Skip to main content

folderbase_core/
root_reconstruction.rs

1//! Bounded planning, retained-capability staging, exact verification, restart,
2//! and no-clobber publication for one root-reconstruction package.
3
4use std::{
5    collections::{BTreeMap, BTreeSet},
6    ffi::{OsStr, OsString},
7    io::{Read, Write},
8    path::{Component, Path, PathBuf},
9};
10
11#[cfg(not(windows))]
12use cap_fs_ext::DirExt;
13use cap_fs_ext::{FollowSymlinks, OpenOptionsFollowExt};
14use cap_std::fs::{Dir, OpenOptions as CapOpenOptions};
15use serde::{
16    Deserialize, Serialize,
17    de::{IgnoredAny, SeqAccess, Visitor},
18};
19use sha2::{Digest, Sha256};
20use uuid::Uuid;
21
22use crate::{
23    FolderbaseCaptureError, FolderbaseError,
24    folderbase_seal::{
25        ReconstructedHistoryClosure, ReconstructedTombstoneAssociation,
26        install_reconstructed_history, prepare_reconstructed_history,
27    },
28    folderbase_state::FolderbaseState,
29    folderbase_version::{
30        DeletedKind, FolderbaseVersion, FolderbaseVersionError, MAX_PATH_BYTES,
31        MAX_PATH_COMPONENT_BYTES, PathBindingKind,
32    },
33    local_versions::{
34        LocalObjectRecord, LocalVersionRecord, LocalVersionStore, ObjectId, ObjectLifecycle,
35        ObjectProvenance, VersionId,
36    },
37    migration_filesystem::{
38        publish_retained_directory_noreplace, require_retained_directory_publication,
39        sync_retained_directory,
40    },
41    physical_identity::PhysicalIdentity,
42    root_attestation::{
43        FolderbaseRootAttestation, ManifestProtocolProfile, RootAttestationError,
44        attest_retained_folderbase_root_with_profile, metadata_is_link_or_reparse,
45        open_root_nofollow,
46    },
47    transfer_manifest::{ChunkManifest, ManifestError, ObjectVerificationError},
48    traversal_policy::is_reserved_workspace_component,
49};
50
51pub const PACKAGE_FORMAT_V1: &str = "folderbase-root-reconstruction-package-v1";
52pub const MAX_PACKAGE_INDEX_BYTES: u64 = 8_388_608;
53pub const MAX_PACKAGE_VERSION_BYTES: u64 = 67_108_864;
54pub const MAX_PACKAGE_MANIFEST_BYTES: u64 = 67_108_864;
55pub const MAX_PACKAGE_REFERENCES: usize = 16_385;
56pub const MAX_DISTINCT_MANIFESTS: usize = 16_385;
57pub const MAX_DISTINCT_CHUNKS: usize = 1_048_576;
58pub const MAX_CHUNKS_PER_MANIFEST: usize = 262_144;
59pub const MAX_PACKAGE_OBJECT_BYTES: u64 = 1_099_511_627_776;
60pub const MAX_TOTAL_OBJECT_BYTES: u64 = 9_007_199_254_740_991;
61pub const MAX_VISIBLE_ENTRIES: usize = 16_384;
62const ACTIVE_RECONSTRUCTION_PATH: &str = ".folderbase/local/root-reconstruction/active.json";
63const COMPLETED_RECONSTRUCTION_PATH: &str = ".folderbase/local/root-reconstruction/completed.json";
64const RECONSTRUCTION_OBJECTS_DIRECTORY: &str = ".folderbase/local/root-reconstruction/objects";
65const MAX_RECONSTRUCTION_RECORD_BYTES: u64 = 64 * 1024;
66const FORCE_UNSUPPORTED_FILESYSTEM_ENV: &str =
67    "FOLDERBASE_ROOT_RECONSTRUCTION_CONFORMANCE_FORCE_UNSUPPORTED_FILESYSTEM";
68const STAGE_OWNERSHIP_FORMAT_V1: &str = "folderbase-root-reconstruction-stage-ownership-v1";
69
70/// One canonical manifest document supplied by the package reader.
71pub struct ManifestInput<R> {
72    chunk_manifest_sha256: String,
73    encoded: R,
74}
75
76impl<R> ManifestInput<R> {
77    pub fn new(chunk_manifest_sha256: impl Into<String>, encoded: R) -> Self {
78        Self {
79            chunk_manifest_sha256: chunk_manifest_sha256.into(),
80            encoded,
81        }
82    }
83
84    pub fn digest(&self) -> &str {
85        &self.chunk_manifest_sha256
86    }
87}
88
89/// One immutable Object Version-to-Chunk Manifest association supplied by a
90/// package producer. Core derives the Object ID and canonical role set from
91/// the exact Folderbase Version; callers cannot author either field.
92#[derive(Debug, Clone, PartialEq, Eq)]
93pub struct RootReconstructionObjectAssociation {
94    object_version_id: String,
95    chunk_manifest_sha256: String,
96}
97
98impl RootReconstructionObjectAssociation {
99    pub fn new(
100        object_version_id: impl Into<String>,
101        chunk_manifest_sha256: impl Into<String>,
102    ) -> Self {
103        Self {
104            object_version_id: object_version_id.into(),
105            chunk_manifest_sha256: chunk_manifest_sha256.into(),
106        }
107    }
108
109    pub fn object_version_id(&self) -> &str {
110        &self.object_version_id
111    }
112
113    pub fn chunk_manifest_sha256(&self) -> &str {
114        &self.chunk_manifest_sha256
115    }
116}
117
118/// Capture-time executable fidelity for one deleted regular file. Core checks
119/// the path and identities against the exact Version and derives no value from
120/// filenames, ambient files, or current process permissions.
121#[derive(Debug, Clone, PartialEq, Eq)]
122pub struct RootReconstructionTombstoneFidelity {
123    path: String,
124    object_id: String,
125    object_version_id: String,
126    executable: bool,
127}
128
129impl RootReconstructionTombstoneFidelity {
130    pub fn new(
131        path: impl Into<String>,
132        object_id: impl Into<String>,
133        object_version_id: impl Into<String>,
134        executable: bool,
135    ) -> Self {
136        Self {
137            path: path.into(),
138            object_id: object_id.into(),
139            object_version_id: object_version_id.into(),
140            executable,
141        }
142    }
143
144    pub fn path(&self) -> &str {
145        &self.path
146    }
147
148    pub fn object_id(&self) -> &str {
149        &self.object_id
150    }
151
152    pub fn object_version_id(&self) -> &str {
153        &self.object_version_id
154    }
155
156    pub fn executable(&self) -> bool {
157        self.executable
158    }
159}
160
161/// Canonical package metadata produced and self-validated by Core. Manifest
162/// and chunk bodies remain caller-owned opaque transfer data.
163#[derive(Debug)]
164pub struct BuiltRootReconstructionPackage {
165    encoded_index: Vec<u8>,
166    encoded_version: Vec<u8>,
167    manifest_digests: Vec<String>,
168    plan: RootReconstructionPlan,
169}
170
171#[derive(Debug, thiserror::Error)]
172pub enum RootReconstructionPackageBuildError {
173    #[error(transparent)]
174    Validation(#[from] RootReconstructionError),
175    #[error("Core could not encode the root reconstruction package index: {0}")]
176    PackageEncoding(#[source] serde_json::Error),
177}
178
179/// Core-derived externally materialized closure for one exact Version. This
180/// lets durable adapters validate and persist the role/object identity mapping
181/// before package bytes are requested, without copying Core's closure rules.
182#[derive(Debug, Clone)]
183pub struct RootReconstructionPackageClosure {
184    encoded_version: Vec<u8>,
185    folderbase_id: String,
186    folderbase_version_id: String,
187    canonical_version_sha256: String,
188    encoded_version_sha256: String,
189    references: Vec<PlannedObjectReference>,
190    tombstone_fidelity: Vec<PlannedTombstoneFidelity>,
191}
192
193impl RootReconstructionPackageClosure {
194    pub fn encoded_version(&self) -> &[u8] {
195        &self.encoded_version
196    }
197
198    pub fn folderbase_id(&self) -> &str {
199        &self.folderbase_id
200    }
201
202    pub fn folderbase_version_id(&self) -> &str {
203        &self.folderbase_version_id
204    }
205
206    pub fn canonical_version_sha256(&self) -> &str {
207        &self.canonical_version_sha256
208    }
209
210    pub fn encoded_version_sha256(&self) -> &str {
211        &self.encoded_version_sha256
212    }
213
214    pub fn references(&self) -> &[PlannedObjectReference] {
215        &self.references
216    }
217
218    pub fn tombstone_fidelity(&self) -> &[PlannedTombstoneFidelity] {
219        &self.tombstone_fidelity
220    }
221}
222
223impl BuiltRootReconstructionPackage {
224    pub fn encoded_index(&self) -> &[u8] {
225        &self.encoded_index
226    }
227
228    pub fn encoded_version(&self) -> &[u8] {
229        &self.encoded_version
230    }
231
232    pub fn manifest_digests(&self) -> &[String] {
233        &self.manifest_digests
234    }
235
236    pub fn plan(&self) -> &RootReconstructionPlan {
237        &self.plan
238    }
239}
240
241#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
242pub enum ReconstructionReferenceRole {
243    RootManifest,
244    LiveRegularFile,
245    RetainedTombstone,
246}
247
248#[derive(Debug, Clone, PartialEq, Eq)]
249pub struct PlannedObjectReference {
250    object_version_id: String,
251    object_id: Option<String>,
252    roles: Vec<ReconstructionReferenceRole>,
253    chunk_manifest_sha256: String,
254}
255
256impl PlannedObjectReference {
257    pub fn object_version_id(&self) -> &str {
258        &self.object_version_id
259    }
260
261    pub fn object_id(&self) -> Option<&str> {
262        self.object_id.as_deref()
263    }
264
265    pub fn roles(&self) -> &[ReconstructionReferenceRole] {
266        &self.roles
267    }
268
269    pub fn chunk_manifest_sha256(&self) -> &str {
270        &self.chunk_manifest_sha256
271    }
272}
273
274#[derive(Debug, Clone, PartialEq, Eq)]
275pub struct PlannedManifest {
276    chunk_manifest_sha256: String,
277    object_sha256: String,
278    object_bytes: u64,
279    chunk_count: usize,
280}
281
282impl PlannedManifest {
283    pub fn chunk_manifest_sha256(&self) -> &str {
284        &self.chunk_manifest_sha256
285    }
286
287    pub fn object_sha256(&self) -> &str {
288        &self.object_sha256
289    }
290
291    pub fn object_bytes(&self) -> u64 {
292        self.object_bytes
293    }
294
295    pub fn chunk_count(&self) -> usize {
296        self.chunk_count
297    }
298}
299
300#[derive(Debug, Clone, PartialEq, Eq)]
301pub struct DerivedSymlink {
302    path: String,
303    object_id: String,
304    object_version_id: String,
305    target: String,
306    content_sha256: String,
307    bytes: u64,
308}
309
310#[derive(Debug, Clone, PartialEq, Eq)]
311pub struct PlannedTombstoneFidelity {
312    path: String,
313    object_id: String,
314    object_version_id: String,
315    executable: bool,
316}
317
318impl PlannedTombstoneFidelity {
319    pub fn path(&self) -> &str {
320        &self.path
321    }
322
323    pub fn object_id(&self) -> &str {
324        &self.object_id
325    }
326
327    pub fn object_version_id(&self) -> &str {
328        &self.object_version_id
329    }
330
331    pub fn executable(&self) -> bool {
332        self.executable
333    }
334}
335
336impl DerivedSymlink {
337    pub fn path(&self) -> &str {
338        &self.path
339    }
340
341    pub fn object_id(&self) -> &str {
342        &self.object_id
343    }
344
345    pub fn object_version_id(&self) -> &str {
346        &self.object_version_id
347    }
348
349    pub fn target(&self) -> &str {
350        &self.target
351    }
352
353    pub fn content_sha256(&self) -> &str {
354        &self.content_sha256
355    }
356
357    pub fn bytes(&self) -> u64 {
358        self.bytes
359    }
360}
361
362#[derive(Debug)]
363pub struct RootReconstructionPlan {
364    package_index_sha256: String,
365    encoded_version_sha256: String,
366    canonical_version_sha256: String,
367    version: FolderbaseVersion,
368    references: Vec<PlannedObjectReference>,
369    manifests: Vec<PlannedManifest>,
370    derived_symlinks: Vec<DerivedSymlink>,
371    tombstone_fidelity: Vec<PlannedTombstoneFidelity>,
372    distinct_chunk_count: usize,
373    total_object_bytes: u64,
374}
375
376/// One stable execution identity bound to an already-validated plan.
377pub struct RootReconstructionOperation<'a> {
378    plan: &'a RootReconstructionPlan,
379    operation_id: String,
380    request_sha256: String,
381}
382
383impl<'a> RootReconstructionOperation<'a> {
384    pub fn new(
385        plan: &'a RootReconstructionPlan,
386        operation_id: impl Into<String>,
387        package_index_sha256: impl Into<String>,
388    ) -> Result<Self, RootReconstructionError> {
389        let operation_id = operation_id.into();
390        let package_index_sha256 = package_index_sha256.into();
391        let Some(uuid) = operation_id.strip_prefix("reconstruction_") else {
392            return Err(RootReconstructionError::InvalidOperation);
393        };
394        let parsed =
395            Uuid::parse_str(uuid).map_err(|_| RootReconstructionError::InvalidOperation)?;
396        if parsed.hyphenated().to_string() != uuid || !(1..=8).contains(&parsed.get_version_num()) {
397            return Err(RootReconstructionError::InvalidOperation);
398        }
399        if package_index_sha256 != plan.package_index_sha256() {
400            return Err(RootReconstructionError::PackageIndexPinMismatch);
401        }
402        let request_sha256 =
403            root_reconstruction_request_sha256(&operation_id, &package_index_sha256)?;
404        Ok(Self {
405            plan,
406            operation_id,
407            request_sha256,
408        })
409    }
410
411    pub fn request_sha256(&self) -> &str {
412        &self.request_sha256
413    }
414}
415
416#[derive(Debug, Clone, Copy, PartialEq, Eq)]
417pub enum RootReconstructionPhase {
418    StageEntryDurable,
419    PreparedJournal,
420    VerifiedStaging,
421    Publication,
422    CompletionDurable,
423}
424
425/// A retained, no-follow package root. Its path is diagnostic-only after open.
426pub struct RetainedReconstructionPackage {
427    root: Dir,
428    display_root: PathBuf,
429}
430
431struct ValidatedPackage {
432    manifests: BTreeMap<String, ChunkManifest>,
433    _manifests_directory: Dir,
434    chunks_directory: Dir,
435    index_identity: PhysicalIdentity,
436    version_identity: PhysicalIdentity,
437    manifests_directory_identity: PhysicalIdentity,
438    chunks_directory_identity: PhysicalIdentity,
439    manifest_identities: BTreeMap<String, PhysicalIdentity>,
440    chunk_identities: BTreeMap<String, PackageRegularIdentity>,
441}
442
443#[derive(Clone, Copy, PartialEq, Eq)]
444struct PackageRegularIdentity {
445    physical: PhysicalIdentity,
446    bytes: u64,
447}
448
449impl RetainedReconstructionPackage {
450    pub fn open(root: impl AsRef<Path>) -> Result<Self, RootReconstructionError> {
451        let display_root = root.as_ref().to_path_buf();
452        let file =
453            open_root_nofollow(&display_root).map_err(|source| RootReconstructionError::Io {
454                path: display_root.clone(),
455                source,
456            })?;
457        let metadata = file
458            .metadata()
459            .map_err(|source| RootReconstructionError::Io {
460                path: display_root.clone(),
461                source,
462            })?;
463        if metadata_is_link_or_reparse(&metadata) || !metadata.is_dir() {
464            return Err(RootReconstructionError::UnsafePackage(display_root));
465        }
466        #[cfg(unix)]
467        {
468            use std::os::unix::fs::PermissionsExt;
469            if metadata.permissions().mode() & 0o022 != 0 {
470                return Err(RootReconstructionError::UnsafePackage(display_root));
471            }
472        }
473        let root = Dir::from_std_file(file);
474        Ok(Self { root, display_root })
475    }
476}
477
478/// A retained parent plus one validated destination leaf. The leaf may be
479/// absent for a new reconstruction or occupied for exact replay/no-clobber
480/// classification.
481pub struct RetainedReconstructionDestination {
482    parent: Dir,
483    display_parent: PathBuf,
484    name: OsString,
485}
486
487impl RetainedReconstructionDestination {
488    pub fn open(
489        parent: impl AsRef<Path>,
490        name: impl AsRef<OsStr>,
491    ) -> Result<Self, RootReconstructionError> {
492        Self::open_with_preflight(
493            parent.as_ref(),
494            name.as_ref(),
495            std::env::var_os(FORCE_UNSUPPORTED_FILESYSTEM_ENV).is_some(),
496        )
497    }
498
499    fn open_with_preflight(
500        parent: &Path,
501        name: &OsStr,
502        force_unsupported: bool,
503    ) -> Result<Self, RootReconstructionError> {
504        let display_parent = parent.to_path_buf();
505        if force_unsupported {
506            return Err(
507                RootReconstructionError::UnsupportedReconstructionFilesystem {
508                    path: display_parent,
509                    reason: "conformance seam forced unsupported reconstruction filesystem"
510                        .to_owned(),
511                },
512            );
513        }
514        let name = name.to_os_string();
515        if name.is_empty()
516            || Path::new(&name).components().count() != 1
517            || !matches!(
518                Path::new(&name).components().next(),
519                Some(Component::Normal(_))
520            )
521        {
522            return Err(RootReconstructionError::InvalidDestination);
523        }
524        let file =
525            open_root_nofollow(&display_parent).map_err(|source| RootReconstructionError::Io {
526                path: display_parent.clone(),
527                source,
528            })?;
529        let metadata = file
530            .metadata()
531            .map_err(|source| RootReconstructionError::Io {
532                path: display_parent.clone(),
533                source,
534            })?;
535        if metadata_is_link_or_reparse(&metadata) || !metadata.is_dir() {
536            return Err(RootReconstructionError::InvalidDestination);
537        }
538        let parent = Dir::from_std_file(file);
539        match parent.symlink_metadata(&name) {
540            Err(source) if source.kind() == std::io::ErrorKind::NotFound => {
541                require_retained_directory_publication(&parent, &display_parent)
542                    .map_err(|error| unsupported_publication_error(error, &display_parent))?;
543            }
544            Ok(_) => {}
545            Err(source) => {
546                return Err(RootReconstructionError::Io {
547                    path: display_parent.join(&name),
548                    source,
549                });
550            }
551        }
552        Ok(Self {
553            parent,
554            display_parent,
555            name,
556        })
557    }
558}
559
560#[derive(Debug, Clone)]
561pub struct RootReconstructionResult {
562    replayed: bool,
563    attestation: FolderbaseRootAttestation,
564}
565
566impl RootReconstructionResult {
567    pub fn replayed(&self) -> bool {
568        self.replayed
569    }
570
571    pub fn attestation(&self) -> &FolderbaseRootAttestation {
572        &self.attestation
573    }
574}
575
576#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
577#[serde(deny_unknown_fields)]
578struct ReconstructionRecord {
579    format: String,
580    operation_id: String,
581    request_sha256: String,
582    package_index_sha256: String,
583    folderbase_id: String,
584    folderbase_version_id: String,
585    canonical_version_sha256: String,
586    visible_entries: usize,
587    external_objects: usize,
588}
589
590#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
591#[serde(deny_unknown_fields)]
592struct ReconstructionCompletion {
593    #[serde(flatten)]
594    operation: ReconstructionRecord,
595    root_instance_sha256: String,
596    manifest_sha256: String,
597}
598
599#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
600#[serde(deny_unknown_fields)]
601struct StageOwnershipRecord {
602    format: String,
603    operation: ReconstructionRecord,
604    staged_name: String,
605    phase: StageOwnershipPhase,
606    physical_identity_sha256: Option<String>,
607}
608
609#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
610#[serde(rename_all = "snake_case")]
611enum StageOwnershipPhase {
612    IntentDurable,
613    StageOwned,
614}
615
616impl RootReconstructionPlan {
617    pub fn package_index_sha256(&self) -> &str {
618        &self.package_index_sha256
619    }
620
621    pub fn encoded_version_sha256(&self) -> &str {
622        &self.encoded_version_sha256
623    }
624
625    pub fn canonical_version_sha256(&self) -> &str {
626        &self.canonical_version_sha256
627    }
628
629    pub fn version(&self) -> &FolderbaseVersion {
630        &self.version
631    }
632
633    pub fn references(&self) -> &[PlannedObjectReference] {
634        &self.references
635    }
636
637    pub fn manifests(&self) -> &[PlannedManifest] {
638        &self.manifests
639    }
640
641    pub fn derived_symlinks(&self) -> &[DerivedSymlink] {
642        &self.derived_symlinks
643    }
644
645    pub fn tombstone_fidelity(&self) -> &[PlannedTombstoneFidelity] {
646        &self.tombstone_fidelity
647    }
648
649    pub fn externally_materialized_object_count(&self) -> usize {
650        self.references.len()
651    }
652
653    pub fn visible_entry_count(&self) -> usize {
654        self.version.binding_count()
655    }
656
657    pub fn distinct_chunk_count(&self) -> usize {
658        self.distinct_chunk_count
659    }
660
661    pub fn total_object_bytes(&self) -> u64 {
662        self.total_object_bytes
663    }
664}
665
666#[derive(Debug, thiserror::Error)]
667pub enum RootReconstructionError {
668    #[error("root reconstruction operation identity is invalid")]
669    InvalidOperation,
670    #[error("root reconstruction package-index pin differs from the validated plan")]
671    PackageIndexPinMismatch,
672    #[error("root reconstruction destination leaf is invalid")]
673    InvalidDestination,
674    #[error("root reconstruction destination is occupied: {0}")]
675    DestinationOccupied(PathBuf),
676    #[error("root reconstruction operation conflicts with retained state")]
677    OperationConflict,
678    #[error("root reconstruction package changed at {0}")]
679    PackageChanged(PathBuf),
680    #[error("root reconstruction package is unsafe at {0}")]
681    UnsafePackage(PathBuf),
682    #[error("root reconstruction filesystem is unsupported at {path}: {reason}")]
683    UnsupportedReconstructionFilesystem { path: PathBuf, reason: String },
684    #[error("root reconstruction filesystem operation failed: {0}")]
685    Filesystem(#[from] FolderbaseError),
686    #[error("root reconstruction history installation failed: {0}")]
687    History(#[from] FolderbaseCaptureError),
688    #[error("reconstructed root attestation failed: {0}")]
689    Attestation(#[from] RootAttestationError),
690    #[error("root reconstruction object verification failed: {0}")]
691    ObjectVerification(#[from] ObjectVerificationError),
692    #[error("root reconstruction I/O failed at {path}: {source}")]
693    Io {
694        path: PathBuf,
695        #[source]
696        source: std::io::Error,
697    },
698    #[error("package index input failed: {0}")]
699    IndexReader(#[source] std::io::Error),
700    #[error("encoded package index exceeds {maximum_bytes} bytes")]
701    IndexTooLarge { maximum_bytes: u64 },
702    #[error("package index is not valid closed JSON: {0}")]
703    InvalidIndexJson(#[source] serde_json::Error),
704    #[error("package index limit declaration is not the fixed v1 declaration")]
705    LimitsMismatch,
706    #[error("package index format is unsupported")]
707    UnknownFormat,
708    #[error("package index contains more than {maximum} references")]
709    TooManyReferences { maximum: usize },
710    #[error("Folderbase Version input failed: {0}")]
711    VersionReader(#[source] std::io::Error),
712    #[error("encoded Folderbase Version exceeds {maximum_bytes} bytes")]
713    VersionTooLarge { maximum_bytes: u64 },
714    #[error("Folderbase Version is invalid: {0}")]
715    InvalidVersion(#[source] FolderbaseVersionError),
716    #[error("package index Folderbase identity differs from the Version")]
717    FolderbaseIdMismatch,
718    #[error("package index Folderbase Version identity differs from the Version")]
719    VersionIdMismatch,
720    #[error("encoded Folderbase Version digest differs from the package index")]
721    EncodedVersionDigestMismatch,
722    #[error("canonical Folderbase Version digest differs from the package index")]
723    CanonicalVersionDigestMismatch,
724    #[error("package references are not strictly ordered by Object Version ID")]
725    ReferencesOutOfOrder,
726    #[error("package contains duplicate Object Version reference {object_version_id}")]
727    DuplicateReference { object_version_id: String },
728    #[error("package reference {object_version_id} has a noncanonical role set")]
729    InvalidReferenceRoles { object_version_id: String },
730    #[error("package reference {object_version_id} is not in the Version closure")]
731    UnexpectedReference { object_version_id: String },
732    #[error("Version closure reference {object_version_id} is missing")]
733    MissingReference { object_version_id: String },
734    #[error("package reference {object_version_id} differs from the Version closure")]
735    ReferenceMismatch { object_version_id: String },
736    #[error("package reference {object_version_id} has an invalid manifest digest")]
737    InvalidManifestDigest { object_version_id: String },
738    #[error("package contains more than {maximum} manifest documents")]
739    TooManyManifests { maximum: usize },
740    #[error("manifest {chunk_manifest_sha256} is not referenced by the Version closure")]
741    UnreferencedManifest { chunk_manifest_sha256: String },
742    #[error("manifest {chunk_manifest_sha256} is supplied more than once")]
743    DuplicateManifest { chunk_manifest_sha256: String },
744    #[error("referenced manifest {chunk_manifest_sha256} is missing")]
745    MissingManifest { chunk_manifest_sha256: String },
746    #[error("manifest {chunk_manifest_sha256} is invalid: {source}")]
747    InvalidManifest {
748        chunk_manifest_sha256: String,
749        #[source]
750        source: ManifestError,
751    },
752    #[error("manifest document does not match its canonical digest {chunk_manifest_sha256}")]
753    ManifestDigestMismatch { chunk_manifest_sha256: String },
754    #[error("package manifests reference more than {maximum} distinct chunks")]
755    TooManyDistinctChunks { maximum: usize },
756    #[error("manifest for {object_version_id} differs from the Version-bound object")]
757    ManifestObjectMismatch { object_version_id: String },
758    #[error("package object bytes exceed the aggregate v1 maximum of {maximum}")]
759    TotalObjectBytesTooLarge { maximum: u64 },
760    #[error("package Tombstone fidelity closure differs from the Folderbase Version")]
761    TombstoneFidelityMismatch,
762}
763
764/// Execute or exactly replay one reconstruction operation.
765///
766/// All staging and publication is rooted in retained capabilities. The final
767/// public destination appears only through one atomic no-replace directory
768/// rename after bytes, history, Local Head, attestation, and completion have
769/// all verified.
770pub fn execute_root_reconstruction(
771    operation: RootReconstructionOperation<'_>,
772    package: &RetainedReconstructionPackage,
773    destination: &RetainedReconstructionDestination,
774) -> Result<RootReconstructionResult, RootReconstructionError> {
775    execute_root_reconstruction_with_phase_callback(operation, package, destination, |_| {})
776}
777
778#[doc(hidden)]
779pub fn execute_root_reconstruction_with_phase_callback<F>(
780    operation: RootReconstructionOperation<'_>,
781    package: &RetainedReconstructionPackage,
782    destination: &RetainedReconstructionDestination,
783    mut phase: F,
784) -> Result<RootReconstructionResult, RootReconstructionError>
785where
786    F: FnMut(RootReconstructionPhase),
787{
788    let record = reconstruction_record(&operation);
789
790    if let Some(root) = open_directory_if_present(
791        &destination.parent,
792        &destination.name,
793        &destination.display_parent.join(&destination.name),
794    )? {
795        return replay_published_root(&root, destination, &record);
796    }
797    require_package_destination_separation(package, destination)?;
798    let validated_package = revalidate_package(package, operation.plan)?;
799
800    let staged_name = staged_root_name(&operation.operation_id);
801    let staged_display = destination.display_parent.join(&staged_name);
802    let owner_name = stage_owner_name(&operation.operation_id);
803    let (staged, ownership) = acquire_owned_stage(
804        destination,
805        &staged_name,
806        &owner_name,
807        &staged_display,
808        &record,
809        &mut phase,
810    )?;
811
812    ensure_directory(&staged, Path::new(".folderbase"), &staged_display)?;
813    let state = FolderbaseState::from_retained_root(&staged, &staged_display)?;
814    state.ensure_private_dir(Path::new(".folderbase/local/root-reconstruction"))?;
815    state.ensure_private_dir(Path::new(RECONSTRUCTION_OBJECTS_DIRECTORY))?;
816    install_exact_record(&state, Path::new(ACTIVE_RECONSTRUCTION_PATH), &record)?;
817    phase(RootReconstructionPhase::PreparedJournal);
818    require_same_package_identity(
819        package,
820        &validated_package,
821        &revalidate_package(package, operation.plan)?,
822    )?;
823    prepare_reconstructed_history(&state)?;
824
825    let local = LocalVersionStore::for_retained_root(&staged_display);
826    let history = materialize_reconstruction(
827        &staged,
828        &staged_display,
829        &state,
830        &local,
831        package,
832        operation.plan,
833        &validated_package,
834    )?;
835    let (attestation, _, profile) =
836        attest_retained_folderbase_root_with_profile(&staged, &staged_display)?;
837    if attestation.folderbase_id != operation.plan.version().folderbase_id() {
838        return Err(RootReconstructionError::OperationConflict);
839    }
840    require_matching_protocol_profile(operation.plan.version(), &profile)?;
841    install_reconstructed_history(
842        &local,
843        &state,
844        &attestation,
845        operation.plan.version(),
846        operation.plan.canonical_version_sha256(),
847        &history,
848    )?;
849    require_same_package_identity(
850        package,
851        &validated_package,
852        &revalidate_package(package, operation.plan)?,
853    )?;
854    verify_visible_tree(&staged, &staged_display, operation.plan.version())?;
855    phase(RootReconstructionPhase::VerifiedStaging);
856    let verified = attest_retained_folderbase_root_with_profile(&staged, &staged_display)?.0;
857    let completion = ReconstructionCompletion {
858        operation: record.clone(),
859        root_instance_sha256: verified.root_instance_sha256.clone(),
860        manifest_sha256: verified.manifest_sha256.clone(),
861    };
862    install_exact_record(
863        &state,
864        Path::new(COMPLETED_RECONSTRUCTION_PATH),
865        &completion,
866    )?;
867
868    publish_retained_directory_noreplace(
869        &destination.parent,
870        &staged_name,
871        &destination.name,
872        &destination.display_parent,
873    )
874    .map_err(|error| match error {
875        FolderbaseError::WouldOverwrite(path) => RootReconstructionError::DestinationOccupied(path),
876        error => RootReconstructionError::Filesystem(error),
877    })?;
878    let final_display = destination.display_parent.join(&destination.name);
879    let published_root =
880        open_directory_if_present(&destination.parent, &destination.name, &final_display)?
881            .ok_or(RootReconstructionError::OperationConflict)?;
882    if Some(directory_identity_sha256(&published_root, &final_display)?)
883        != ownership.physical_identity_sha256
884    {
885        return Err(RootReconstructionError::OperationConflict);
886    }
887    verify_visible_tree(&published_root, &final_display, operation.plan.version())?;
888    let final_attestation =
889        attest_retained_folderbase_root_with_profile(&published_root, &final_display)?.0;
890    if final_attestation.root_instance_sha256 != completion.root_instance_sha256
891        || final_attestation.manifest_sha256 != completion.manifest_sha256
892    {
893        return Err(RootReconstructionError::OperationConflict);
894    }
895    phase(RootReconstructionPhase::Publication);
896    retire_stage_owner(destination, &owner_name, &ownership, &published_root)?;
897    phase(RootReconstructionPhase::CompletionDurable);
898    Ok(RootReconstructionResult {
899        replayed: false,
900        attestation: final_attestation,
901    })
902}
903
904fn require_package_destination_separation(
905    package: &RetainedReconstructionPackage,
906    destination: &RetainedReconstructionDestination,
907) -> Result<(), RootReconstructionError> {
908    let package_identity = cap_directory_identity(&package.root, &package.display_root)?;
909    let destination_identity =
910        cap_directory_identity(&destination.parent, &destination.display_parent)?;
911    let package_canonical = canonical_retained_directory(
912        &package.root,
913        &package.display_root,
914        RootReconstructionError::PackageChanged(package.display_root.clone()),
915    )?;
916    let destination_canonical = canonical_retained_directory(
917        &destination.parent,
918        &destination.display_parent,
919        RootReconstructionError::InvalidDestination,
920    )?;
921    if package_identity == destination_identity
922        || physical_ancestor_chain_contains(&package_canonical, destination_identity)?
923        || physical_ancestor_chain_contains(&destination_canonical, package_identity)?
924    {
925        return Err(RootReconstructionError::InvalidDestination);
926    }
927    Ok(())
928}
929
930fn canonical_retained_directory(
931    directory: &Dir,
932    display: &Path,
933    mismatch: RootReconstructionError,
934) -> Result<PathBuf, RootReconstructionError> {
935    let canonical =
936        std::fs::canonicalize(display).map_err(|source| RootReconstructionError::Io {
937            path: display.to_path_buf(),
938            source,
939        })?;
940    let canonical_identity =
941        PhysicalIdentity::from_path(&canonical).map_err(|source| RootReconstructionError::Io {
942            path: canonical.clone(),
943            source,
944        })?;
945    if canonical_identity != cap_directory_identity(directory, display)? {
946        return Err(mismatch);
947    }
948    Ok(canonical)
949}
950
951fn physical_ancestor_chain_contains(
952    descendant: &Path,
953    ancestor_identity: PhysicalIdentity,
954) -> Result<bool, RootReconstructionError> {
955    for candidate in descendant.ancestors() {
956        let identity = PhysicalIdentity::from_path(candidate).map_err(|source| {
957            RootReconstructionError::Io {
958                path: candidate.to_path_buf(),
959                source,
960            }
961        })?;
962        if identity == ancestor_identity {
963            return Ok(true);
964        }
965    }
966    Ok(false)
967}
968
969fn reconstruction_record(operation: &RootReconstructionOperation<'_>) -> ReconstructionRecord {
970    ReconstructionRecord {
971        format: "folderbase-root-reconstruction-operation-v1".to_owned(),
972        operation_id: operation.operation_id.clone(),
973        request_sha256: operation.request_sha256.clone(),
974        package_index_sha256: operation.plan.package_index_sha256().to_owned(),
975        folderbase_id: operation.plan.version().folderbase_id().to_owned(),
976        folderbase_version_id: operation.plan.version().version_id().to_owned(),
977        canonical_version_sha256: operation.plan.canonical_version_sha256().to_owned(),
978        visible_entries: operation.plan.visible_entry_count(),
979        external_objects: operation.plan.externally_materialized_object_count(),
980    }
981}
982
983fn require_matching_protocol_profile(
984    version: &FolderbaseVersion,
985    profile: &ManifestProtocolProfile,
986) -> Result<(), RootReconstructionError> {
987    let matches = matches!(
988        (version.protocol_version(), profile),
989        ("0.4", ManifestProtocolProfile::LegacyV01V02)
990            | ("0.5", ManifestProtocolProfile::OrdinaryV05 { .. })
991    );
992    if matches {
993        Ok(())
994    } else {
995        Err(RootReconstructionError::OperationConflict)
996    }
997}
998
999fn unsupported_publication_error(
1000    error: FolderbaseError,
1001    display: &Path,
1002) -> RootReconstructionError {
1003    match error {
1004        FolderbaseError::UnsupportedMigrationFilesystem { reason, .. } => {
1005            RootReconstructionError::UnsupportedReconstructionFilesystem {
1006                path: display.to_path_buf(),
1007                reason,
1008            }
1009        }
1010        error => RootReconstructionError::Filesystem(error),
1011    }
1012}
1013
1014fn staged_root_name(operation_id: &str) -> OsString {
1015    OsString::from(format!(
1016        ".folderbase-reconstruction-{}.stage",
1017        operation_id
1018            .strip_prefix("reconstruction_")
1019            .expect("validated operation ID")
1020    ))
1021}
1022
1023fn stage_owner_name(operation_id: &str) -> OsString {
1024    OsString::from(format!(
1025        ".folderbase-reconstruction-{}.owner.json",
1026        operation_id
1027            .strip_prefix("reconstruction_")
1028            .expect("validated operation ID")
1029    ))
1030}
1031
1032fn stage_proof_name(operation_id: &str) -> OsString {
1033    OsString::from(format!(
1034        ".folderbase-reconstruction-{}.stage-owned.json",
1035        operation_id
1036            .strip_prefix("reconstruction_")
1037            .expect("validated operation ID")
1038    ))
1039}
1040
1041fn acquire_owned_stage<F>(
1042    destination: &RetainedReconstructionDestination,
1043    staged_name: &OsStr,
1044    owner_name: &OsStr,
1045    staged_display: &Path,
1046    operation: &ReconstructionRecord,
1047    phase: &mut F,
1048) -> Result<(Dir, StageOwnershipRecord), RootReconstructionError>
1049where
1050    F: FnMut(RootReconstructionPhase),
1051{
1052    let owner_display = destination.display_parent.join(owner_name);
1053    let proof_name = stage_proof_name(&operation.operation_id);
1054    let proof_display = destination.display_parent.join(&proof_name);
1055    let expected_intent = StageOwnershipRecord {
1056        format: STAGE_OWNERSHIP_FORMAT_V1.to_owned(),
1057        operation: operation.clone(),
1058        staged_name: staged_name.to_string_lossy().into_owned(),
1059        phase: StageOwnershipPhase::IntentDurable,
1060        physical_identity_sha256: None,
1061    };
1062    let intent = read_parent_regular(
1063        &destination.parent,
1064        owner_name,
1065        &owner_display,
1066        MAX_RECONSTRUCTION_RECORD_BYTES,
1067    )?;
1068    if let Some(encoded) = intent.as_deref() {
1069        require_exact_stage_ownership(encoded, &expected_intent)?;
1070    } else {
1071        if read_parent_regular(
1072            &destination.parent,
1073            &proof_name,
1074            &proof_display,
1075            MAX_RECONSTRUCTION_RECORD_BYTES,
1076        )?
1077        .is_some()
1078            || open_owned_stage_if_present(destination, staged_name, staged_display)?.is_some()
1079        {
1080            return Err(RootReconstructionError::OperationConflict);
1081        }
1082        write_parent_new(
1083            &destination.parent,
1084            owner_name,
1085            &owner_display,
1086            &destination.display_parent,
1087            &serde_json::to_vec(&expected_intent)
1088                .map_err(|_| RootReconstructionError::OperationConflict)?,
1089        )?;
1090    }
1091
1092    let stage = open_owned_stage_if_present(destination, staged_name, staged_display)?;
1093    let proof = read_parent_regular(
1094        &destination.parent,
1095        &proof_name,
1096        &proof_display,
1097        MAX_RECONSTRUCTION_RECORD_BYTES,
1098    )?;
1099    match (stage, proof) {
1100        (None, None) => {
1101            destination
1102                .parent
1103                .create_dir(staged_name)
1104                .map_err(|source| RootReconstructionError::Io {
1105                    path: staged_display.to_path_buf(),
1106                    source,
1107                })?;
1108            sync_retained_directory(&destination.parent, &destination.display_parent)?;
1109            let staged = open_owned_stage_if_present(destination, staged_name, staged_display)?
1110                .ok_or(RootReconstructionError::OperationConflict)?;
1111            phase(RootReconstructionPhase::StageEntryDurable);
1112            let ownership = persist_stage_ownership(
1113                destination,
1114                &staged,
1115                staged_name,
1116                staged_display,
1117                &proof_name,
1118                &proof_display,
1119                operation,
1120            )?;
1121            Ok((staged, ownership))
1122        }
1123        (Some(staged), None) => {
1124            let ownership = persist_stage_ownership(
1125                destination,
1126                &staged,
1127                staged_name,
1128                staged_display,
1129                &proof_name,
1130                &proof_display,
1131                operation,
1132            )?;
1133            Ok((staged, ownership))
1134        }
1135        (Some(staged), Some(encoded)) => {
1136            let ownership = decode_stage_ownership(&encoded)?;
1137            let actual_identity = directory_identity_sha256(&staged, staged_display)?;
1138            if ownership.format != STAGE_OWNERSHIP_FORMAT_V1
1139                || ownership.operation != *operation
1140                || ownership.staged_name != staged_name.to_string_lossy()
1141                || ownership.phase != StageOwnershipPhase::StageOwned
1142                || ownership.physical_identity_sha256.as_deref() != Some(actual_identity.as_str())
1143            {
1144                return Err(RootReconstructionError::OperationConflict);
1145            }
1146            Ok((staged, ownership))
1147        }
1148        _ => Err(RootReconstructionError::OperationConflict),
1149    }
1150}
1151
1152fn persist_stage_ownership(
1153    destination: &RetainedReconstructionDestination,
1154    staged: &Dir,
1155    staged_name: &OsStr,
1156    staged_display: &Path,
1157    proof_name: &OsStr,
1158    proof_display: &Path,
1159    operation: &ReconstructionRecord,
1160) -> Result<StageOwnershipRecord, RootReconstructionError> {
1161    let ownership = StageOwnershipRecord {
1162        format: STAGE_OWNERSHIP_FORMAT_V1.to_owned(),
1163        operation: operation.clone(),
1164        staged_name: staged_name.to_string_lossy().into_owned(),
1165        phase: StageOwnershipPhase::StageOwned,
1166        physical_identity_sha256: Some(directory_identity_sha256(staged, staged_display)?),
1167    };
1168    write_parent_new(
1169        &destination.parent,
1170        proof_name,
1171        proof_display,
1172        &destination.display_parent,
1173        &serde_json::to_vec(&ownership).map_err(|_| RootReconstructionError::OperationConflict)?,
1174    )?;
1175    Ok(ownership)
1176}
1177
1178fn open_owned_stage_if_present(
1179    destination: &RetainedReconstructionDestination,
1180    staged_name: &OsStr,
1181    staged_display: &Path,
1182) -> Result<Option<Dir>, RootReconstructionError> {
1183    match open_directory_if_present(&destination.parent, staged_name, staged_display) {
1184        Err(RootReconstructionError::DestinationOccupied(_)) => {
1185            Err(RootReconstructionError::OperationConflict)
1186        }
1187        result => result,
1188    }
1189}
1190
1191fn decode_stage_ownership(encoded: &[u8]) -> Result<StageOwnershipRecord, RootReconstructionError> {
1192    let record: StageOwnershipRecord =
1193        serde_json::from_slice(encoded).map_err(|_| RootReconstructionError::OperationConflict)?;
1194    if serde_json::to_vec(&record).ok().as_deref() != Some(encoded) {
1195        return Err(RootReconstructionError::OperationConflict);
1196    }
1197    Ok(record)
1198}
1199
1200fn require_exact_stage_ownership(
1201    encoded: &[u8],
1202    expected: &StageOwnershipRecord,
1203) -> Result<(), RootReconstructionError> {
1204    if decode_stage_ownership(encoded)? == *expected {
1205        Ok(())
1206    } else {
1207        Err(RootReconstructionError::OperationConflict)
1208    }
1209}
1210
1211fn directory_identity_sha256(
1212    directory: &Dir,
1213    display: &Path,
1214) -> Result<String, RootReconstructionError> {
1215    cap_directory_identity(directory, display).map(PhysicalIdentity::stable_sha256)
1216}
1217
1218fn cap_directory_identity(
1219    directory: &Dir,
1220    display: &Path,
1221) -> Result<PhysicalIdentity, RootReconstructionError> {
1222    let file = directory
1223        .try_clone()
1224        .map_err(|source| RootReconstructionError::Io {
1225            path: display.to_path_buf(),
1226            source,
1227        })?
1228        .into_std_file();
1229    PhysicalIdentity::from_file(&file).map_err(|source| RootReconstructionError::Io {
1230        path: display.to_path_buf(),
1231        source,
1232    })
1233}
1234
1235fn read_parent_regular(
1236    parent: &Dir,
1237    name: &OsStr,
1238    display: &Path,
1239    maximum: u64,
1240) -> Result<Option<Vec<u8>>, RootReconstructionError> {
1241    let mut options = CapOpenOptions::new();
1242    options.read(true).follow(FollowSymlinks::No);
1243    let mut file = match parent.open_with(name, &options) {
1244        Ok(file) => file,
1245        Err(source) if source.kind() == std::io::ErrorKind::NotFound => return Ok(None),
1246        Err(source) => {
1247            return Err(RootReconstructionError::Io {
1248                path: display.to_path_buf(),
1249                source,
1250            });
1251        }
1252    };
1253    let metadata = file
1254        .metadata()
1255        .map_err(|source| RootReconstructionError::Io {
1256            path: display.to_path_buf(),
1257            source,
1258        })?;
1259    if metadata.file_type().is_symlink() || !metadata.is_file() || metadata.len() > maximum {
1260        return Err(RootReconstructionError::OperationConflict);
1261    }
1262    let mut encoded = Vec::new();
1263    Read::by_ref(&mut file)
1264        .take(maximum.saturating_add(1))
1265        .read_to_end(&mut encoded)
1266        .map_err(|source| RootReconstructionError::Io {
1267            path: display.to_path_buf(),
1268            source,
1269        })?;
1270    if encoded.len() as u64 > maximum {
1271        return Err(RootReconstructionError::OperationConflict);
1272    }
1273    Ok(Some(encoded))
1274}
1275
1276fn write_parent_new(
1277    parent: &Dir,
1278    name: &OsStr,
1279    display: &Path,
1280    parent_display: &Path,
1281    encoded: &[u8],
1282) -> Result<(), RootReconstructionError> {
1283    let mut options = CapOpenOptions::new();
1284    options
1285        .write(true)
1286        .create_new(true)
1287        .follow(FollowSymlinks::No);
1288    let mut file =
1289        parent
1290            .open_with(name, &options)
1291            .map_err(|source| RootReconstructionError::Io {
1292                path: display.to_path_buf(),
1293                source,
1294            })?;
1295    file.write_all(encoded)
1296        .and_then(|()| file.sync_all())
1297        .map_err(|source| RootReconstructionError::Io {
1298            path: display.to_path_buf(),
1299            source,
1300        })?;
1301    sync_retained_directory(parent, parent_display)?;
1302    Ok(())
1303}
1304
1305fn retire_stage_owner(
1306    destination: &RetainedReconstructionDestination,
1307    owner_name: &OsStr,
1308    expected: &StageOwnershipRecord,
1309    published_root: &Dir,
1310) -> Result<(), RootReconstructionError> {
1311    let owner_display = destination.display_parent.join(owner_name);
1312    let staged_name = staged_root_name(&expected.operation.operation_id);
1313    let intent = StageOwnershipRecord {
1314        format: STAGE_OWNERSHIP_FORMAT_V1.to_owned(),
1315        operation: expected.operation.clone(),
1316        staged_name: staged_name.to_string_lossy().into_owned(),
1317        phase: StageOwnershipPhase::IntentDurable,
1318        physical_identity_sha256: None,
1319    };
1320    let intent_encoded = read_parent_regular(
1321        &destination.parent,
1322        owner_name,
1323        &owner_display,
1324        MAX_RECONSTRUCTION_RECORD_BYTES,
1325    )?
1326    .ok_or(RootReconstructionError::OperationConflict)?;
1327    require_exact_stage_ownership(&intent_encoded, &intent)?;
1328    let proof_name = stage_proof_name(&expected.operation.operation_id);
1329    let proof_display = destination.display_parent.join(&proof_name);
1330    let proof_encoded = read_parent_regular(
1331        &destination.parent,
1332        &proof_name,
1333        &proof_display,
1334        MAX_RECONSTRUCTION_RECORD_BYTES,
1335    )?
1336    .ok_or(RootReconstructionError::OperationConflict)?;
1337    require_exact_stage_ownership(&proof_encoded, expected)?;
1338    if expected.format != STAGE_OWNERSHIP_FORMAT_V1
1339        || expected.staged_name != staged_name.to_string_lossy()
1340        || expected.phase != StageOwnershipPhase::StageOwned
1341        || directory_identity_sha256(
1342            published_root,
1343            &destination.display_parent.join(&destination.name),
1344        )? != expected
1345            .physical_identity_sha256
1346            .as_deref()
1347            .ok_or(RootReconstructionError::OperationConflict)?
1348    {
1349        return Err(RootReconstructionError::OperationConflict);
1350    }
1351    destination
1352        .parent
1353        .remove_file(&proof_name)
1354        .map_err(|source| RootReconstructionError::Io {
1355            path: proof_display,
1356            source,
1357        })?;
1358    sync_retained_directory(&destination.parent, &destination.display_parent)?;
1359    destination
1360        .parent
1361        .remove_file(owner_name)
1362        .map_err(|source| RootReconstructionError::Io {
1363            path: owner_display,
1364            source,
1365        })?;
1366    sync_retained_directory(&destination.parent, &destination.display_parent)?;
1367    Ok(())
1368}
1369
1370fn retire_stage_owner_after_replay(
1371    destination: &RetainedReconstructionDestination,
1372    expected_operation: &ReconstructionRecord,
1373    published_root: &Dir,
1374) -> Result<(), RootReconstructionError> {
1375    let owner_name = stage_owner_name(&expected_operation.operation_id);
1376    let owner_display = destination.display_parent.join(&owner_name);
1377    let owner = read_parent_regular(
1378        &destination.parent,
1379        &owner_name,
1380        &owner_display,
1381        MAX_RECONSTRUCTION_RECORD_BYTES,
1382    )?;
1383    let proof_name = stage_proof_name(&expected_operation.operation_id);
1384    let proof_display = destination.display_parent.join(&proof_name);
1385    let proof = read_parent_regular(
1386        &destination.parent,
1387        &proof_name,
1388        &proof_display,
1389        MAX_RECONSTRUCTION_RECORD_BYTES,
1390    )?;
1391    let Some(owner) = owner else {
1392        return if proof.is_none() {
1393            Ok(())
1394        } else {
1395            Err(RootReconstructionError::OperationConflict)
1396        };
1397    };
1398    let staged_name = staged_root_name(&expected_operation.operation_id);
1399    let intent = StageOwnershipRecord {
1400        format: STAGE_OWNERSHIP_FORMAT_V1.to_owned(),
1401        operation: expected_operation.clone(),
1402        staged_name: staged_name.to_string_lossy().into_owned(),
1403        phase: StageOwnershipPhase::IntentDurable,
1404        physical_identity_sha256: None,
1405    };
1406    require_exact_stage_ownership(&owner, &intent)?;
1407    if let Some(proof) = proof {
1408        let ownership = decode_stage_ownership(&proof)?;
1409        let actual_identity = directory_identity_sha256(
1410            published_root,
1411            &destination.display_parent.join(&destination.name),
1412        )?;
1413        if ownership.format != STAGE_OWNERSHIP_FORMAT_V1
1414            || ownership.operation != *expected_operation
1415            || ownership.staged_name != staged_name.to_string_lossy()
1416            || ownership.phase != StageOwnershipPhase::StageOwned
1417            || ownership.physical_identity_sha256.as_deref() != Some(actual_identity.as_str())
1418        {
1419            return Err(RootReconstructionError::OperationConflict);
1420        }
1421        destination
1422            .parent
1423            .remove_file(&proof_name)
1424            .map_err(|source| RootReconstructionError::Io {
1425                path: proof_display,
1426                source,
1427            })?;
1428        sync_retained_directory(&destination.parent, &destination.display_parent)?;
1429    }
1430    if intent.operation != *expected_operation {
1431        return Err(RootReconstructionError::OperationConflict);
1432    }
1433    destination
1434        .parent
1435        .remove_file(&owner_name)
1436        .map_err(|source| RootReconstructionError::Io {
1437            path: owner_display,
1438            source,
1439        })?;
1440    sync_retained_directory(&destination.parent, &destination.display_parent)?;
1441    Ok(())
1442}
1443
1444fn open_directory_if_present(
1445    parent: &Dir,
1446    name: &OsStr,
1447    display: &Path,
1448) -> Result<Option<Dir>, RootReconstructionError> {
1449    let metadata = match parent.symlink_metadata(name) {
1450        Ok(metadata) => metadata,
1451        Err(source) if source.kind() == std::io::ErrorKind::NotFound => return Ok(None),
1452        Err(source) => {
1453            return Err(RootReconstructionError::Io {
1454                path: display.to_path_buf(),
1455                source,
1456            });
1457        }
1458    };
1459    if metadata.file_type().is_symlink() || !metadata.is_dir() {
1460        return Err(RootReconstructionError::DestinationOccupied(
1461            display.to_path_buf(),
1462        ));
1463    }
1464    parent
1465        .open_dir_nofollow(name)
1466        .map(Some)
1467        .map_err(|source| RootReconstructionError::Io {
1468            path: display.to_path_buf(),
1469            source,
1470        })
1471}
1472
1473fn replay_published_root(
1474    root: &Dir,
1475    destination: &RetainedReconstructionDestination,
1476    expected: &ReconstructionRecord,
1477) -> Result<RootReconstructionResult, RootReconstructionError> {
1478    let display = destination.display_parent.join(&destination.name);
1479    match replay_published_root_exact(root, destination, expected) {
1480        Ok(result) => Ok(result),
1481        Err(PublishedReplayError::NotExact) => {
1482            Err(RootReconstructionError::DestinationOccupied(display))
1483        }
1484        Err(PublishedReplayError::Operational(error)) => Err(error),
1485    }
1486}
1487
1488enum PublishedReplayError {
1489    NotExact,
1490    Operational(RootReconstructionError),
1491}
1492
1493impl From<RootReconstructionError> for PublishedReplayError {
1494    fn from(error: RootReconstructionError) -> Self {
1495        Self::Operational(error)
1496    }
1497}
1498
1499fn replay_published_root_exact(
1500    root: &Dir,
1501    destination: &RetainedReconstructionDestination,
1502    expected: &ReconstructionRecord,
1503) -> Result<RootReconstructionResult, PublishedReplayError> {
1504    let display = destination.display_parent.join(&destination.name);
1505    let state = match FolderbaseState::from_retained_root(root, &display) {
1506        Ok(state) => state,
1507        Err(FolderbaseError::Io { source, .. })
1508            if source.kind() == std::io::ErrorKind::NotFound =>
1509        {
1510            return Err(PublishedReplayError::NotExact);
1511        }
1512        Err(error) => {
1513            return Err(PublishedReplayError::Operational(
1514                RootReconstructionError::Filesystem(error),
1515            ));
1516        }
1517    };
1518    let Some(bytes) = state
1519        .read_bounded(
1520            Path::new(COMPLETED_RECONSTRUCTION_PATH),
1521            MAX_RECONSTRUCTION_RECORD_BYTES,
1522        )
1523        .map_err(|error| {
1524            PublishedReplayError::Operational(RootReconstructionError::Filesystem(error))
1525        })?
1526    else {
1527        return Err(PublishedReplayError::NotExact);
1528    };
1529    let completion: ReconstructionCompletion =
1530        serde_json::from_slice(&bytes).map_err(|_| PublishedReplayError::NotExact)?;
1531    if serde_json::to_vec(&completion).ok().as_deref() != Some(bytes.as_slice())
1532        || &completion.operation != expected
1533    {
1534        return Err(PublishedReplayError::NotExact);
1535    }
1536    let (attestation, _, profile) = attest_retained_folderbase_root_with_profile(root, &display)
1537        .map_err(|error| match &error {
1538            RootAttestationError::Io { source, .. }
1539                if source.kind() == std::io::ErrorKind::NotFound =>
1540            {
1541                PublishedReplayError::NotExact
1542            }
1543            RootAttestationError::Io { .. }
1544            | RootAttestationError::RootChangedDuringAttestation
1545            | RootAttestationError::PhysicalIdentityUnavailable => {
1546                PublishedReplayError::Operational(RootReconstructionError::Attestation(error))
1547            }
1548            _ => PublishedReplayError::NotExact,
1549        })?;
1550    if attestation.folderbase_id != expected.folderbase_id
1551        || attestation.root_instance_sha256 != completion.root_instance_sha256
1552        || attestation.manifest_sha256 != completion.manifest_sha256
1553    {
1554        return Err(PublishedReplayError::NotExact);
1555    }
1556    let version_bytes = state
1557        .read_bounded(
1558            &Path::new(".folderbase/versions/folderbase")
1559                .join(format!("{}.json", expected.folderbase_version_id)),
1560            MAX_PACKAGE_VERSION_BYTES,
1561        )
1562        .map_err(|error| {
1563            PublishedReplayError::Operational(RootReconstructionError::Filesystem(error))
1564        })?
1565        .ok_or(PublishedReplayError::NotExact)?;
1566    let version = FolderbaseVersion::decode_bounded(version_bytes.as_slice())
1567        .map_err(|_| PublishedReplayError::NotExact)?;
1568    if version
1569        .canonical_digest()
1570        .map_err(|_| PublishedReplayError::NotExact)?
1571        != expected.canonical_version_sha256
1572    {
1573        return Err(PublishedReplayError::NotExact);
1574    }
1575    require_matching_protocol_profile(&version, &profile)
1576        .map_err(|_| PublishedReplayError::NotExact)?;
1577    verify_visible_tree(root, &display, &version).map_err(|error| match error {
1578        RootReconstructionError::OperationConflict => PublishedReplayError::NotExact,
1579        error => PublishedReplayError::Operational(error),
1580    })?;
1581    retire_stage_owner_after_replay(destination, expected, root)
1582        .map_err(PublishedReplayError::Operational)?;
1583    Ok(RootReconstructionResult {
1584        replayed: true,
1585        attestation,
1586    })
1587}
1588
1589fn install_exact_record<T: Serialize>(
1590    state: &FolderbaseState,
1591    path: &Path,
1592    record: &T,
1593) -> Result<(), RootReconstructionError> {
1594    let encoded =
1595        serde_json::to_vec(record).map_err(|_| RootReconstructionError::OperationConflict)?;
1596    match state.publish_new(path, &encoded) {
1597        Ok(()) => Ok(()),
1598        Err(FolderbaseError::WouldOverwrite(_)) => {
1599            if state
1600                .read_bounded(path, MAX_RECONSTRUCTION_RECORD_BYTES)?
1601                .as_deref()
1602                == Some(encoded.as_slice())
1603            {
1604                Ok(())
1605            } else {
1606                Err(RootReconstructionError::OperationConflict)
1607            }
1608        }
1609        Err(error) => Err(error.into()),
1610    }
1611}
1612
1613fn revalidate_package(
1614    package: &RetainedReconstructionPackage,
1615    plan: &RootReconstructionPlan,
1616) -> Result<ValidatedPackage, RootReconstructionError> {
1617    let (index, index_identity) = read_package_regular_with_identity(
1618        package,
1619        Path::new("index.json"),
1620        MAX_PACKAGE_INDEX_BYTES,
1621    )?;
1622    if sha256(&index) != plan.package_index_sha256() {
1623        return Err(RootReconstructionError::PackageChanged(
1624            package.display_root.join("index.json"),
1625        ));
1626    }
1627    let (version, version_identity) = read_package_regular_with_identity(
1628        package,
1629        Path::new("version.json"),
1630        MAX_PACKAGE_VERSION_BYTES,
1631    )?;
1632    if sha256(&version) != plan.encoded_version_sha256() {
1633        return Err(RootReconstructionError::PackageChanged(
1634            package.display_root.join("version.json"),
1635        ));
1636    }
1637    let decoded = FolderbaseVersion::decode_bounded(version.as_slice())
1638        .map_err(RootReconstructionError::InvalidVersion)?;
1639    if decoded
1640        .canonical_digest()
1641        .map_err(RootReconstructionError::InvalidVersion)?
1642        != plan.canonical_version_sha256()
1643    {
1644        return Err(RootReconstructionError::PackageChanged(
1645            package.display_root.join("version.json"),
1646        ));
1647    }
1648
1649    require_exact_entries(
1650        &package.root,
1651        &package.display_root,
1652        &["chunks", "index.json", "manifests", "version.json"]
1653            .into_iter()
1654            .map(str::to_owned)
1655            .collect(),
1656    )?;
1657    let manifests_dir = open_package_directory(package, "manifests")?;
1658    let chunks_dir = open_package_directory(package, "chunks")?;
1659    let manifests_directory_identity =
1660        cap_directory_identity(&manifests_dir, &package.display_root.join("manifests"))?;
1661    let chunks_directory_identity =
1662        cap_directory_identity(&chunks_dir, &package.display_root.join("chunks"))?;
1663    let mut manifests = BTreeMap::new();
1664    let mut manifest_identities = BTreeMap::new();
1665    let mut manifest_names = BTreeSet::new();
1666    let mut chunk_names = BTreeSet::new();
1667    for planned in plan.manifests() {
1668        let name = format!("{}.json", planned.chunk_manifest_sha256());
1669        manifest_names.insert(name.clone());
1670        let (encoded, identity) = read_regular_from_with_identity(
1671            &manifests_dir,
1672            &package.display_root.join("manifests").join(&name),
1673            Path::new(&name),
1674            MAX_PACKAGE_MANIFEST_BYTES,
1675        )?;
1676        manifest_identities.insert(name.clone(), identity);
1677        let manifest = ChunkManifest::decode_slice_bounded(&encoded).map_err(|source| {
1678            RootReconstructionError::InvalidManifest {
1679                chunk_manifest_sha256: planned.chunk_manifest_sha256().to_owned(),
1680                source,
1681            }
1682        })?;
1683        if manifest.canonical_digest().ok().as_deref() != Some(planned.chunk_manifest_sha256())
1684            || manifest.object_sha256 != planned.object_sha256()
1685            || manifest.object_bytes != planned.object_bytes()
1686            || manifest.chunks.len() != planned.chunk_count()
1687        {
1688            return Err(RootReconstructionError::PackageChanged(
1689                package.display_root.join("manifests").join(name),
1690            ));
1691        }
1692        chunk_names.extend(manifest.chunks.iter().map(|chunk| chunk.sha256.clone()));
1693        manifests.insert(planned.chunk_manifest_sha256().to_owned(), manifest);
1694    }
1695    require_exact_entries(
1696        &manifests_dir,
1697        &package.display_root.join("manifests"),
1698        &manifest_names,
1699    )?;
1700    require_exact_entries(
1701        &chunks_dir,
1702        &package.display_root.join("chunks"),
1703        &chunk_names,
1704    )?;
1705    let mut chunk_identities = BTreeMap::new();
1706    for name in &chunk_names {
1707        let display = package.display_root.join("chunks").join(name);
1708        let file = open_regular_from(&chunks_dir, &display, Path::new(name))?;
1709        let metadata = file
1710            .metadata()
1711            .map_err(|source| RootReconstructionError::Io {
1712                path: display.clone(),
1713                source,
1714            })?;
1715        validate_package_regular_metadata(&metadata, &display)?;
1716        chunk_identities.insert(
1717            name.clone(),
1718            PackageRegularIdentity {
1719                physical: cap_file_identity(&file, &display)?,
1720                bytes: metadata.len(),
1721            },
1722        );
1723    }
1724    Ok(ValidatedPackage {
1725        manifests,
1726        _manifests_directory: manifests_dir,
1727        chunks_directory: chunks_dir,
1728        index_identity,
1729        version_identity,
1730        manifests_directory_identity,
1731        chunks_directory_identity,
1732        manifest_identities,
1733        chunk_identities,
1734    })
1735}
1736
1737fn require_same_package_identity(
1738    package: &RetainedReconstructionPackage,
1739    expected: &ValidatedPackage,
1740    actual: &ValidatedPackage,
1741) -> Result<(), RootReconstructionError> {
1742    if expected.index_identity != actual.index_identity
1743        || expected.version_identity != actual.version_identity
1744        || expected.manifests_directory_identity != actual.manifests_directory_identity
1745        || expected.chunks_directory_identity != actual.chunks_directory_identity
1746        || expected.manifest_identities != actual.manifest_identities
1747        || expected.chunk_identities != actual.chunk_identities
1748    {
1749        return Err(RootReconstructionError::PackageChanged(
1750            package.display_root.clone(),
1751        ));
1752    }
1753    Ok(())
1754}
1755
1756fn open_package_directory(
1757    package: &RetainedReconstructionPackage,
1758    name: &str,
1759) -> Result<Dir, RootReconstructionError> {
1760    let directory =
1761        package
1762            .root
1763            .open_dir_nofollow(name)
1764            .map_err(|source| RootReconstructionError::Io {
1765                path: package.display_root.join(name),
1766                source,
1767            })?;
1768    let metadata = directory
1769        .dir_metadata()
1770        .map_err(|source| RootReconstructionError::Io {
1771            path: package.display_root.join(name),
1772            source,
1773        })?;
1774    #[cfg(unix)]
1775    {
1776        use cap_std::fs::PermissionsExt;
1777        if metadata.permissions().mode() & 0o022 != 0 {
1778            return Err(RootReconstructionError::UnsafePackage(
1779                package.display_root.join(name),
1780            ));
1781        }
1782    }
1783    Ok(directory)
1784}
1785
1786fn require_exact_entries(
1787    directory: &Dir,
1788    display: &Path,
1789    expected: &BTreeSet<String>,
1790) -> Result<(), RootReconstructionError> {
1791    let mut actual = BTreeSet::new();
1792    let maximum_observations = expected.len().saturating_add(1);
1793    for entry in directory
1794        .entries()
1795        .map_err(|source| RootReconstructionError::Io {
1796            path: display.to_path_buf(),
1797            source,
1798        })?
1799    {
1800        if actual.len() >= maximum_observations {
1801            return Err(RootReconstructionError::UnsafePackage(
1802                display.to_path_buf(),
1803            ));
1804        }
1805        let entry = entry.map_err(|source| RootReconstructionError::Io {
1806            path: display.to_path_buf(),
1807            source,
1808        })?;
1809        let name = entry.file_name();
1810        if name.as_encoded_bytes().len() > MAX_PATH_COMPONENT_BYTES {
1811            return Err(RootReconstructionError::UnsafePackage(
1812                display.to_path_buf(),
1813            ));
1814        }
1815        let name = name
1816            .into_string()
1817            .map_err(|_| RootReconstructionError::UnsafePackage(display.to_path_buf()))?;
1818        actual.insert(name);
1819    }
1820    if &actual == expected {
1821        Ok(())
1822    } else {
1823        Err(RootReconstructionError::UnsafePackage(
1824            display.to_path_buf(),
1825        ))
1826    }
1827}
1828
1829fn read_package_regular_with_identity(
1830    package: &RetainedReconstructionPackage,
1831    relative: &Path,
1832    maximum: u64,
1833) -> Result<(Vec<u8>, PhysicalIdentity), RootReconstructionError> {
1834    read_regular_from_with_identity(
1835        &package.root,
1836        &package.display_root.join(relative),
1837        relative,
1838        maximum,
1839    )
1840}
1841
1842fn read_regular_from_with_identity(
1843    directory: &Dir,
1844    display: &Path,
1845    relative: &Path,
1846    maximum: u64,
1847) -> Result<(Vec<u8>, PhysicalIdentity), RootReconstructionError> {
1848    let mut file = open_regular_from(directory, display, relative)?;
1849    let identity = cap_file_identity(&file, display)?;
1850    let metadata = file
1851        .metadata()
1852        .map_err(|source| RootReconstructionError::Io {
1853            path: display.to_path_buf(),
1854            source,
1855        })?;
1856    validate_package_regular_metadata(&metadata, display)?;
1857    if metadata.len() > maximum {
1858        return Err(RootReconstructionError::PackageChanged(
1859            display.to_path_buf(),
1860        ));
1861    }
1862    let mut bytes = Vec::new();
1863    Read::by_ref(&mut file)
1864        .take(maximum.saturating_add(1))
1865        .read_to_end(&mut bytes)
1866        .map_err(|source| RootReconstructionError::Io {
1867            path: display.to_path_buf(),
1868            source,
1869        })?;
1870    if bytes.len() as u64 > maximum {
1871        return Err(RootReconstructionError::PackageChanged(
1872            display.to_path_buf(),
1873        ));
1874    }
1875    let reopened = open_regular_from(directory, display, relative)?;
1876    let reopened_identity = cap_file_identity(&reopened, display)?;
1877    let after = reopened
1878        .metadata()
1879        .map_err(|source| RootReconstructionError::Io {
1880            path: display.to_path_buf(),
1881            source,
1882        })?;
1883    validate_package_regular_metadata(&after, display)?;
1884    if after.len() != metadata.len() || reopened_identity != identity {
1885        return Err(RootReconstructionError::PackageChanged(
1886            display.to_path_buf(),
1887        ));
1888    }
1889    Ok((bytes, identity))
1890}
1891
1892fn validate_package_regular_metadata(
1893    metadata: &cap_std::fs::Metadata,
1894    display: &Path,
1895) -> Result<(), RootReconstructionError> {
1896    if metadata.file_type().is_symlink() || !metadata.is_file() {
1897        return Err(RootReconstructionError::UnsafePackage(
1898            display.to_path_buf(),
1899        ));
1900    }
1901    #[cfg(unix)]
1902    {
1903        use cap_fs_ext::OsMetadataExt;
1904        use cap_std::fs::PermissionsExt;
1905        if metadata.permissions().mode() & 0o022 != 0 || metadata.nlink() != 1 {
1906            return Err(RootReconstructionError::UnsafePackage(
1907                display.to_path_buf(),
1908            ));
1909        }
1910    }
1911    Ok(())
1912}
1913
1914fn cap_file_identity(
1915    file: &cap_std::fs::File,
1916    display: &Path,
1917) -> Result<PhysicalIdentity, RootReconstructionError> {
1918    let file = file
1919        .try_clone()
1920        .map_err(|source| RootReconstructionError::Io {
1921            path: display.to_path_buf(),
1922            source,
1923        })?
1924        .into_std();
1925    PhysicalIdentity::from_file(&file).map_err(|source| RootReconstructionError::Io {
1926        path: display.to_path_buf(),
1927        source,
1928    })
1929}
1930
1931fn open_regular_from(
1932    directory: &Dir,
1933    display: &Path,
1934    relative: &Path,
1935) -> Result<cap_std::fs::File, RootReconstructionError> {
1936    let leaf = retain_leaf_parent(directory, relative, display)?;
1937    let mut options = CapOpenOptions::new();
1938    options.read(true).follow(FollowSymlinks::No);
1939    let file = leaf
1940        .parent
1941        .open_with(&leaf.name, &options)
1942        .map_err(|source| RootReconstructionError::Io {
1943            path: display.to_path_buf(),
1944            source,
1945        })?;
1946    let metadata = file
1947        .metadata()
1948        .map_err(|source| RootReconstructionError::Io {
1949            path: display.to_path_buf(),
1950            source,
1951        })?;
1952    if metadata.file_type().is_symlink() || !metadata.is_file() {
1953        return Err(RootReconstructionError::UnsafePackage(
1954            display.to_path_buf(),
1955        ));
1956    }
1957    Ok(file)
1958}
1959
1960#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1961enum ObservedVisibleKind {
1962    Directory,
1963    RegularFile,
1964    Symlink,
1965}
1966
1967fn verify_visible_tree(
1968    root: &Dir,
1969    display_root: &Path,
1970    version: &FolderbaseVersion,
1971) -> Result<(), RootReconstructionError> {
1972    let expected = version
1973        .bindings()
1974        .iter()
1975        .map(|binding| (binding.path().to_owned(), binding.kind()))
1976        .collect::<BTreeMap<_, _>>();
1977    let mut observed = BTreeMap::new();
1978    inventory_visible_directory(
1979        root,
1980        display_root,
1981        Path::new(""),
1982        expected.len(),
1983        &mut observed,
1984    )?;
1985    if observed.len() != expected.len()
1986        || expected.iter().any(|(path, kind)| {
1987            observed.get(path).copied()
1988                != Some(match kind {
1989                    PathBindingKind::Directory => ObservedVisibleKind::Directory,
1990                    PathBindingKind::RegularFile => ObservedVisibleKind::RegularFile,
1991                    PathBindingKind::Symlink => ObservedVisibleKind::Symlink,
1992                })
1993        })
1994    {
1995        return Err(RootReconstructionError::OperationConflict);
1996    }
1997
1998    for binding in version.bindings() {
1999        let relative = Path::new(binding.path());
2000        let display = display_root.join(relative);
2001        let leaf = retain_leaf_parent(root, relative, &display)?;
2002        match binding.kind() {
2003            PathBindingKind::Directory => {
2004                let metadata = leaf.parent.symlink_metadata(&leaf.name).map_err(|source| {
2005                    RootReconstructionError::Io {
2006                        path: display,
2007                        source,
2008                    }
2009                })?;
2010                if metadata.file_type().is_symlink() || !metadata.is_dir() {
2011                    return Err(RootReconstructionError::OperationConflict);
2012                }
2013            }
2014            PathBindingKind::RegularFile => {
2015                verify_exact_regular_binding(root, display_root, binding)?;
2016            }
2017            PathBindingKind::Symlink => {
2018                let target = leaf.parent.read_link(&leaf.name).map_err(|source| {
2019                    RootReconstructionError::Io {
2020                        path: display,
2021                        source,
2022                    }
2023                })?;
2024                if target != Path::new(binding.symlink_target().expect("symlink target")) {
2025                    return Err(RootReconstructionError::OperationConflict);
2026                }
2027            }
2028        }
2029    }
2030    Ok(())
2031}
2032
2033fn inventory_visible_directory(
2034    directory: &Dir,
2035    display_root: &Path,
2036    relative_directory: &Path,
2037    maximum: usize,
2038    observed: &mut BTreeMap<String, ObservedVisibleKind>,
2039) -> Result<(), RootReconstructionError> {
2040    let display_directory = display_root.join(relative_directory);
2041    for entry in directory
2042        .entries()
2043        .map_err(|source| RootReconstructionError::Io {
2044            path: display_directory.clone(),
2045            source,
2046        })?
2047    {
2048        if observed.len() >= maximum.saturating_add(1) {
2049            return Err(RootReconstructionError::OperationConflict);
2050        }
2051        let entry = entry.map_err(|source| RootReconstructionError::Io {
2052            path: display_directory.clone(),
2053            source,
2054        })?;
2055        let name = entry.file_name();
2056        if name.as_encoded_bytes().is_empty()
2057            || name.as_encoded_bytes().len() > MAX_PATH_COMPONENT_BYTES
2058        {
2059            return Err(RootReconstructionError::OperationConflict);
2060        }
2061        if relative_directory.as_os_str().is_empty()
2062            && name.to_str().is_some_and(|name| name == ".folderbase")
2063        {
2064            continue;
2065        }
2066        let relative = relative_directory.join(&name);
2067        let path = relative
2068            .to_str()
2069            .filter(|path| path.len() <= MAX_PATH_BYTES)
2070            .ok_or(RootReconstructionError::OperationConflict)?
2071            .to_owned();
2072        let metadata =
2073            directory
2074                .symlink_metadata(&name)
2075                .map_err(|source| RootReconstructionError::Io {
2076                    path: display_root.join(&relative),
2077                    source,
2078                })?;
2079        let kind = if metadata.file_type().is_symlink() {
2080            ObservedVisibleKind::Symlink
2081        } else if metadata.is_dir() {
2082            ObservedVisibleKind::Directory
2083        } else if metadata.is_file() {
2084            ObservedVisibleKind::RegularFile
2085        } else {
2086            return Err(RootReconstructionError::OperationConflict);
2087        };
2088        if observed.insert(path, kind).is_some() {
2089            return Err(RootReconstructionError::OperationConflict);
2090        }
2091        if kind == ObservedVisibleKind::Directory {
2092            let child = directory.open_dir_nofollow(&name).map_err(|source| {
2093                RootReconstructionError::Io {
2094                    path: display_root.join(&relative),
2095                    source,
2096                }
2097            })?;
2098            inventory_visible_directory(&child, display_root, &relative, maximum, observed)?;
2099        }
2100    }
2101    Ok(())
2102}
2103
2104fn verify_exact_regular_binding(
2105    root: &Dir,
2106    display_root: &Path,
2107    binding: &crate::folderbase_version::PathBinding,
2108) -> Result<(), RootReconstructionError> {
2109    let relative = Path::new(binding.path());
2110    let display = display_root.join(relative);
2111    let mut file = open_regular_from(root, &display, relative)?;
2112    let expected_bytes = binding.bytes().expect("regular bytes");
2113    let metadata = file
2114        .metadata()
2115        .map_err(|source| RootReconstructionError::Io {
2116            path: display.clone(),
2117            source,
2118        })?;
2119    let identity = cap_file_identity(&file, &display)?;
2120    if metadata.len() != expected_bytes
2121        || regular_is_executable(&metadata) != binding.executable().expect("regular executable")
2122    {
2123        return Err(RootReconstructionError::OperationConflict);
2124    }
2125    let mut digest = Sha256::new();
2126    let mut bytes = 0_u64;
2127    let mut buffer = [0_u8; 64 * 1024];
2128    let mut bounded = Read::by_ref(&mut file).take(expected_bytes.saturating_add(1));
2129    loop {
2130        let read = bounded
2131            .read(&mut buffer)
2132            .map_err(|source| RootReconstructionError::Io {
2133                path: display.clone(),
2134                source,
2135            })?;
2136        if read == 0 {
2137            break;
2138        }
2139        bytes = bytes.saturating_add(read as u64);
2140        digest.update(&buffer[..read]);
2141    }
2142    if bytes != expected_bytes
2143        || format!("{:x}", digest.finalize()) != binding.content_sha256().expect("regular digest")
2144    {
2145        return Err(RootReconstructionError::OperationConflict);
2146    }
2147    let reopened = open_regular_from(root, &display, relative)?;
2148    let reopened_metadata = reopened
2149        .metadata()
2150        .map_err(|source| RootReconstructionError::Io {
2151            path: display.clone(),
2152            source,
2153        })?;
2154    if cap_file_identity(&reopened, &display)? != identity
2155        || reopened_metadata.len() != expected_bytes
2156        || regular_is_executable(&reopened_metadata)
2157            != binding.executable().expect("regular executable")
2158    {
2159        return Err(RootReconstructionError::OperationConflict);
2160    }
2161    Ok(())
2162}
2163
2164fn regular_is_executable(metadata: &cap_std::fs::Metadata) -> bool {
2165    #[cfg(unix)]
2166    {
2167        use cap_std::fs::PermissionsExt;
2168        metadata.permissions().mode() & 0o111 != 0
2169    }
2170    #[cfg(not(unix))]
2171    {
2172        let _ = metadata;
2173        false
2174    }
2175}
2176
2177struct RetainedLeafParent {
2178    parent: Dir,
2179    name: OsString,
2180    parent_display: PathBuf,
2181    display: PathBuf,
2182}
2183
2184fn retain_leaf_parent(
2185    root: &Dir,
2186    relative: &Path,
2187    display: &Path,
2188) -> Result<RetainedLeafParent, RootReconstructionError> {
2189    let name = relative
2190        .file_name()
2191        .ok_or(RootReconstructionError::InvalidDestination)?
2192        .to_os_string();
2193    let mut parent = root
2194        .try_clone()
2195        .map_err(|source| RootReconstructionError::Io {
2196            path: display.to_path_buf(),
2197            source,
2198        })?;
2199    if let Some(ancestors) = relative.parent() {
2200        for component in ancestors.components() {
2201            let Component::Normal(component) = component else {
2202                return Err(RootReconstructionError::InvalidDestination);
2203            };
2204            parent = parent.open_dir_nofollow(component).map_err(|source| {
2205                RootReconstructionError::Io {
2206                    path: display.to_path_buf(),
2207                    source,
2208                }
2209            })?;
2210        }
2211    }
2212    Ok(RetainedLeafParent {
2213        parent,
2214        name,
2215        parent_display: display.parent().unwrap_or(display).to_path_buf(),
2216        display: display.to_path_buf(),
2217    })
2218}
2219
2220fn materialize_reconstruction(
2221    root: &Dir,
2222    display_root: &Path,
2223    state: &FolderbaseState,
2224    local: &LocalVersionStore,
2225    _package: &RetainedReconstructionPackage,
2226    plan: &RootReconstructionPlan,
2227    validated_package: &ValidatedPackage,
2228) -> Result<ReconstructedHistoryClosure, RootReconstructionError> {
2229    let mut executable_fidelity = BTreeMap::new();
2230    for binding in plan.version().bindings() {
2231        if binding.kind() == PathBindingKind::RegularFile {
2232            insert_executable_fidelity(
2233                &mut executable_fidelity,
2234                binding
2235                    .object_version_id()
2236                    .ok_or(RootReconstructionError::OperationConflict)?,
2237                binding.executable().unwrap_or(false),
2238            )?;
2239        }
2240    }
2241    for fidelity in plan.tombstone_fidelity() {
2242        insert_executable_fidelity(
2243            &mut executable_fidelity,
2244            fidelity.object_version_id(),
2245            fidelity.executable(),
2246        )?;
2247    }
2248
2249    for binding in plan.version().bindings() {
2250        if binding.kind() == PathBindingKind::Directory {
2251            ensure_directory(root, Path::new(binding.path()), display_root)?;
2252        } else if let Some(parent) = Path::new(binding.path()).parent()
2253            && !parent.as_os_str().is_empty()
2254        {
2255            ensure_directory(root, parent, display_root)?;
2256        }
2257    }
2258
2259    let mut object_paths = BTreeMap::new();
2260    let mut object_versions = Vec::new();
2261    for reference in plan.references() {
2262        let manifest = validated_package
2263            .manifests
2264            .get(reference.chunk_manifest_sha256())
2265            .ok_or(RootReconstructionError::OperationConflict)?;
2266        let relative = Path::new(RECONSTRUCTION_OBJECTS_DIRECTORY)
2267            .join(format!("{}.object", reference.object_version_id()));
2268        write_verified_package_object(root, display_root, &relative, validated_package, manifest)?;
2269        let mut staged_object = open_regular_from(root, &display_root.join(&relative), &relative)?;
2270        let installed = local.install_content_reader_in(
2271            state,
2272            &mut staged_object,
2273            &display_root.join(&relative),
2274            manifest.object_bytes,
2275        )?;
2276        if installed.digest != manifest.object_sha256 || installed.bytes != manifest.object_bytes {
2277            return Err(RootReconstructionError::OperationConflict);
2278        }
2279        let object_id = match reference.object_id() {
2280            Some(value) => ObjectId::parse(value.to_owned())?,
2281            None => derived_root_object_id(plan)?,
2282        };
2283        let mut extensions = BTreeMap::new();
2284        if let Some(executable) = executable_fidelity.get(reference.object_version_id()) {
2285            extensions.insert(
2286                "executable".to_owned(),
2287                serde_json::Value::Bool(*executable),
2288            );
2289        }
2290        object_versions.push(LocalVersionRecord {
2291            id: VersionId::parse(reference.object_version_id().to_owned())?,
2292            object_id,
2293            content: installed,
2294            captured_at: plan.version().created_at().to_owned(),
2295            extensions,
2296        });
2297        object_paths.insert(reference.object_version_id().to_owned(), relative);
2298    }
2299
2300    let root_reference = plan
2301        .references()
2302        .iter()
2303        .find(|reference| {
2304            reference
2305                .roles()
2306                .contains(&ReconstructionReferenceRole::RootManifest)
2307        })
2308        .ok_or(RootReconstructionError::OperationConflict)?;
2309    let root_manifest = validated_package
2310        .manifests
2311        .get(root_reference.chunk_manifest_sha256())
2312        .ok_or(RootReconstructionError::OperationConflict)?;
2313    copy_verified_stage_object(
2314        root,
2315        display_root,
2316        object_paths
2317            .get(root_reference.object_version_id())
2318            .ok_or(RootReconstructionError::OperationConflict)?,
2319        Path::new(".folderbase/manifest.json"),
2320        root_manifest,
2321        false,
2322    )?;
2323
2324    for binding in plan.version().bindings() {
2325        if binding.kind() != PathBindingKind::RegularFile {
2326            continue;
2327        }
2328        let version_id = binding
2329            .object_version_id()
2330            .ok_or(RootReconstructionError::OperationConflict)?;
2331        let reference = plan
2332            .references()
2333            .iter()
2334            .find(|reference| reference.object_version_id() == version_id)
2335            .ok_or(RootReconstructionError::OperationConflict)?;
2336        let manifest = validated_package
2337            .manifests
2338            .get(reference.chunk_manifest_sha256())
2339            .ok_or(RootReconstructionError::OperationConflict)?;
2340        copy_verified_stage_object(
2341            root,
2342            display_root,
2343            object_paths
2344                .get(version_id)
2345                .ok_or(RootReconstructionError::OperationConflict)?,
2346            Path::new(binding.path()),
2347            manifest,
2348            binding.executable().unwrap_or(false),
2349        )?;
2350    }
2351
2352    for symlink in plan.derived_symlinks() {
2353        create_exact_symlink(root, display_root, symlink)?;
2354        let content = local.install_content_bytes_in(state, symlink.target().as_bytes())?;
2355        if content.digest != symlink.content_sha256() || content.bytes != symlink.bytes() {
2356            return Err(RootReconstructionError::OperationConflict);
2357        }
2358        object_versions.push(LocalVersionRecord {
2359            id: VersionId::parse(symlink.object_version_id().to_owned())?,
2360            object_id: ObjectId::parse(symlink.object_id().to_owned())?,
2361            content,
2362            captured_at: plan.version().created_at().to_owned(),
2363            extensions: BTreeMap::new(),
2364        });
2365    }
2366
2367    let mut projections = BTreeMap::new();
2368    for binding in plan.version().bindings() {
2369        if binding.kind() != PathBindingKind::RegularFile
2370            || !can_project_reconstructed_object(binding.path())
2371        {
2372            continue;
2373        }
2374        let object_id = ObjectId::parse(binding.object_id().to_owned())?;
2375        let version_id = VersionId::parse(
2376            binding
2377                .object_version_id()
2378                .ok_or(RootReconstructionError::OperationConflict)?
2379                .to_owned(),
2380        )?;
2381        merge_reconstructed_projection(
2382            &mut projections,
2383            reconstructed_projection(
2384                object_id,
2385                version_id,
2386                binding.path(),
2387                plan.version().created_at(),
2388                "canonical",
2389            ),
2390        );
2391    }
2392    for tombstone in plan.version().tombstones() {
2393        if tombstone.deleted_kind() != DeletedKind::RegularFile
2394            || !can_project_reconstructed_object(tombstone.path())
2395        {
2396            continue;
2397        }
2398        let Some(version_id) = tombstone.last_object_version_id() else {
2399            continue;
2400        };
2401        merge_reconstructed_projection(
2402            &mut projections,
2403            reconstructed_projection(
2404                ObjectId::parse(tombstone.object_id().to_owned())?,
2405                VersionId::parse(version_id.to_owned())?,
2406                tombstone.path(),
2407                plan.version().created_at(),
2408                "deleted",
2409            ),
2410        );
2411    }
2412    object_versions.sort_by(|left, right| left.id.as_str().cmp(right.id.as_str()));
2413    let tombstone_associations = plan
2414        .tombstone_fidelity()
2415        .iter()
2416        .map(|fidelity| {
2417            let record = object_versions
2418                .iter()
2419                .find(|record| {
2420                    record.id.as_str() == fidelity.object_version_id()
2421                        && record.object_id.as_str() == fidelity.object_id()
2422                })
2423                .ok_or(RootReconstructionError::OperationConflict)?;
2424            Ok(ReconstructedTombstoneAssociation::for_tombstone(
2425                fidelity.path(),
2426                fidelity.object_id(),
2427                fidelity.object_version_id(),
2428                &record.content.digest,
2429                record.content.bytes,
2430                fidelity.executable(),
2431            ))
2432        })
2433        .collect::<Result<Vec<_>, RootReconstructionError>>()?;
2434    Ok(ReconstructedHistoryClosure {
2435        object_versions,
2436        object_projections: projections.into_values().collect(),
2437        tombstone_associations,
2438    })
2439}
2440
2441fn can_project_reconstructed_object(path: &str) -> bool {
2442    !Path::new(path).components().any(|component| {
2443        matches!(component, Component::Normal(name) if is_reserved_workspace_component(name))
2444    })
2445}
2446
2447fn insert_executable_fidelity(
2448    executable_fidelity: &mut BTreeMap<String, bool>,
2449    object_version_id: &str,
2450    executable: bool,
2451) -> Result<(), RootReconstructionError> {
2452    if executable_fidelity
2453        .insert(object_version_id.to_owned(), executable)
2454        .is_some_and(|previous| previous != executable)
2455    {
2456        return Err(RootReconstructionError::TombstoneFidelityMismatch);
2457    }
2458    Ok(())
2459}
2460
2461fn reconstructed_projection(
2462    object_id: ObjectId,
2463    version_id: VersionId,
2464    path: &str,
2465    created_at: &str,
2466    lifecycle_status: &str,
2467) -> LocalObjectRecord {
2468    LocalObjectRecord {
2469        schema: "https://folderbase.ai/protocol/0.1/object.schema.json".to_owned(),
2470        id: object_id,
2471        object_type: "file".to_owned(),
2472        path: path.to_owned(),
2473        lifecycle: ObjectLifecycle {
2474            status: lifecycle_status.to_owned(),
2475            extensions: BTreeMap::new(),
2476        },
2477        provenance: ObjectProvenance {
2478            created_at: created_at.to_owned(),
2479            source: "folderbase-root-reconstruction".to_owned(),
2480            extensions: BTreeMap::new(),
2481        },
2482        current_version: version_id.clone(),
2483        versions: vec![version_id],
2484        extensions: BTreeMap::new(),
2485    }
2486}
2487
2488fn merge_reconstructed_projection(
2489    projections: &mut BTreeMap<String, LocalObjectRecord>,
2490    candidate: LocalObjectRecord,
2491) {
2492    match projections.entry(candidate.id.as_str().to_owned()) {
2493        std::collections::btree_map::Entry::Vacant(entry) => {
2494            entry.insert(candidate);
2495        }
2496        std::collections::btree_map::Entry::Occupied(mut entry) => {
2497            let existing = entry.get_mut();
2498            for version in candidate.versions {
2499                if !existing.versions.contains(&version) {
2500                    existing.versions.push(version);
2501                }
2502            }
2503            existing
2504                .versions
2505                .sort_by(|left, right| left.as_str().cmp(right.as_str()));
2506        }
2507    }
2508}
2509
2510fn derived_root_object_id(
2511    plan: &RootReconstructionPlan,
2512) -> Result<ObjectId, RootReconstructionError> {
2513    let digest = Sha256::digest(
2514        format!(
2515            "folderbase-root-reconstruction-root-object-v1\0{}\0{}",
2516            plan.version().folderbase_id(),
2517            plan.version().root_manifest().object_version_id()
2518        )
2519        .as_bytes(),
2520    );
2521    let mut bytes = [0_u8; 16];
2522    bytes.copy_from_slice(&digest[..16]);
2523    bytes[6] = (bytes[6] & 0x0f) | 0x70;
2524    bytes[8] = (bytes[8] & 0x3f) | 0x80;
2525    ObjectId::parse(format!("obj_{}", Uuid::from_bytes(bytes).hyphenated())).map_err(Into::into)
2526}
2527
2528fn write_verified_package_object(
2529    root: &Dir,
2530    display_root: &Path,
2531    relative: &Path,
2532    validated_package: &ValidatedPackage,
2533    manifest: &ChunkManifest,
2534) -> Result<(), RootReconstructionError> {
2535    let leaf = retain_leaf_parent(root, relative, &display_root.join(relative))?;
2536    match leaf.parent.symlink_metadata(&leaf.name) {
2537        Ok(metadata) if metadata.is_file() && !metadata.file_type().is_symlink() => {
2538            let existing = open_regular_from(root, &leaf.display, relative)?;
2539            if manifest.verify_object(existing).is_ok() {
2540                manifest.verify_object(PackageObjectReader::new(validated_package, manifest)?)?;
2541                return Ok(());
2542            }
2543            leaf.parent
2544                .remove_file(&leaf.name)
2545                .map_err(|source| RootReconstructionError::Io {
2546                    path: leaf.display.clone(),
2547                    source,
2548                })?;
2549            sync_retained_directory(&leaf.parent, &leaf.parent_display)?;
2550        }
2551        Ok(_) => return Err(RootReconstructionError::OperationConflict),
2552        Err(source) if source.kind() == std::io::ErrorKind::NotFound => {}
2553        Err(source) => {
2554            return Err(RootReconstructionError::Io {
2555                path: leaf.display.clone(),
2556                source,
2557            });
2558        }
2559    }
2560    let mut options = CapOpenOptions::new();
2561    options
2562        .write(true)
2563        .create_new(true)
2564        .follow(FollowSymlinks::No);
2565    let mut file = leaf
2566        .parent
2567        .open_with(&leaf.name, &options)
2568        .map_err(|source| RootReconstructionError::Io {
2569            path: leaf.display.clone(),
2570            source,
2571        })?;
2572    manifest.verify_object_and_copy(
2573        PackageObjectReader::new(validated_package, manifest)?,
2574        &mut file,
2575    )?;
2576    file.sync_all()
2577        .map_err(|source| RootReconstructionError::Io {
2578            path: leaf.display.clone(),
2579            source,
2580        })?;
2581    sync_retained_directory(&leaf.parent, &leaf.parent_display)?;
2582    manifest.verify_object(open_regular_from(
2583        root,
2584        &display_root.join(relative),
2585        relative,
2586    )?)?;
2587    Ok(())
2588}
2589
2590fn copy_verified_stage_object(
2591    root: &Dir,
2592    display_root: &Path,
2593    source: &Path,
2594    destination: &Path,
2595    manifest: &ChunkManifest,
2596    executable: bool,
2597) -> Result<(), RootReconstructionError> {
2598    let leaf = retain_leaf_parent(root, destination, &display_root.join(destination))?;
2599    match leaf.parent.symlink_metadata(&leaf.name) {
2600        Ok(metadata) if metadata.is_file() && !metadata.file_type().is_symlink() => {
2601            let existing = open_regular_from(root, &leaf.display, destination)?;
2602            if manifest.verify_object(existing).is_ok()
2603                && regular_is_executable(&metadata) == executable
2604            {
2605                return Ok(());
2606            }
2607            leaf.parent
2608                .remove_file(&leaf.name)
2609                .map_err(|source| RootReconstructionError::Io {
2610                    path: leaf.display.clone(),
2611                    source,
2612                })?;
2613            sync_retained_directory(&leaf.parent, &leaf.parent_display)?;
2614        }
2615        Ok(_) => return Err(RootReconstructionError::OperationConflict),
2616        Err(source) if source.kind() == std::io::ErrorKind::NotFound => {}
2617        Err(source) => {
2618            return Err(RootReconstructionError::Io {
2619                path: leaf.display.clone(),
2620                source,
2621            });
2622        }
2623    }
2624    let mut options = CapOpenOptions::new();
2625    options
2626        .write(true)
2627        .create_new(true)
2628        .follow(FollowSymlinks::No);
2629    let mut destination_file = leaf
2630        .parent
2631        .open_with(&leaf.name, &options)
2632        .map_err(|source| RootReconstructionError::Io {
2633            path: leaf.display.clone(),
2634            source,
2635        })?;
2636    let source_file = open_regular_from(root, &display_root.join(source), source)?;
2637    manifest.verify_object_and_copy(source_file, &mut destination_file)?;
2638    set_regular_executable(
2639        &destination_file,
2640        executable,
2641        &display_root.join(destination),
2642    )?;
2643    destination_file
2644        .sync_all()
2645        .map_err(|source| RootReconstructionError::Io {
2646            path: leaf.display.clone(),
2647            source,
2648        })?;
2649    sync_retained_directory(&leaf.parent, &leaf.parent_display)?;
2650    Ok(())
2651}
2652
2653fn set_regular_executable(
2654    file: &cap_std::fs::File,
2655    executable: bool,
2656    display: &Path,
2657) -> Result<(), RootReconstructionError> {
2658    #[cfg(unix)]
2659    {
2660        use cap_std::fs::PermissionsExt;
2661        let mode = if executable { 0o755 } else { 0o644 };
2662        file.set_permissions(cap_std::fs::Permissions::from_mode(mode))
2663            .map_err(|source| RootReconstructionError::Io {
2664                path: display.to_path_buf(),
2665                source,
2666            })?;
2667    }
2668    #[cfg(not(unix))]
2669    let _ = (file, executable, display);
2670    Ok(())
2671}
2672
2673fn create_exact_symlink(
2674    root: &Dir,
2675    display_root: &Path,
2676    symlink: &DerivedSymlink,
2677) -> Result<(), RootReconstructionError> {
2678    let relative = Path::new(symlink.path());
2679    let leaf = retain_leaf_parent(root, relative, &display_root.join(relative))?;
2680    match leaf.parent.read_link(&leaf.name) {
2681        Ok(target) if target == Path::new(symlink.target()) => return Ok(()),
2682        Ok(_) => return Err(RootReconstructionError::OperationConflict),
2683        Err(source) if source.kind() == std::io::ErrorKind::NotFound => {}
2684        Err(source) => {
2685            return Err(RootReconstructionError::Io {
2686                path: display_root.join(relative),
2687                source,
2688            });
2689        }
2690    }
2691    leaf.parent
2692        .symlink_contents(symlink.target(), &leaf.name)
2693        .map_err(|source| RootReconstructionError::Io {
2694            path: leaf.display.clone(),
2695            source,
2696        })?;
2697    sync_retained_directory(&leaf.parent, &leaf.parent_display)?;
2698    Ok(())
2699}
2700
2701fn ensure_directory(
2702    root: &Dir,
2703    relative: &Path,
2704    display_root: &Path,
2705) -> Result<(), RootReconstructionError> {
2706    let mut current = root
2707        .try_clone()
2708        .map_err(|source| RootReconstructionError::Io {
2709            path: display_root.to_path_buf(),
2710            source,
2711        })?;
2712    let mut display = display_root.to_path_buf();
2713    for component in relative.components() {
2714        let Component::Normal(name) = component else {
2715            return Err(RootReconstructionError::InvalidDestination);
2716        };
2717        display.push(name);
2718        match current.symlink_metadata(name) {
2719            Ok(metadata) if metadata.is_dir() && !metadata.file_type().is_symlink() => {}
2720            Ok(_) => return Err(RootReconstructionError::OperationConflict),
2721            Err(source) if source.kind() == std::io::ErrorKind::NotFound => {
2722                current
2723                    .create_dir(name)
2724                    .map_err(|source| RootReconstructionError::Io {
2725                        path: display.clone(),
2726                        source,
2727                    })?;
2728                sync_retained_directory(&current, &display)?;
2729            }
2730            Err(source) => {
2731                return Err(RootReconstructionError::Io {
2732                    path: display.clone(),
2733                    source,
2734                });
2735            }
2736        }
2737        current =
2738            current
2739                .open_dir_nofollow(name)
2740                .map_err(|source| RootReconstructionError::Io {
2741                    path: display.clone(),
2742                    source,
2743                })?;
2744    }
2745    Ok(())
2746}
2747
2748struct PackageObjectReader<'a> {
2749    chunks: Dir,
2750    display: PathBuf,
2751    expected_identities: &'a BTreeMap<String, PackageRegularIdentity>,
2752    descriptors: Vec<(String, u64)>,
2753    next: usize,
2754    current: Option<OpenPackageChunk>,
2755}
2756
2757struct OpenPackageChunk {
2758    file: cap_std::fs::File,
2759    name: String,
2760    bytes: u64,
2761    identity: PhysicalIdentity,
2762}
2763
2764impl<'a> PackageObjectReader<'a> {
2765    fn new(
2766        package: &'a ValidatedPackage,
2767        manifest: &ChunkManifest,
2768    ) -> Result<Self, RootReconstructionError> {
2769        Ok(Self {
2770            chunks: package.chunks_directory.try_clone().map_err(|source| {
2771                RootReconstructionError::Io {
2772                    path: PathBuf::from("chunks"),
2773                    source,
2774                }
2775            })?,
2776            display: PathBuf::from("chunks"),
2777            expected_identities: &package.chunk_identities,
2778            descriptors: manifest
2779                .chunks
2780                .iter()
2781                .map(|chunk| (chunk.sha256.clone(), chunk.bytes))
2782                .collect(),
2783            next: 0,
2784            current: None,
2785        })
2786    }
2787
2788    fn open_next(&mut self) -> std::io::Result<bool> {
2789        let Some((name, bytes)) = self.descriptors.get(self.next) else {
2790            return Ok(false);
2791        };
2792        let mut options = CapOpenOptions::new();
2793        options.read(true).follow(FollowSymlinks::No);
2794        let file = self.chunks.open_with(name, &options)?;
2795        let metadata = file.metadata()?;
2796        validate_package_regular_metadata(&metadata, &self.display.join(name))
2797            .map_err(|error| std::io::Error::other(error.to_string()))?;
2798        let expected = self
2799            .expected_identities
2800            .get(name)
2801            .ok_or_else(|| std::io::Error::other("package chunk identity is unbound"))?;
2802        let identity = cap_file_identity(&file, &self.display.join(name)).map_err(|error| {
2803            std::io::Error::other(format!("package chunk identity failed: {error}"))
2804        })?;
2805        if metadata.len() != *bytes
2806            || metadata.len() != expected.bytes
2807            || identity != expected.physical
2808        {
2809            return Err(std::io::Error::other(format!(
2810                "package chunk changed: {}",
2811                self.display.join(name).display()
2812            )));
2813        }
2814        self.current = Some(OpenPackageChunk {
2815            file,
2816            name: name.clone(),
2817            bytes: *bytes,
2818            identity,
2819        });
2820        self.next += 1;
2821        Ok(true)
2822    }
2823}
2824
2825impl Read for PackageObjectReader<'_> {
2826    fn read(&mut self, buffer: &mut [u8]) -> std::io::Result<usize> {
2827        loop {
2828            if self.current.is_none() && !self.open_next()? {
2829                return Ok(0);
2830            }
2831            let read = self
2832                .current
2833                .as_mut()
2834                .expect("opened package chunk")
2835                .file
2836                .read(buffer)?;
2837            if read != 0 {
2838                return Ok(read);
2839            }
2840            let completed = self.current.take().expect("completed package chunk");
2841            let mut options = CapOpenOptions::new();
2842            options.read(true).follow(FollowSymlinks::No);
2843            let reopened = self.chunks.open_with(&completed.name, &options)?;
2844            let metadata = reopened.metadata()?;
2845            validate_package_regular_metadata(&metadata, &self.display.join(&completed.name))
2846                .map_err(|error| std::io::Error::other(error.to_string()))?;
2847            let identity = cap_file_identity(&reopened, &self.display.join(&completed.name))
2848                .map_err(|error| std::io::Error::other(error.to_string()))?;
2849            if metadata.len() != completed.bytes || identity != completed.identity {
2850                return Err(std::io::Error::other("package chunk changed during read"));
2851            }
2852        }
2853    }
2854}
2855
2856/// Plan directly from one retained, no-follow package authority.
2857///
2858/// This is the integration seam for CLIs and other process adapters: package
2859/// paths remain diagnostic-only, every planning input is opened relative to
2860/// the retained root, and the exact package shape is revalidated before the
2861/// caller can begin reconstruction.
2862pub fn plan_retained_package(
2863    package: &RetainedReconstructionPackage,
2864) -> Result<RootReconstructionPlan, RootReconstructionError> {
2865    let (index_encoded, _) = read_package_regular_with_identity(
2866        package,
2867        Path::new("index.json"),
2868        MAX_PACKAGE_INDEX_BYTES,
2869    )?;
2870    let count: ReferenceCountProbe = serde_json::from_slice(&index_encoded)
2871        .map_err(RootReconstructionError::InvalidIndexJson)?;
2872    if count.references.exceeds_maximum {
2873        return Err(RootReconstructionError::TooManyReferences {
2874            maximum: MAX_PACKAGE_REFERENCES,
2875        });
2876    }
2877    let index: PackageIndexWire = serde_json::from_slice(&index_encoded)
2878        .map_err(RootReconstructionError::InvalidIndexJson)?;
2879    let mut manifest_digests = BTreeSet::new();
2880    for reference in &index.references {
2881        if !is_sha256(&reference.chunk_manifest_sha256) {
2882            return Err(RootReconstructionError::InvalidManifestDigest {
2883                object_version_id: reference.object_version_id.clone(),
2884            });
2885        }
2886        manifest_digests.insert(reference.chunk_manifest_sha256.clone());
2887    }
2888    if manifest_digests.len() > MAX_DISTINCT_MANIFESTS {
2889        return Err(RootReconstructionError::TooManyManifests {
2890            maximum: MAX_DISTINCT_MANIFESTS,
2891        });
2892    }
2893    let (version_encoded, _) = read_package_regular_with_identity(
2894        package,
2895        Path::new("version.json"),
2896        MAX_PACKAGE_VERSION_BYTES,
2897    )?;
2898    let manifests_directory = open_package_directory(package, "manifests")?;
2899    let mut manifest_inputs = Vec::with_capacity(manifest_digests.len());
2900    for digest in manifest_digests {
2901        let name = format!("{digest}.json");
2902        let (encoded, _) = read_regular_from_with_identity(
2903            &manifests_directory,
2904            &package.display_root.join("manifests").join(&name),
2905            Path::new(&name),
2906            MAX_PACKAGE_MANIFEST_BYTES,
2907        )?;
2908        manifest_inputs.push(ManifestInput::new(digest, std::io::Cursor::new(encoded)));
2909    }
2910    let plan = decode_and_plan(
2911        std::io::Cursor::new(index_encoded),
2912        std::io::Cursor::new(version_encoded),
2913        manifest_inputs,
2914    )?;
2915    revalidate_package(package, &plan)?;
2916    Ok(plan)
2917}
2918
2919/// Derive the exact externally materialized package closure without reading
2920/// any manifest documents. Associations must be strictly ordered by Object
2921/// Version ID. Core derives every Object ID and role from the Version and
2922/// validates the complete Tombstone-fidelity closure.
2923pub fn derive_root_reconstruction_package_closure<VR, AI, TI>(
2924    version_reader: VR,
2925    associations: AI,
2926    tombstone_fidelity: TI,
2927) -> Result<RootReconstructionPackageClosure, RootReconstructionPackageBuildError>
2928where
2929    VR: Read,
2930    AI: IntoIterator<Item = RootReconstructionObjectAssociation>,
2931    TI: IntoIterator<Item = RootReconstructionTombstoneFidelity>,
2932{
2933    let encoded_version = read_bounded_version(version_reader)?;
2934    let version = FolderbaseVersion::decode_bounded(encoded_version.as_slice())
2935        .map_err(RootReconstructionError::InvalidVersion)?;
2936    let canonical_version_sha256 = version
2937        .canonical_digest()
2938        .map_err(RootReconstructionError::InvalidVersion)?;
2939    let encoded_version_sha256 = sha256(&encoded_version);
2940    let (expected, _) = expected_closure(&version);
2941    let expected_count = expected
2942        .values()
2943        .filter(|object| !object.roles.is_empty())
2944        .count();
2945
2946    let mut references = Vec::with_capacity(expected_count);
2947    let mut observed = BTreeSet::new();
2948    let mut previous: Option<String> = None;
2949    for (position, association) in associations.into_iter().enumerate() {
2950        if position >= MAX_PACKAGE_REFERENCES {
2951            return Err(RootReconstructionError::TooManyReferences {
2952                maximum: MAX_PACKAGE_REFERENCES,
2953            }
2954            .into());
2955        }
2956        let Some(expected_object) = expected.get(&association.object_version_id) else {
2957            return Err(RootReconstructionError::UnexpectedReference {
2958                object_version_id: association.object_version_id,
2959            }
2960            .into());
2961        };
2962        if expected_object.roles.is_empty() {
2963            return Err(RootReconstructionError::UnexpectedReference {
2964                object_version_id: association.object_version_id,
2965            }
2966            .into());
2967        }
2968        if !is_sha256(&association.chunk_manifest_sha256) {
2969            return Err(RootReconstructionError::InvalidManifestDigest {
2970                object_version_id: association.object_version_id,
2971            }
2972            .into());
2973        }
2974        if let Some(previous) = &previous {
2975            match previous
2976                .as_bytes()
2977                .cmp(association.object_version_id.as_bytes())
2978            {
2979                std::cmp::Ordering::Equal => {
2980                    return Err(RootReconstructionError::DuplicateReference {
2981                        object_version_id: association.object_version_id,
2982                    }
2983                    .into());
2984                }
2985                std::cmp::Ordering::Greater => {
2986                    return Err(RootReconstructionError::ReferencesOutOfOrder.into());
2987                }
2988                std::cmp::Ordering::Less => {}
2989            }
2990        }
2991        previous = Some(association.object_version_id.clone());
2992        let roles = expected_object.roles.iter().copied().collect();
2993        observed.insert(association.object_version_id.clone());
2994        references.push(PlannedObjectReference {
2995            object_version_id: association.object_version_id,
2996            object_id: expected_object.object_id.clone(),
2997            roles,
2998            chunk_manifest_sha256: association.chunk_manifest_sha256,
2999        });
3000    }
3001    for (object_version_id, expected_object) in &expected {
3002        if !expected_object.roles.is_empty() && !observed.contains(object_version_id) {
3003            return Err(RootReconstructionError::MissingReference {
3004                object_version_id: object_version_id.clone(),
3005            }
3006            .into());
3007        }
3008    }
3009
3010    let expected_fidelity = version
3011        .tombstones()
3012        .iter()
3013        .filter(|tombstone| tombstone.deleted_kind() == DeletedKind::RegularFile)
3014        .filter_map(|tombstone| {
3015            tombstone.last_object_version_id().map(|object_version_id| {
3016                (tombstone.path(), tombstone.object_id(), object_version_id)
3017            })
3018        })
3019        .collect::<Vec<_>>();
3020    let mut fidelity = Vec::with_capacity(expected_fidelity.len());
3021    for (position, record) in tombstone_fidelity.into_iter().enumerate() {
3022        let Some((path, object_id, object_version_id)) = expected_fidelity.get(position) else {
3023            return Err(RootReconstructionError::TombstoneFidelityMismatch.into());
3024        };
3025        if record.path != *path
3026            || record.object_id != *object_id
3027            || record.object_version_id != *object_version_id
3028        {
3029            return Err(RootReconstructionError::TombstoneFidelityMismatch.into());
3030        }
3031        fidelity.push(PlannedTombstoneFidelity {
3032            path: record.path,
3033            object_id: record.object_id,
3034            object_version_id: record.object_version_id,
3035            executable: record.executable,
3036        });
3037    }
3038    if fidelity.len() != expected_fidelity.len() {
3039        return Err(RootReconstructionError::TombstoneFidelityMismatch.into());
3040    }
3041
3042    Ok(RootReconstructionPackageClosure {
3043        encoded_version,
3044        folderbase_id: version.folderbase_id().to_owned(),
3045        folderbase_version_id: version.version_id().to_owned(),
3046        canonical_version_sha256,
3047        encoded_version_sha256,
3048        references,
3049        tombstone_fidelity: fidelity,
3050    })
3051}
3052
3053/// Build one canonical root-reconstruction package index from producer-held
3054/// immutable associations, then validate the result through the same public
3055/// decoder used by independent consumers.
3056pub fn build_root_reconstruction_package<VR, AI, TI, MR, MI>(
3057    version_reader: VR,
3058    associations: AI,
3059    tombstone_fidelity: TI,
3060    manifest_inputs: MI,
3061) -> Result<BuiltRootReconstructionPackage, RootReconstructionPackageBuildError>
3062where
3063    VR: Read,
3064    AI: IntoIterator<Item = RootReconstructionObjectAssociation>,
3065    TI: IntoIterator<Item = RootReconstructionTombstoneFidelity>,
3066    MR: Read,
3067    MI: IntoIterator<Item = ManifestInput<MR>>,
3068{
3069    let closure = derive_root_reconstruction_package_closure(
3070        version_reader,
3071        associations,
3072        tombstone_fidelity,
3073    )?;
3074
3075    let index = PackageIndexWire {
3076        format: PACKAGE_FORMAT_V1.to_owned(),
3077        folderbase_id: closure.folderbase_id.clone(),
3078        folderbase_version_id: closure.folderbase_version_id.clone(),
3079        canonical_version_sha256: closure.canonical_version_sha256.clone(),
3080        encoded_version_sha256: closure.encoded_version_sha256.clone(),
3081        limits: PackageLimitsWire::v1(),
3082        references: closure
3083            .references
3084            .iter()
3085            .map(|reference| ReferenceWire {
3086                object_version_id: reference.object_version_id.clone(),
3087                object_id: OptionalObjectId {
3088                    present: reference.object_id.is_some(),
3089                    value: reference.object_id.clone(),
3090                },
3091                roles: reference
3092                    .roles
3093                    .iter()
3094                    .copied()
3095                    .map(ReferenceRoleWire::from)
3096                    .collect(),
3097                chunk_manifest_sha256: reference.chunk_manifest_sha256.clone(),
3098            })
3099            .collect(),
3100        tombstone_fidelity: closure
3101            .tombstone_fidelity
3102            .iter()
3103            .map(|record| TombstoneFidelityWire {
3104                path: record.path.clone(),
3105                object_id: record.object_id.clone(),
3106                object_version_id: record.object_version_id.clone(),
3107                executable: record.executable,
3108            })
3109            .collect(),
3110    };
3111    let mut encoded_index = BoundedPackageIndexWriter::new();
3112    if let Err(source) = serde_json::to_writer(&mut encoded_index, &index) {
3113        if encoded_index.exceeded {
3114            return Err(RootReconstructionError::IndexTooLarge {
3115                maximum_bytes: MAX_PACKAGE_INDEX_BYTES,
3116            }
3117            .into());
3118        }
3119        return Err(RootReconstructionPackageBuildError::PackageEncoding(source));
3120    }
3121    if encoded_index.exceeded {
3122        return Err(RootReconstructionError::IndexTooLarge {
3123            maximum_bytes: MAX_PACKAGE_INDEX_BYTES,
3124        }
3125        .into());
3126    }
3127    let encoded_index = encoded_index.bytes;
3128    let plan = decode_and_plan(
3129        encoded_index.as_slice(),
3130        closure.encoded_version.as_slice(),
3131        manifest_inputs,
3132    )?;
3133    let manifest_digests = plan
3134        .manifests()
3135        .iter()
3136        .map(|manifest| manifest.chunk_manifest_sha256().to_owned())
3137        .collect();
3138    Ok(BuiltRootReconstructionPackage {
3139        encoded_index,
3140        encoded_version: closure.encoded_version,
3141        manifest_digests,
3142        plan,
3143    })
3144}
3145
3146/// Decode one closed package index and Version, validate its exact reference
3147/// and manifest closure, and return a deterministic bounded plan.
3148pub fn decode_and_plan<IR, VR, MR, MI>(
3149    index_reader: IR,
3150    version_reader: VR,
3151    manifest_inputs: MI,
3152) -> Result<RootReconstructionPlan, RootReconstructionError>
3153where
3154    IR: Read,
3155    VR: Read,
3156    MR: Read,
3157    MI: IntoIterator<Item = ManifestInput<MR>>,
3158{
3159    let index_encoded = read_bounded_index(index_reader)?;
3160    let count: ReferenceCountProbe = serde_json::from_slice(&index_encoded)
3161        .map_err(RootReconstructionError::InvalidIndexJson)?;
3162    if count.references.exceeds_maximum {
3163        return Err(RootReconstructionError::TooManyReferences {
3164            maximum: MAX_PACKAGE_REFERENCES,
3165        });
3166    }
3167    let index: PackageIndexWire = serde_json::from_slice(&index_encoded)
3168        .map_err(RootReconstructionError::InvalidIndexJson)?;
3169    if index.format != PACKAGE_FORMAT_V1 {
3170        return Err(RootReconstructionError::UnknownFormat);
3171    }
3172    if index.limits != PackageLimitsWire::v1() {
3173        return Err(RootReconstructionError::LimitsMismatch);
3174    }
3175
3176    let version_encoded = read_bounded_version(version_reader)?;
3177    let encoded_version_sha256 = sha256(&version_encoded);
3178    if index.encoded_version_sha256 != encoded_version_sha256 {
3179        return Err(RootReconstructionError::EncodedVersionDigestMismatch);
3180    }
3181    let version = FolderbaseVersion::decode_bounded(version_encoded.as_slice())
3182        .map_err(RootReconstructionError::InvalidVersion)?;
3183    if index.folderbase_id != version.folderbase_id() {
3184        return Err(RootReconstructionError::FolderbaseIdMismatch);
3185    }
3186    if index.folderbase_version_id != version.version_id() {
3187        return Err(RootReconstructionError::VersionIdMismatch);
3188    }
3189    let canonical_version_sha256 = version
3190        .canonical_digest()
3191        .map_err(RootReconstructionError::InvalidVersion)?;
3192    if index.canonical_version_sha256 != canonical_version_sha256 {
3193        return Err(RootReconstructionError::CanonicalVersionDigestMismatch);
3194    }
3195    if version.binding_count() > MAX_VISIBLE_ENTRIES {
3196        return Err(RootReconstructionError::LimitsMismatch);
3197    }
3198
3199    let tombstone_fidelity = validate_tombstone_fidelity(&version, &index.tombstone_fidelity)?;
3200    let (expected, derived_symlinks) = expected_closure(&version);
3201    let references = validate_references(index.references, &expected)?;
3202    let expected_manifest_digests = references
3203        .iter()
3204        .map(|reference| reference.chunk_manifest_sha256.clone())
3205        .collect::<BTreeSet<_>>();
3206    if expected_manifest_digests.len() > MAX_DISTINCT_MANIFESTS {
3207        return Err(RootReconstructionError::TooManyManifests {
3208            maximum: MAX_DISTINCT_MANIFESTS,
3209        });
3210    }
3211
3212    let mut manifests = BTreeMap::new();
3213    let mut distinct_chunks = BTreeSet::new();
3214    for (position, input) in manifest_inputs.into_iter().enumerate() {
3215        if position >= MAX_DISTINCT_MANIFESTS {
3216            return Err(RootReconstructionError::TooManyManifests {
3217                maximum: MAX_DISTINCT_MANIFESTS,
3218            });
3219        }
3220        let digest = input.chunk_manifest_sha256;
3221        if !expected_manifest_digests.contains(&digest) {
3222            return Err(RootReconstructionError::UnreferencedManifest {
3223                chunk_manifest_sha256: digest,
3224            });
3225        }
3226        if manifests.contains_key(&digest) {
3227            return Err(RootReconstructionError::DuplicateManifest {
3228                chunk_manifest_sha256: digest,
3229            });
3230        }
3231        let manifest = ChunkManifest::decode_bounded(input.encoded).map_err(|source| {
3232            RootReconstructionError::InvalidManifest {
3233                chunk_manifest_sha256: digest.clone(),
3234                source,
3235            }
3236        })?;
3237        let canonical = manifest.canonical_digest().map_err(|source| {
3238            RootReconstructionError::InvalidManifest {
3239                chunk_manifest_sha256: digest.clone(),
3240                source: ManifestError::InvalidManifest(source),
3241            }
3242        })?;
3243        if canonical != digest {
3244            return Err(RootReconstructionError::ManifestDigestMismatch {
3245                chunk_manifest_sha256: digest,
3246            });
3247        }
3248        for chunk in &manifest.chunks {
3249            distinct_chunks.insert(chunk.sha256.clone());
3250            if distinct_chunks.len() > MAX_DISTINCT_CHUNKS {
3251                return Err(RootReconstructionError::TooManyDistinctChunks {
3252                    maximum: MAX_DISTINCT_CHUNKS,
3253                });
3254            }
3255        }
3256        manifests.insert(
3257            canonical.clone(),
3258            PlannedManifest {
3259                chunk_manifest_sha256: canonical,
3260                object_sha256: manifest.object_sha256,
3261                object_bytes: manifest.object_bytes,
3262                chunk_count: manifest.chunks.len(),
3263            },
3264        );
3265    }
3266    for expected_digest in &expected_manifest_digests {
3267        if !manifests.contains_key(expected_digest) {
3268            return Err(RootReconstructionError::MissingManifest {
3269                chunk_manifest_sha256: expected_digest.clone(),
3270            });
3271        }
3272    }
3273
3274    let mut total_object_bytes = 0_u64;
3275    for reference in &references {
3276        let manifest = &manifests[&reference.chunk_manifest_sha256];
3277        let expected_object = &expected[&reference.object_version_id];
3278        if let Some(identity) = &expected_object.authenticated
3279            && (manifest.object_sha256 != identity.sha256
3280                || manifest.object_bytes != identity.bytes)
3281        {
3282            return Err(RootReconstructionError::ManifestObjectMismatch {
3283                object_version_id: reference.object_version_id.clone(),
3284            });
3285        }
3286        total_object_bytes = total_object_bytes
3287            .checked_add(manifest.object_bytes)
3288            .ok_or(RootReconstructionError::TotalObjectBytesTooLarge {
3289                maximum: MAX_TOTAL_OBJECT_BYTES,
3290            })?;
3291        if total_object_bytes > MAX_TOTAL_OBJECT_BYTES {
3292            return Err(RootReconstructionError::TotalObjectBytesTooLarge {
3293                maximum: MAX_TOTAL_OBJECT_BYTES,
3294            });
3295        }
3296    }
3297
3298    Ok(RootReconstructionPlan {
3299        package_index_sha256: sha256(&index_encoded),
3300        encoded_version_sha256,
3301        canonical_version_sha256,
3302        version,
3303        references,
3304        manifests: manifests.into_values().collect(),
3305        derived_symlinks,
3306        tombstone_fidelity,
3307        distinct_chunk_count: distinct_chunks.len(),
3308        total_object_bytes,
3309    })
3310}
3311
3312#[derive(Deserialize, Serialize)]
3313#[serde(deny_unknown_fields)]
3314struct PackageIndexWire {
3315    format: String,
3316    folderbase_id: String,
3317    folderbase_version_id: String,
3318    canonical_version_sha256: String,
3319    encoded_version_sha256: String,
3320    limits: PackageLimitsWire,
3321    references: Vec<ReferenceWire>,
3322    tombstone_fidelity: Vec<TombstoneFidelityWire>,
3323}
3324
3325#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]
3326#[serde(deny_unknown_fields)]
3327struct TombstoneFidelityWire {
3328    path: String,
3329    object_id: String,
3330    object_version_id: String,
3331    executable: bool,
3332}
3333
3334#[derive(Debug, Deserialize, Serialize, PartialEq, Eq)]
3335#[serde(deny_unknown_fields)]
3336struct PackageLimitsWire {
3337    max_index_bytes: u64,
3338    max_version_bytes: u64,
3339    max_manifest_bytes: u64,
3340    max_references: usize,
3341    max_distinct_manifests: usize,
3342    max_distinct_chunks: usize,
3343    max_chunks_per_manifest: usize,
3344    max_object_bytes: u64,
3345    max_total_object_bytes: u64,
3346    max_visible_entries: usize,
3347}
3348
3349impl PackageLimitsWire {
3350    fn v1() -> Self {
3351        Self {
3352            max_index_bytes: MAX_PACKAGE_INDEX_BYTES,
3353            max_version_bytes: MAX_PACKAGE_VERSION_BYTES,
3354            max_manifest_bytes: MAX_PACKAGE_MANIFEST_BYTES,
3355            max_references: MAX_PACKAGE_REFERENCES,
3356            max_distinct_manifests: MAX_DISTINCT_MANIFESTS,
3357            max_distinct_chunks: MAX_DISTINCT_CHUNKS,
3358            max_chunks_per_manifest: MAX_CHUNKS_PER_MANIFEST,
3359            max_object_bytes: MAX_PACKAGE_OBJECT_BYTES,
3360            max_total_object_bytes: MAX_TOTAL_OBJECT_BYTES,
3361            max_visible_entries: MAX_VISIBLE_ENTRIES,
3362        }
3363    }
3364}
3365
3366#[derive(Deserialize, Serialize)]
3367#[serde(deny_unknown_fields)]
3368struct ReferenceWire {
3369    object_version_id: String,
3370    #[serde(
3371        default,
3372        deserialize_with = "deserialize_optional_object_id",
3373        skip_serializing_if = "OptionalObjectId::is_absent",
3374        serialize_with = "serialize_optional_object_id"
3375    )]
3376    object_id: OptionalObjectId,
3377    #[serde(deserialize_with = "deserialize_bounded_roles")]
3378    roles: Vec<ReferenceRoleWire>,
3379    chunk_manifest_sha256: String,
3380}
3381
3382#[derive(Clone, Copy, Deserialize, Serialize, PartialEq, Eq)]
3383#[serde(rename_all = "snake_case")]
3384enum ReferenceRoleWire {
3385    RootManifest,
3386    LiveRegularFile,
3387    RetainedTombstone,
3388}
3389
3390impl From<ReconstructionReferenceRole> for ReferenceRoleWire {
3391    fn from(role: ReconstructionReferenceRole) -> Self {
3392        match role {
3393            ReconstructionReferenceRole::RootManifest => Self::RootManifest,
3394            ReconstructionReferenceRole::LiveRegularFile => Self::LiveRegularFile,
3395            ReconstructionReferenceRole::RetainedTombstone => Self::RetainedTombstone,
3396        }
3397    }
3398}
3399
3400#[derive(Default)]
3401struct OptionalObjectId {
3402    present: bool,
3403    value: Option<String>,
3404}
3405
3406struct BoundedPackageIndexWriter {
3407    bytes: Vec<u8>,
3408    exceeded: bool,
3409}
3410
3411impl BoundedPackageIndexWriter {
3412    fn new() -> Self {
3413        Self {
3414            bytes: Vec::with_capacity(64 * 1024),
3415            exceeded: false,
3416        }
3417    }
3418}
3419
3420impl Write for BoundedPackageIndexWriter {
3421    fn write(&mut self, bytes: &[u8]) -> std::io::Result<usize> {
3422        let Some(next_len) = (self.bytes.len() as u64).checked_add(bytes.len() as u64) else {
3423            self.exceeded = true;
3424            return Err(std::io::Error::other("package index size overflow"));
3425        };
3426        if next_len > MAX_PACKAGE_INDEX_BYTES {
3427            self.exceeded = true;
3428            return Err(std::io::Error::other(
3429                "package index exceeds its byte limit",
3430            ));
3431        }
3432        self.bytes.extend_from_slice(bytes);
3433        Ok(bytes.len())
3434    }
3435
3436    fn flush(&mut self) -> std::io::Result<()> {
3437        Ok(())
3438    }
3439}
3440
3441impl OptionalObjectId {
3442    fn is_absent(&self) -> bool {
3443        !self.present
3444    }
3445}
3446
3447fn serialize_optional_object_id<S>(
3448    object_id: &OptionalObjectId,
3449    serializer: S,
3450) -> Result<S::Ok, S::Error>
3451where
3452    S: serde::Serializer,
3453{
3454    object_id.value.serialize(serializer)
3455}
3456
3457fn deserialize_optional_object_id<'de, D>(deserializer: D) -> Result<OptionalObjectId, D::Error>
3458where
3459    D: serde::Deserializer<'de>,
3460{
3461    Ok(OptionalObjectId {
3462        present: true,
3463        value: Option::<String>::deserialize(deserializer)?,
3464    })
3465}
3466
3467fn deserialize_bounded_roles<'de, D>(deserializer: D) -> Result<Vec<ReferenceRoleWire>, D::Error>
3468where
3469    D: serde::Deserializer<'de>,
3470{
3471    struct RolesVisitor;
3472    impl<'de> Visitor<'de> for RolesVisitor {
3473        type Value = Vec<ReferenceRoleWire>;
3474
3475        fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
3476            formatter.write_str("a canonical root-reconstruction role array")
3477        }
3478
3479        fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
3480        where
3481            A: SeqAccess<'de>,
3482        {
3483            let mut roles = Vec::with_capacity(2);
3484            while let Some(role) = sequence.next_element()? {
3485                if roles.len() == 2 {
3486                    return Err(serde::de::Error::custom("reference has too many roles"));
3487                }
3488                roles.push(role);
3489            }
3490            Ok(roles)
3491        }
3492    }
3493    deserializer.deserialize_seq(RolesVisitor)
3494}
3495
3496#[derive(Deserialize)]
3497struct ReferenceCountProbe {
3498    references: ReferenceCount,
3499}
3500
3501struct ReferenceCount {
3502    exceeds_maximum: bool,
3503}
3504
3505impl<'de> Deserialize<'de> for ReferenceCount {
3506    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
3507    where
3508        D: serde::Deserializer<'de>,
3509    {
3510        struct CountVisitor;
3511        impl<'de> Visitor<'de> for CountVisitor {
3512            type Value = ReferenceCount;
3513
3514            fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
3515                formatter.write_str("a package reference array")
3516            }
3517
3518            fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
3519            where
3520                A: SeqAccess<'de>,
3521            {
3522                let mut count = 0_usize;
3523                while sequence.next_element::<IgnoredAny>()?.is_some() {
3524                    count = count.saturating_add(1);
3525                }
3526                Ok(ReferenceCount {
3527                    exceeds_maximum: count > MAX_PACKAGE_REFERENCES,
3528                })
3529            }
3530        }
3531        deserializer.deserialize_seq(CountVisitor)
3532    }
3533}
3534
3535#[derive(Clone)]
3536struct ObjectIdentity {
3537    sha256: String,
3538    bytes: u64,
3539}
3540
3541struct ExpectedObject {
3542    object_id: Option<String>,
3543    roles: BTreeSet<ReconstructionReferenceRole>,
3544    authenticated: Option<ObjectIdentity>,
3545}
3546
3547fn expected_closure(
3548    version: &FolderbaseVersion,
3549) -> (BTreeMap<String, ExpectedObject>, Vec<DerivedSymlink>) {
3550    let root = version.root_manifest();
3551    let mut expected = BTreeMap::from([(
3552        root.object_version_id().to_owned(),
3553        ExpectedObject {
3554            object_id: None,
3555            roles: BTreeSet::from([ReconstructionReferenceRole::RootManifest]),
3556            authenticated: Some(ObjectIdentity {
3557                sha256: root.content_sha256().to_owned(),
3558                bytes: root.bytes(),
3559            }),
3560        },
3561    )]);
3562    let mut symlinks = Vec::new();
3563    for binding in version.bindings() {
3564        let Some(object_version_id) = binding.object_version_id() else {
3565            continue;
3566        };
3567        match binding.kind() {
3568            PathBindingKind::Directory => {}
3569            PathBindingKind::RegularFile => {
3570                expected.insert(
3571                    object_version_id.to_owned(),
3572                    ExpectedObject {
3573                        object_id: Some(binding.object_id().to_owned()),
3574                        roles: BTreeSet::from([ReconstructionReferenceRole::LiveRegularFile]),
3575                        authenticated: Some(ObjectIdentity {
3576                            sha256: binding.content_sha256().expect("regular digest").to_owned(),
3577                            bytes: binding.bytes().expect("regular length"),
3578                        }),
3579                    },
3580                );
3581            }
3582            PathBindingKind::Symlink => {
3583                let target = binding.symlink_target().expect("symlink target");
3584                let identity = ObjectIdentity {
3585                    sha256: sha256(target.as_bytes()),
3586                    bytes: target.len() as u64,
3587                };
3588                expected.insert(
3589                    object_version_id.to_owned(),
3590                    ExpectedObject {
3591                        object_id: Some(binding.object_id().to_owned()),
3592                        roles: BTreeSet::new(),
3593                        authenticated: Some(identity.clone()),
3594                    },
3595                );
3596                symlinks.push(DerivedSymlink {
3597                    path: binding.path().to_owned(),
3598                    object_id: binding.object_id().to_owned(),
3599                    object_version_id: object_version_id.to_owned(),
3600                    target: target.to_owned(),
3601                    content_sha256: identity.sha256,
3602                    bytes: identity.bytes,
3603                });
3604            }
3605        }
3606    }
3607    for tombstone in version.tombstones() {
3608        let Some(object_version_id) = tombstone.last_object_version_id() else {
3609            continue;
3610        };
3611        expected
3612            .entry(object_version_id.to_owned())
3613            .and_modify(|object| {
3614                object
3615                    .roles
3616                    .insert(ReconstructionReferenceRole::RetainedTombstone);
3617            })
3618            .or_insert_with(|| ExpectedObject {
3619                object_id: Some(tombstone.object_id().to_owned()),
3620                roles: BTreeSet::from([ReconstructionReferenceRole::RetainedTombstone]),
3621                authenticated: None,
3622            });
3623    }
3624    (expected, symlinks)
3625}
3626
3627fn validate_tombstone_fidelity(
3628    version: &FolderbaseVersion,
3629    supplied: &[TombstoneFidelityWire],
3630) -> Result<Vec<PlannedTombstoneFidelity>, RootReconstructionError> {
3631    let expected = version
3632        .tombstones()
3633        .iter()
3634        .filter(|tombstone| tombstone.deleted_kind() == DeletedKind::RegularFile)
3635        .filter_map(|tombstone| {
3636            tombstone.last_object_version_id().map(|object_version_id| {
3637                (tombstone.path(), tombstone.object_id(), object_version_id)
3638            })
3639        })
3640        .collect::<Vec<_>>();
3641    if supplied.len() != expected.len() {
3642        return Err(RootReconstructionError::TombstoneFidelityMismatch);
3643    }
3644    let mut planned = Vec::with_capacity(supplied.len());
3645    let mut previous_path: Option<&str> = None;
3646    for (record, (path, object_id, object_version_id)) in supplied.iter().zip(expected) {
3647        if previous_path.is_some_and(|previous| previous.as_bytes() >= record.path.as_bytes())
3648            || record.path != path
3649            || record.object_id != object_id
3650            || record.object_version_id != object_version_id
3651        {
3652            return Err(RootReconstructionError::TombstoneFidelityMismatch);
3653        }
3654        previous_path = Some(&record.path);
3655        planned.push(PlannedTombstoneFidelity {
3656            path: record.path.clone(),
3657            object_id: record.object_id.clone(),
3658            object_version_id: record.object_version_id.clone(),
3659            executable: record.executable,
3660        });
3661    }
3662    Ok(planned)
3663}
3664
3665fn validate_references(
3666    references: Vec<ReferenceWire>,
3667    expected: &BTreeMap<String, ExpectedObject>,
3668) -> Result<Vec<PlannedObjectReference>, RootReconstructionError> {
3669    let mut planned = Vec::with_capacity(references.len());
3670    let mut previous: Option<String> = None;
3671    let mut observed = BTreeSet::new();
3672    for reference in references {
3673        if let Some(previous) = &previous {
3674            match previous
3675                .as_bytes()
3676                .cmp(reference.object_version_id.as_bytes())
3677            {
3678                std::cmp::Ordering::Equal => {
3679                    return Err(RootReconstructionError::DuplicateReference {
3680                        object_version_id: reference.object_version_id,
3681                    });
3682                }
3683                std::cmp::Ordering::Greater => {
3684                    return Err(RootReconstructionError::ReferencesOutOfOrder);
3685                }
3686                std::cmp::Ordering::Less => {}
3687            }
3688        }
3689        previous = Some(reference.object_version_id.clone());
3690        let roles = canonical_roles(&reference)?;
3691        let Some(expected_object) = expected.get(&reference.object_version_id) else {
3692            return Err(RootReconstructionError::UnexpectedReference {
3693                object_version_id: reference.object_version_id,
3694            });
3695        };
3696        let expected_roles = expected_object.roles.iter().copied().collect::<Vec<_>>();
3697        if roles != expected_roles || reference.object_id.value != expected_object.object_id {
3698            return Err(RootReconstructionError::ReferenceMismatch {
3699                object_version_id: reference.object_version_id,
3700            });
3701        }
3702        if !is_sha256(&reference.chunk_manifest_sha256) {
3703            return Err(RootReconstructionError::InvalidManifestDigest {
3704                object_version_id: reference.object_version_id,
3705            });
3706        }
3707        observed.insert(reference.object_version_id.clone());
3708        planned.push(PlannedObjectReference {
3709            object_version_id: reference.object_version_id,
3710            object_id: reference.object_id.value,
3711            roles,
3712            chunk_manifest_sha256: reference.chunk_manifest_sha256,
3713        });
3714    }
3715    for (object_version_id, expected_object) in expected {
3716        if !expected_object.roles.is_empty() && !observed.contains(object_version_id) {
3717            return Err(RootReconstructionError::MissingReference {
3718                object_version_id: object_version_id.clone(),
3719            });
3720        }
3721    }
3722    Ok(planned)
3723}
3724
3725fn canonical_roles(
3726    reference: &ReferenceWire,
3727) -> Result<Vec<ReconstructionReferenceRole>, RootReconstructionError> {
3728    let roles = match reference.roles.as_slice() {
3729        [ReferenceRoleWire::RootManifest] if !reference.object_id.present => {
3730            vec![ReconstructionReferenceRole::RootManifest]
3731        }
3732        [ReferenceRoleWire::LiveRegularFile] if reference.object_id.value.is_some() => {
3733            vec![ReconstructionReferenceRole::LiveRegularFile]
3734        }
3735        [ReferenceRoleWire::RetainedTombstone] if reference.object_id.value.is_some() => {
3736            vec![ReconstructionReferenceRole::RetainedTombstone]
3737        }
3738        [
3739            ReferenceRoleWire::LiveRegularFile,
3740            ReferenceRoleWire::RetainedTombstone,
3741        ] if reference.object_id.value.is_some() => {
3742            vec![
3743                ReconstructionReferenceRole::LiveRegularFile,
3744                ReconstructionReferenceRole::RetainedTombstone,
3745            ]
3746        }
3747        _ => {
3748            return Err(RootReconstructionError::InvalidReferenceRoles {
3749                object_version_id: reference.object_version_id.clone(),
3750            });
3751        }
3752    };
3753    Ok(roles)
3754}
3755
3756fn read_bounded_index(mut reader: impl Read) -> Result<Vec<u8>, RootReconstructionError> {
3757    let mut encoded = Vec::new();
3758    reader
3759        .by_ref()
3760        .take(MAX_PACKAGE_INDEX_BYTES + 1)
3761        .read_to_end(&mut encoded)
3762        .map_err(RootReconstructionError::IndexReader)?;
3763    if encoded.len() as u64 > MAX_PACKAGE_INDEX_BYTES {
3764        return Err(RootReconstructionError::IndexTooLarge {
3765            maximum_bytes: MAX_PACKAGE_INDEX_BYTES,
3766        });
3767    }
3768    Ok(encoded)
3769}
3770
3771fn read_bounded_version(mut reader: impl Read) -> Result<Vec<u8>, RootReconstructionError> {
3772    let mut encoded = Vec::new();
3773    reader
3774        .by_ref()
3775        .take(MAX_PACKAGE_VERSION_BYTES + 1)
3776        .read_to_end(&mut encoded)
3777        .map_err(RootReconstructionError::VersionReader)?;
3778    if encoded.len() as u64 > MAX_PACKAGE_VERSION_BYTES {
3779        return Err(RootReconstructionError::VersionTooLarge {
3780            maximum_bytes: MAX_PACKAGE_VERSION_BYTES,
3781        });
3782    }
3783    Ok(encoded)
3784}
3785
3786fn sha256(bytes: &[u8]) -> String {
3787    format!("{:x}", Sha256::digest(bytes))
3788}
3789
3790fn root_reconstruction_request_sha256(
3791    operation_id: &str,
3792    package_index_sha256: &str,
3793) -> Result<String, RootReconstructionError> {
3794    if !is_sha256(package_index_sha256) {
3795        return Err(RootReconstructionError::InvalidOperation);
3796    }
3797    let operation = operation_id.as_bytes();
3798    let operation_bytes =
3799        u32::try_from(operation.len()).map_err(|_| RootReconstructionError::InvalidOperation)?;
3800    let mut digest = Sha256::new();
3801    digest.update(b"folderbase-root-reconstruction-request-v1\0");
3802    digest.update(operation_bytes.to_be_bytes());
3803    digest.update(operation);
3804    let mut pin = [0_u8; 32];
3805    for (index, pair) in package_index_sha256.as_bytes().chunks_exact(2).enumerate() {
3806        let encoded = std::str::from_utf8(pair)
3807            .ok()
3808            .and_then(|value| u8::from_str_radix(value, 16).ok())
3809            .ok_or(RootReconstructionError::InvalidOperation)?;
3810        pin[index] = encoded;
3811    }
3812    digest.update(pin);
3813    Ok(format!("{:x}", digest.finalize()))
3814}
3815
3816fn is_sha256(value: &str) -> bool {
3817    value.len() == 64
3818        && value
3819            .bytes()
3820            .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
3821}
3822
3823#[cfg(test)]
3824mod tests {
3825    use std::{
3826        collections::BTreeMap,
3827        io::{Cursor, Read as _},
3828        panic::{AssertUnwindSafe, catch_unwind},
3829        path::Path,
3830    };
3831
3832    use serde_json::{Value, json};
3833    use sha2::{Digest, Sha256};
3834
3835    use super::{
3836        BuiltRootReconstructionPackage, COMPLETED_RECONSTRUCTION_PATH, MAX_PACKAGE_INDEX_BYTES,
3837        MAX_PACKAGE_MANIFEST_BYTES, MAX_PACKAGE_REFERENCES, RetainedReconstructionDestination,
3838        RetainedReconstructionPackage, RootReconstructionError,
3839        RootReconstructionObjectAssociation, RootReconstructionOperation,
3840        RootReconstructionPackageBuildError, RootReconstructionPhase,
3841        RootReconstructionTombstoneFidelity, build_root_reconstruction_package,
3842        can_project_reconstructed_object, execute_root_reconstruction,
3843        execute_root_reconstruction_with_phase_callback, plan_retained_package,
3844        root_reconstruction_request_sha256, stage_owner_name, stage_proof_name, staged_root_name,
3845    };
3846    use super::{ManifestInput, ReconstructionReferenceRole, decode_and_plan};
3847    use crate::{
3848        folderbase_version::FolderbaseVersion,
3849        physical_identity::PhysicalIdentity,
3850        transfer_manifest::{
3851            CHUNKING_ALGORITHM_V1, ChunkDescriptor, ChunkManifest, MANIFEST_FORMAT_V1,
3852            ManifestError, STANDARD_PROFILE_V1,
3853        },
3854    };
3855
3856    const FOLDERBASE_ID: &str = "folderbase_01900000-0000-7000-8000-000000000001";
3857    const FOLDERBASE_VERSION_ID: &str = "fbversion_01900000-0000-7000-8000-000000000002";
3858    const ROOT_VERSION_ID: &str = "version_01900000-0000-7000-8000-000000000003";
3859    const LIVE_VERSION_ID: &str = "version_01900000-0000-7000-8000-000000000004";
3860    const SYMLINK_VERSION_ID: &str = "version_01900000-0000-7000-8000-000000000005";
3861    const LIVE_OBJECT_ID: &str = "obj_01900000-0000-7000-8000-000000000006";
3862
3863    struct Fixture {
3864        index: Vec<u8>,
3865        version: Vec<u8>,
3866        manifests: Vec<ManifestInput<Cursor<Vec<u8>>>>,
3867    }
3868
3869    #[test]
3870    fn complete_package_plans_exact_reference_closure_and_derived_symlink() {
3871        let fixture = complete_fixture();
3872
3873        let plan = decode_and_plan(
3874            fixture.index.as_slice(),
3875            fixture.version.as_slice(),
3876            fixture.manifests,
3877        )
3878        .expect("complete package should plan");
3879
3880        assert_eq!(plan.version().folderbase_id(), FOLDERBASE_ID);
3881        assert_eq!(plan.version().version_id(), FOLDERBASE_VERSION_ID);
3882        assert_eq!(plan.references().len(), 2);
3883        assert_eq!(
3884            plan.references()[1].roles(),
3885            &[
3886                ReconstructionReferenceRole::LiveRegularFile,
3887                ReconstructionReferenceRole::RetainedTombstone,
3888            ]
3889        );
3890        assert_eq!(plan.manifests().len(), 2);
3891        assert_eq!(plan.derived_symlinks().len(), 1);
3892        assert_eq!(plan.derived_symlinks()[0].path(), "shortcut");
3893        assert_eq!(plan.derived_symlinks()[0].target(), "current.txt");
3894        assert_eq!(
3895            plan.derived_symlinks()[0].content_sha256(),
3896            sha256(b"current.txt")
3897        );
3898        assert_eq!(plan.derived_symlinks()[0].bytes(), 11);
3899        assert_eq!(plan.externally_materialized_object_count(), 2);
3900        assert_eq!(plan.visible_entry_count(), 2);
3901        assert_eq!(
3902            plan.total_object_bytes(),
3903            root_manifest_bytes().len() as u64 + 7
3904        );
3905    }
3906
3907    #[test]
3908    fn public_builder_derives_the_exact_package_without_a_roleless_symlink_reference() {
3909        let fixture = complete_fixture();
3910        let root_manifest = manifest(&root_manifest_bytes(), 0x11);
3911        let live_manifest = manifest(b"payload", 0x22);
3912        let associations = vec![
3913            RootReconstructionObjectAssociation::new(
3914                ROOT_VERSION_ID,
3915                root_manifest
3916                    .canonical_digest()
3917                    .expect("root manifest digest"),
3918            ),
3919            RootReconstructionObjectAssociation::new(
3920                LIVE_VERSION_ID,
3921                live_manifest
3922                    .canonical_digest()
3923                    .expect("live manifest digest"),
3924            ),
3925        ];
3926        let fidelity = vec![RootReconstructionTombstoneFidelity::new(
3927            "previous.txt",
3928            LIVE_OBJECT_ID,
3929            LIVE_VERSION_ID,
3930            false,
3931        )];
3932
3933        let package = build_root_reconstruction_package(
3934            fixture.version.as_slice(),
3935            associations,
3936            fidelity,
3937            fixture.manifests,
3938        )
3939        .expect("Core-owned deterministic package");
3940
3941        assert_eq!(package.plan().references().len(), 2);
3942        assert_eq!(package.plan().derived_symlinks().len(), 1);
3943        assert_eq!(package.plan().derived_symlinks()[0].path(), "shortcut");
3944        assert_eq!(package.manifest_digests().len(), 2);
3945        let index: Value =
3946            serde_json::from_slice(package.encoded_index()).expect("public package index JSON");
3947        assert!(
3948            index["references"]
3949                .as_array()
3950                .expect("reference array")
3951                .iter()
3952                .all(|reference| !reference["roles"]
3953                    .as_array()
3954                    .expect("role array")
3955                    .is_empty())
3956        );
3957    }
3958
3959    #[test]
3960    fn public_builder_rejects_a_live_symlink_as_an_external_object_reference() {
3961        let fixture = complete_fixture();
3962        let root_manifest = manifest(&root_manifest_bytes(), 0x11);
3963        let live_manifest = manifest(b"payload", 0x22);
3964        let associations = vec![
3965            RootReconstructionObjectAssociation::new(
3966                ROOT_VERSION_ID,
3967                root_manifest
3968                    .canonical_digest()
3969                    .expect("root manifest digest"),
3970            ),
3971            RootReconstructionObjectAssociation::new(
3972                LIVE_VERSION_ID,
3973                live_manifest
3974                    .canonical_digest()
3975                    .expect("live manifest digest"),
3976            ),
3977            RootReconstructionObjectAssociation::new(
3978                SYMLINK_VERSION_ID,
3979                "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3980            ),
3981        ];
3982
3983        let error = build_root_reconstruction_package(
3984            fixture.version.as_slice(),
3985            associations,
3986            [RootReconstructionTombstoneFidelity::new(
3987                "previous.txt",
3988                LIVE_OBJECT_ID,
3989                LIVE_VERSION_ID,
3990                false,
3991            )],
3992            fixture.manifests,
3993        )
3994        .expect_err("symlink bytes are already bound by the Version");
3995
3996        assert!(matches!(
3997            error,
3998            RootReconstructionPackageBuildError::Validation(
3999                RootReconstructionError::UnexpectedReference { object_version_id }
4000            )
4001                if object_version_id == SYMLINK_VERSION_ID
4002        ));
4003    }
4004
4005    #[test]
4006    fn public_builder_rejects_an_oversized_unknown_association_before_retaining_it() {
4007        let fixture = complete_fixture();
4008        let oversized_object_version_id = "x".repeat(MAX_PACKAGE_INDEX_BYTES as usize + 1);
4009
4010        let error = build_root_reconstruction_package(
4011            fixture.version.as_slice(),
4012            [RootReconstructionObjectAssociation::new(
4013                oversized_object_version_id,
4014                "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4015            )],
4016            [RootReconstructionTombstoneFidelity::new(
4017                "previous.txt",
4018                LIVE_OBJECT_ID,
4019                LIVE_VERSION_ID,
4020                false,
4021            )],
4022            fixture.manifests,
4023        )
4024        .expect_err("unknown association must be rejected before it is retained");
4025
4026        assert!(matches!(
4027            error,
4028            RootReconstructionPackageBuildError::Validation(
4029                RootReconstructionError::UnexpectedReference { .. }
4030            )
4031        ));
4032    }
4033
4034    #[test]
4035    fn public_builder_rejects_an_incomplete_external_object_closure() {
4036        let fixture = complete_fixture();
4037        let root_manifest = manifest(&root_manifest_bytes(), 0x11);
4038
4039        let error = build_root_reconstruction_package(
4040            fixture.version.as_slice(),
4041            [RootReconstructionObjectAssociation::new(
4042                ROOT_VERSION_ID,
4043                root_manifest
4044                    .canonical_digest()
4045                    .expect("root manifest digest"),
4046            )],
4047            [RootReconstructionTombstoneFidelity::new(
4048                "previous.txt",
4049                LIVE_OBJECT_ID,
4050                LIVE_VERSION_ID,
4051                false,
4052            )],
4053            fixture.manifests,
4054        )
4055        .expect_err("every external object must be represented");
4056
4057        assert!(matches!(
4058            error,
4059            RootReconstructionPackageBuildError::Validation(
4060                RootReconstructionError::MissingReference { object_version_id }
4061            )
4062                if object_version_id == LIVE_VERSION_ID
4063        ));
4064    }
4065
4066    #[test]
4067    fn public_builder_rejects_oversized_untrusted_fidelity_before_encoding() {
4068        let fixture = complete_fixture();
4069        let root_manifest = manifest(&root_manifest_bytes(), 0x11);
4070        let live_manifest = manifest(b"payload", 0x22);
4071        let oversized_path = "x".repeat(MAX_PACKAGE_INDEX_BYTES as usize + 1);
4072
4073        let error = build_root_reconstruction_package(
4074            fixture.version.as_slice(),
4075            [
4076                RootReconstructionObjectAssociation::new(
4077                    ROOT_VERSION_ID,
4078                    root_manifest
4079                        .canonical_digest()
4080                        .expect("root manifest digest"),
4081                ),
4082                RootReconstructionObjectAssociation::new(
4083                    LIVE_VERSION_ID,
4084                    live_manifest
4085                        .canonical_digest()
4086                        .expect("live manifest digest"),
4087                ),
4088            ],
4089            [RootReconstructionTombstoneFidelity::new(
4090                oversized_path,
4091                LIVE_OBJECT_ID,
4092                LIVE_VERSION_ID,
4093                false,
4094            )],
4095            fixture.manifests,
4096        )
4097        .expect_err("untrusted fidelity must match the bounded Version before encoding");
4098
4099        assert!(matches!(
4100            error,
4101            RootReconstructionPackageBuildError::Validation(
4102                RootReconstructionError::TombstoneFidelityMismatch
4103            )
4104        ));
4105    }
4106
4107    #[test]
4108    fn public_builder_derives_a_retained_tombstone_only_role() {
4109        let fixture = tombstone_only_fixture();
4110        let root_manifest = manifest(&root_manifest_bytes(), 0x11);
4111        let retained_manifest = manifest(b"payload", 0x22);
4112
4113        let package = build_root_reconstruction_package(
4114            fixture.version.as_slice(),
4115            [
4116                RootReconstructionObjectAssociation::new(
4117                    ROOT_VERSION_ID,
4118                    root_manifest
4119                        .canonical_digest()
4120                        .expect("root manifest digest"),
4121                ),
4122                RootReconstructionObjectAssociation::new(
4123                    LIVE_VERSION_ID,
4124                    retained_manifest
4125                        .canonical_digest()
4126                        .expect("retained manifest digest"),
4127                ),
4128            ],
4129            [RootReconstructionTombstoneFidelity::new(
4130                "previous.txt",
4131                LIVE_OBJECT_ID,
4132                LIVE_VERSION_ID,
4133                true,
4134            )],
4135            fixture.manifests,
4136        )
4137        .expect("Tombstone-only package");
4138
4139        assert_eq!(
4140            package.plan().references()[1].roles(),
4141            &[ReconstructionReferenceRole::RetainedTombstone]
4142        );
4143        assert!(package.plan().tombstone_fidelity()[0].executable());
4144    }
4145
4146    #[test]
4147    fn public_builder_is_deterministic_for_the_same_exact_inputs() {
4148        fn build() -> BuiltRootReconstructionPackage {
4149            let fixture = complete_fixture();
4150            let root_manifest = manifest(&root_manifest_bytes(), 0x11);
4151            let live_manifest = manifest(b"payload", 0x22);
4152            build_root_reconstruction_package(
4153                fixture.version.as_slice(),
4154                [
4155                    RootReconstructionObjectAssociation::new(
4156                        ROOT_VERSION_ID,
4157                        root_manifest
4158                            .canonical_digest()
4159                            .expect("root manifest digest"),
4160                    ),
4161                    RootReconstructionObjectAssociation::new(
4162                        LIVE_VERSION_ID,
4163                        live_manifest
4164                            .canonical_digest()
4165                            .expect("live manifest digest"),
4166                    ),
4167                ],
4168                [RootReconstructionTombstoneFidelity::new(
4169                    "previous.txt",
4170                    LIVE_OBJECT_ID,
4171                    LIVE_VERSION_ID,
4172                    false,
4173                )],
4174                fixture.manifests,
4175            )
4176            .expect("deterministic package")
4177        }
4178
4179        let first = build();
4180        let second = build();
4181
4182        assert_eq!(first.encoded_index(), second.encoded_index());
4183        assert_eq!(first.encoded_version(), second.encoded_version());
4184        assert_eq!(first.manifest_digests(), second.manifest_digests());
4185        assert_eq!(
4186            sha256(first.encoded_index()),
4187            "9a25ad9ec24a9275e90a42c93cf669552977314ce91b8b5f70491d23edb57258"
4188        );
4189    }
4190
4191    #[test]
4192    fn retained_package_planning_uses_the_exact_nofollow_package_shape() {
4193        let temporary = tempfile::tempdir().expect("temporary root");
4194        let source = temporary.path().join("package");
4195        std::fs::create_dir(&source).expect("package root");
4196        let fixture = complete_fixture();
4197        write_package(&source, &fixture);
4198        let package = RetainedReconstructionPackage::open(&source).expect("retained package");
4199
4200        let plan = plan_retained_package(&package).expect("retained package plan");
4201
4202        assert_eq!(plan.version().version_id(), FOLDERBASE_VERSION_ID);
4203        assert_eq!(plan.package_index_sha256(), sha256(&fixture.index));
4204        assert_eq!(plan.externally_materialized_object_count(), 2);
4205        assert!(can_project_reconstructed_object("current.txt"));
4206        assert!(!can_project_reconstructed_object("repo/.git/HEAD"));
4207        assert!(!can_project_reconstructed_object(
4208            ".folderbase/private.json"
4209        ));
4210
4211        #[cfg(unix)]
4212        {
4213            std::os::unix::fs::symlink("version.json", source.join("version-alias.json"))
4214                .expect("unsafe package alias");
4215            assert!(matches!(
4216                plan_retained_package(&package),
4217                Err(RootReconstructionError::UnsafePackage(path)) if path == source
4218            ));
4219        }
4220    }
4221
4222    #[test]
4223    fn destination_inside_source_is_rejected_before_the_package_changes() {
4224        let temporary = tempfile::tempdir().expect("temporary root");
4225        let source = temporary.path().join("package");
4226        std::fs::create_dir(&source).expect("package root");
4227        let fixture = complete_fixture();
4228        write_package(&source, &fixture);
4229        let package = RetainedReconstructionPackage::open(&source).expect("retained package");
4230        let plan = plan_retained_package(&package).expect("retained package plan");
4231        let destination = RetainedReconstructionDestination::open(&source, "restored")
4232            .expect("retained destination inside source");
4233        let before = package_tree_snapshot(&source);
4234
4235        let result = execute_root_reconstruction(
4236            RootReconstructionOperation::new(
4237                &plan,
4238                "reconstruction_01900000-0000-7000-8000-000000000201",
4239                plan.package_index_sha256(),
4240            )
4241            .expect("valid operation"),
4242            &package,
4243            &destination,
4244        );
4245
4246        assert!(matches!(
4247            result,
4248            Err(RootReconstructionError::InvalidDestination)
4249        ));
4250        assert_eq!(package_tree_snapshot(&source), before);
4251    }
4252
4253    #[test]
4254    fn source_inside_destination_parent_is_rejected_before_the_package_changes() {
4255        let temporary = tempfile::tempdir().expect("temporary root");
4256        let destination_parent = temporary.path().join("destination-parent");
4257        let source = destination_parent.join("package");
4258        std::fs::create_dir(&destination_parent).expect("destination parent");
4259        std::fs::create_dir(&source).expect("package root");
4260        let fixture = complete_fixture();
4261        write_package(&source, &fixture);
4262        let package = RetainedReconstructionPackage::open(&source).expect("retained package");
4263        let plan = plan_retained_package(&package).expect("retained package plan");
4264        let destination = RetainedReconstructionDestination::open(&destination_parent, "restored")
4265            .expect("retained destination around source");
4266        let before = package_tree_snapshot(&source);
4267
4268        let result = execute_root_reconstruction(
4269            RootReconstructionOperation::new(
4270                &plan,
4271                "reconstruction_01900000-0000-7000-8000-000000000202",
4272                plan.package_index_sha256(),
4273            )
4274            .expect("valid operation"),
4275            &package,
4276            &destination,
4277        );
4278
4279        assert!(matches!(
4280            result,
4281            Err(RootReconstructionError::InvalidDestination)
4282        ));
4283        assert_eq!(package_tree_snapshot(&source), before);
4284        assert_eq!(
4285            std::fs::read_dir(&destination_parent)
4286                .expect("destination parent remains readable")
4287                .map(|entry| entry.expect("destination parent entry").file_name())
4288                .collect::<Vec<_>>(),
4289            vec![std::ffi::OsString::from("package")]
4290        );
4291    }
4292
4293    #[test]
4294    fn destination_parent_beneath_source_is_rejected_before_the_package_changes() {
4295        let temporary = tempfile::tempdir().expect("temporary root");
4296        let source = temporary.path().join("package");
4297        std::fs::create_dir(&source).expect("package root");
4298        let fixture = complete_fixture();
4299        write_package(&source, &fixture);
4300        let package = RetainedReconstructionPackage::open(&source).expect("retained package");
4301        let plan = plan_retained_package(&package).expect("retained package plan");
4302        let destination =
4303            RetainedReconstructionDestination::open(source.join("chunks"), "restored")
4304                .expect("retained destination beneath source");
4305        let before = package_tree_snapshot(&source);
4306
4307        let result = execute_root_reconstruction(
4308            RootReconstructionOperation::new(
4309                &plan,
4310                "reconstruction_01900000-0000-7000-8000-000000000203",
4311                plan.package_index_sha256(),
4312            )
4313            .expect("valid operation"),
4314            &package,
4315            &destination,
4316        );
4317
4318        assert!(matches!(
4319            result,
4320            Err(RootReconstructionError::InvalidDestination)
4321        ));
4322        assert_eq!(package_tree_snapshot(&source), before);
4323    }
4324
4325    #[cfg(unix)]
4326    #[test]
4327    fn aliased_source_ancestor_cannot_hide_containment_from_destination_parent() {
4328        let temporary = tempfile::tempdir().expect("temporary root");
4329        let destination_parent = temporary.path().join("physical-parent");
4330        let source = destination_parent.join("package");
4331        let aliased_parent = temporary.path().join("aliased-parent");
4332        std::fs::create_dir(&destination_parent).expect("physical destination parent");
4333        std::fs::create_dir(&source).expect("package root");
4334        std::os::unix::fs::symlink(&destination_parent, &aliased_parent)
4335            .expect("destination-parent alias");
4336        let fixture = complete_fixture();
4337        write_package(&source, &fixture);
4338        let package = RetainedReconstructionPackage::open(aliased_parent.join("package"))
4339            .expect("retained package through aliased ancestor");
4340        let plan = plan_retained_package(&package).expect("retained package plan");
4341        let destination = RetainedReconstructionDestination::open(&destination_parent, "restored")
4342            .expect("retained physical destination parent");
4343        let before = package_tree_snapshot(&source);
4344
4345        let result = execute_root_reconstruction(
4346            RootReconstructionOperation::new(
4347                &plan,
4348                "reconstruction_01900000-0000-7000-8000-000000000204",
4349                plan.package_index_sha256(),
4350            )
4351            .expect("valid operation"),
4352            &package,
4353            &destination,
4354        );
4355
4356        assert!(matches!(
4357            result,
4358            Err(RootReconstructionError::InvalidDestination)
4359        ));
4360        assert_eq!(package_tree_snapshot(&source), before);
4361        assert_eq!(
4362            std::fs::read_dir(&destination_parent)
4363                .expect("destination parent remains readable")
4364                .map(|entry| entry.expect("destination parent entry").file_name())
4365                .collect::<Vec<_>>(),
4366            vec![std::ffi::OsString::from("package")]
4367        );
4368    }
4369
4370    #[cfg(unix)]
4371    #[test]
4372    fn aliased_destination_ancestor_cannot_hide_containment_inside_source() {
4373        let temporary = tempfile::tempdir().expect("temporary root");
4374        let source = temporary.path().join("package");
4375        let aliased_source = temporary.path().join("aliased-package");
4376        std::fs::create_dir(&source).expect("package root");
4377        let fixture = complete_fixture();
4378        write_package(&source, &fixture);
4379        std::os::unix::fs::symlink(&source, &aliased_source).expect("package alias");
4380        let package = RetainedReconstructionPackage::open(&source).expect("retained package");
4381        let plan = plan_retained_package(&package).expect("retained package plan");
4382        let destination =
4383            RetainedReconstructionDestination::open(aliased_source.join("chunks"), "restored")
4384                .expect("retained destination through aliased ancestor");
4385        let before = package_tree_snapshot(&source);
4386
4387        let result = execute_root_reconstruction(
4388            RootReconstructionOperation::new(
4389                &plan,
4390                "reconstruction_01900000-0000-7000-8000-000000000205",
4391                plan.package_index_sha256(),
4392            )
4393            .expect("valid operation"),
4394            &package,
4395            &destination,
4396        );
4397
4398        assert!(matches!(
4399            result,
4400            Err(RootReconstructionError::InvalidDestination)
4401        ));
4402        assert_eq!(package_tree_snapshot(&source), before);
4403    }
4404
4405    #[test]
4406    fn execution_publishes_one_complete_verified_root() {
4407        let temporary = tempfile::tempdir().expect("temporary root");
4408        let source = temporary.path().join("package");
4409        let destination_parent = temporary.path().join("destinations");
4410        std::fs::create_dir(&source).expect("package root");
4411        std::fs::create_dir(&destination_parent).expect("destination parent");
4412        let fixture = complete_fixture();
4413        write_package(&source, &fixture);
4414        let plan = plan_from_fixture(&fixture);
4415        let package = RetainedReconstructionPackage::open(&source).expect("retained package");
4416        let destination = RetainedReconstructionDestination::open(&destination_parent, "restored")
4417            .expect("retained absent destination");
4418        let operation = RootReconstructionOperation::new(
4419            &plan,
4420            "reconstruction_01900000-0000-7000-8000-000000000100",
4421            plan.package_index_sha256(),
4422        )
4423        .expect("valid operation");
4424
4425        let result = execute_root_reconstruction(operation, &package, &destination)
4426            .expect("root reconstruction");
4427
4428        let restored = destination_parent.join("restored");
4429        assert!(!result.replayed());
4430        assert_eq!(result.attestation().root, restored);
4431        assert_eq!(
4432            std::fs::read(restored.join("current.txt")).unwrap(),
4433            b"payload"
4434        );
4435        assert_eq!(
4436            std::fs::read_link(restored.join("shortcut")).unwrap(),
4437            std::path::Path::new("current.txt")
4438        );
4439        assert_eq!(
4440            crate::attest_folderbase_root(&restored)
4441                .expect("published root attests")
4442                .folderbase_id,
4443            FOLDERBASE_ID
4444        );
4445        let store =
4446            crate::FolderbaseVersionStore::open(&restored).expect("open reconstructed root");
4447        assert_eq!(
4448            store
4449                .read_version(FOLDERBASE_VERSION_ID)
4450                .expect("installed Version")
4451                .canonical_digest()
4452                .expect("Version digest"),
4453            plan.canonical_version_sha256()
4454        );
4455        let capture = store.plan_capture().expect("follow-up capture plan");
4456        store
4457            .seal_capture(capture)
4458            .expect("follow-up capture remains operational");
4459
4460        let owner = stage_owner_name("reconstruction_01900000-0000-7000-8000-000000000100");
4461        let proof = stage_proof_name("reconstruction_01900000-0000-7000-8000-000000000100");
4462        assert!(!destination_parent.join(owner).exists());
4463        assert!(!destination_parent.join(proof).exists());
4464        std::fs::remove_dir_all(&source).expect("transport may disappear after completion");
4465        let replay = execute_root_reconstruction(
4466            RootReconstructionOperation::new(
4467                &plan,
4468                "reconstruction_01900000-0000-7000-8000-000000000100",
4469                plan.package_index_sha256(),
4470            )
4471            .unwrap(),
4472            &package,
4473            &destination,
4474        )
4475        .expect("exact replay does not require transport");
4476        assert!(replay.replayed());
4477        assert_eq!(replay.attestation().root, restored);
4478
4479        let occupied = execute_root_reconstruction(
4480            RootReconstructionOperation::new(
4481                &plan,
4482                "reconstruction_01900000-0000-7000-8000-000000000101",
4483                plan.package_index_sha256(),
4484            )
4485            .unwrap(),
4486            &package,
4487            &destination,
4488        );
4489        assert!(matches!(
4490            occupied,
4491            Err(RootReconstructionError::DestinationOccupied(path)) if path == restored
4492        ));
4493        assert_eq!(
4494            std::fs::read(restored.join("current.txt")).unwrap(),
4495            b"payload"
4496        );
4497    }
4498
4499    #[test]
4500    fn reconstructed_tombstone_only_history_restores_exact_fidelity() {
4501        let temporary = tempfile::tempdir().expect("temporary root");
4502        let source = temporary.path().join("package");
4503        let destination_parent = temporary.path().join("destinations");
4504        std::fs::create_dir(&source).expect("package root");
4505        std::fs::create_dir(&destination_parent).expect("destination parent");
4506        let fixture = tombstone_only_fixture();
4507        write_package(&source, &fixture);
4508        let plan = plan_from_fixture(&fixture);
4509        let package = RetainedReconstructionPackage::open(&source).expect("retained package");
4510        let destination = RetainedReconstructionDestination::open(&destination_parent, "restored")
4511            .expect("retained absent destination");
4512
4513        execute_root_reconstruction(
4514            RootReconstructionOperation::new(
4515                &plan,
4516                "reconstruction_01900000-0000-7000-8000-000000000102",
4517                plan.package_index_sha256(),
4518            )
4519            .expect("valid operation"),
4520            &package,
4521            &destination,
4522        )
4523        .expect("root reconstruction");
4524
4525        let restored = destination_parent.join("restored");
4526        let local = crate::LocalVersionStore::open(&restored).expect("reopen local versions");
4527        local
4528            .restore_version(
4529                &crate::VersionId::parse(LIVE_VERSION_ID.to_owned())
4530                    .expect("valid Object Version ID"),
4531                "Restored/previous.txt",
4532            )
4533            .expect("ordinary Object Version restore preserves retained fidelity");
4534        assert_eq!(
4535            std::fs::read(restored.join("Restored/previous.txt")).unwrap(),
4536            b"payload"
4537        );
4538        #[cfg(unix)]
4539        {
4540            use std::os::unix::fs::PermissionsExt;
4541            assert_ne!(
4542                std::fs::metadata(restored.join("Restored/previous.txt"))
4543                    .unwrap()
4544                    .permissions()
4545                    .mode()
4546                    & 0o111,
4547                0
4548            );
4549        }
4550
4551        let store = crate::FolderbaseVersionStore::open(&restored).expect("reopen root");
4552        store
4553            .restore_tombstone("previous.txt")
4554            .expect("retained Tombstone remains restorable without ancestor Versions");
4555        assert_eq!(
4556            std::fs::read(restored.join("previous.txt")).unwrap(),
4557            b"payload"
4558        );
4559        #[cfg(unix)]
4560        {
4561            use std::os::unix::fs::PermissionsExt;
4562            assert_ne!(
4563                std::fs::metadata(restored.join("previous.txt"))
4564                    .unwrap()
4565                    .permissions()
4566                    .mode()
4567                    & 0o111,
4568                0,
4569                "Tombstone restore must retain executable fidelity"
4570            );
4571        }
4572    }
4573
4574    #[test]
4575    fn operation_derives_the_normative_request_digest_and_rejects_invalid_identity_or_pin() {
4576        assert_eq!(
4577            root_reconstruction_request_sha256(
4578                "reconstruction_019f0000-0000-7000-8000-000000000001",
4579                "c646776fc7a7c2f8b3d6320fcb647f19fa2df32f7061ed70944efc5bf13aac28",
4580            )
4581            .unwrap(),
4582            "3c306292ba513818e68b83a09f65a127dca5ae44a892ce7db4485e4f29b45115"
4583        );
4584        let fixture = complete_fixture();
4585        let plan = plan_from_fixture(&fixture);
4586        let operation = RootReconstructionOperation::new(
4587            &plan,
4588            "reconstruction_01900000-0000-7000-8000-000000000100",
4589            plan.package_index_sha256(),
4590        )
4591        .expect("canonical UUID and exact pin");
4592        assert!(super::is_sha256(operation.request_sha256()));
4593        assert!(matches!(
4594            RootReconstructionOperation::new(
4595                &plan,
4596                "reconstruction_01900000-0000-7000-8000-000000000100",
4597                "ab".repeat(32),
4598            ),
4599            Err(RootReconstructionError::PackageIndexPinMismatch)
4600        ));
4601        assert!(matches!(
4602            RootReconstructionOperation::new(
4603                &plan,
4604                "reconstruction_01900000-0000-9000-8000-000000000100",
4605                plan.package_index_sha256(),
4606            ),
4607            Err(RootReconstructionError::InvalidOperation)
4608        ));
4609    }
4610
4611    #[test]
4612    fn occupied_destination_and_foreign_private_state_are_preserved() {
4613        let temporary = tempfile::tempdir().unwrap();
4614        let source = temporary.path().join("package");
4615        let parent = temporary.path().join("destinations");
4616        std::fs::create_dir(&source).unwrap();
4617        std::fs::create_dir(&parent).unwrap();
4618        let fixture = complete_fixture();
4619        write_package(&source, &fixture);
4620        let plan = plan_from_fixture(&fixture);
4621        let package = RetainedReconstructionPackage::open(&source).unwrap();
4622
4623        std::fs::create_dir(parent.join("occupied")).unwrap();
4624        std::fs::write(parent.join("occupied/keep.txt"), b"keep").unwrap();
4625        let occupied_destination =
4626            RetainedReconstructionDestination::open(&parent, "occupied").unwrap();
4627        let result = execute_root_reconstruction(
4628            RootReconstructionOperation::new(
4629                &plan,
4630                "reconstruction_01900000-0000-7000-8000-000000000110",
4631                plan.package_index_sha256(),
4632            )
4633            .unwrap(),
4634            &package,
4635            &occupied_destination,
4636        );
4637        assert!(matches!(
4638            result,
4639            Err(RootReconstructionError::DestinationOccupied(_))
4640        ));
4641        assert_eq!(
4642            std::fs::read(parent.join("occupied/keep.txt")).unwrap(),
4643            b"keep"
4644        );
4645
4646        let operation_id = "reconstruction_01900000-0000-7000-8000-000000000111";
4647        let foreign_stage = parent.join(staged_root_name(operation_id));
4648        std::fs::create_dir(&foreign_stage).unwrap();
4649        std::fs::write(foreign_stage.join("keep.txt"), b"foreign").unwrap();
4650        let destination =
4651            RetainedReconstructionDestination::open(&parent, "foreign-target").unwrap();
4652        let result = execute_root_reconstruction(
4653            RootReconstructionOperation::new(&plan, operation_id, plan.package_index_sha256())
4654                .unwrap(),
4655            &package,
4656            &destination,
4657        );
4658        assert!(matches!(
4659            result,
4660            Err(RootReconstructionError::OperationConflict)
4661        ));
4662        assert_eq!(
4663            std::fs::read(foreign_stage.join("keep.txt")).unwrap(),
4664            b"foreign"
4665        );
4666
4667        let operation_id = "reconstruction_01900000-0000-7000-8000-000000000112";
4668        let foreign_owner = parent.join(stage_owner_name(operation_id));
4669        std::fs::write(&foreign_owner, b"foreign-owner").unwrap();
4670        let destination =
4671            RetainedReconstructionDestination::open(&parent, "foreign-owner-target").unwrap();
4672        let result = execute_root_reconstruction(
4673            RootReconstructionOperation::new(&plan, operation_id, plan.package_index_sha256())
4674                .unwrap(),
4675            &package,
4676            &destination,
4677        );
4678        assert!(matches!(
4679            result,
4680            Err(RootReconstructionError::OperationConflict)
4681        ));
4682        assert_eq!(std::fs::read(foreign_owner).unwrap(), b"foreign-owner");
4683    }
4684
4685    #[test]
4686    fn unsupported_preflight_creates_no_private_stage() {
4687        let temporary = tempfile::tempdir().unwrap();
4688        let parent = temporary.path().join("destinations");
4689        std::fs::create_dir(&parent).unwrap();
4690        let result = RetainedReconstructionDestination::open_with_preflight(
4691            &parent,
4692            std::ffi::OsStr::new("restored"),
4693            true,
4694        );
4695        assert!(matches!(
4696            result,
4697            Err(RootReconstructionError::UnsupportedReconstructionFilesystem { .. })
4698        ));
4699        assert_eq!(std::fs::read_dir(&parent).unwrap().count(), 0);
4700    }
4701
4702    #[test]
4703    fn exact_owned_stage_rejects_extra_entries_and_repairs_executable_fidelity() {
4704        let temporary = tempfile::tempdir().unwrap();
4705        let source = temporary.path().join("package");
4706        let parent = temporary.path().join("destinations");
4707        std::fs::create_dir(&source).unwrap();
4708        std::fs::create_dir(&parent).unwrap();
4709        let fixture = complete_fixture();
4710        write_package(&source, &fixture);
4711        let plan = plan_from_fixture(&fixture);
4712        let package = RetainedReconstructionPackage::open(&source).unwrap();
4713        let operation_id = "reconstruction_01900000-0000-7000-8000-000000000120";
4714        let destination = RetainedReconstructionDestination::open(&parent, "extra-target").unwrap();
4715        let crash = catch_unwind(AssertUnwindSafe(|| {
4716            let _ = execute_root_reconstruction_with_phase_callback(
4717                RootReconstructionOperation::new(&plan, operation_id, plan.package_index_sha256())
4718                    .unwrap(),
4719                &package,
4720                &destination,
4721                |phase| {
4722                    if phase == RootReconstructionPhase::PreparedJournal {
4723                        let stage = parent.join(staged_root_name(operation_id));
4724                        std::fs::write(stage.join("extra.txt"), b"extra").unwrap();
4725                        panic!("simulated loss");
4726                    }
4727                },
4728            );
4729        }));
4730        assert!(crash.is_err());
4731        let result = execute_root_reconstruction(
4732            RootReconstructionOperation::new(&plan, operation_id, plan.package_index_sha256())
4733                .unwrap(),
4734            &package,
4735            &destination,
4736        );
4737        assert!(matches!(
4738            result,
4739            Err(RootReconstructionError::OperationConflict)
4740        ));
4741        assert_eq!(
4742            std::fs::read(
4743                parent
4744                    .join(staged_root_name(operation_id))
4745                    .join("extra.txt")
4746            )
4747            .unwrap(),
4748            b"extra"
4749        );
4750
4751        #[cfg(unix)]
4752        {
4753            use std::os::unix::fs::PermissionsExt;
4754            let operation_id = "reconstruction_01900000-0000-7000-8000-000000000121";
4755            let destination =
4756                RetainedReconstructionDestination::open(&parent, "mode-target").unwrap();
4757            let crash = catch_unwind(AssertUnwindSafe(|| {
4758                let _ = execute_root_reconstruction_with_phase_callback(
4759                    RootReconstructionOperation::new(
4760                        &plan,
4761                        operation_id,
4762                        plan.package_index_sha256(),
4763                    )
4764                    .unwrap(),
4765                    &package,
4766                    &destination,
4767                    |phase| {
4768                        if phase == RootReconstructionPhase::VerifiedStaging {
4769                            let file = parent
4770                                .join(staged_root_name(operation_id))
4771                                .join("current.txt");
4772                            std::fs::set_permissions(&file, std::fs::Permissions::from_mode(0o755))
4773                                .unwrap();
4774                            panic!("simulated loss");
4775                        }
4776                    },
4777                );
4778            }));
4779            assert!(crash.is_err());
4780            let result = execute_root_reconstruction(
4781                RootReconstructionOperation::new(&plan, operation_id, plan.package_index_sha256())
4782                    .unwrap(),
4783                &package,
4784                &destination,
4785            )
4786            .expect("retry repairs exact executable fidelity");
4787            assert!(!result.replayed());
4788            assert_eq!(
4789                std::fs::metadata(parent.join("mode-target/current.txt"))
4790                    .unwrap()
4791                    .permissions()
4792                    .mode()
4793                    & 0o111,
4794                0
4795            );
4796        }
4797    }
4798
4799    #[test]
4800    fn post_publication_phase_losses_replay_and_retire_only_owned_records() {
4801        for (suffix, crash_phase) in [
4802            ("130", RootReconstructionPhase::Publication),
4803            ("131", RootReconstructionPhase::CompletionDurable),
4804        ] {
4805            let temporary = tempfile::tempdir().unwrap();
4806            let source = temporary.path().join("package");
4807            let parent = temporary.path().join("destinations");
4808            std::fs::create_dir(&source).unwrap();
4809            std::fs::create_dir(&parent).unwrap();
4810            let fixture = complete_fixture();
4811            write_package(&source, &fixture);
4812            let plan = plan_from_fixture(&fixture);
4813            let package = RetainedReconstructionPackage::open(&source).unwrap();
4814            let destination = RetainedReconstructionDestination::open(&parent, "restored").unwrap();
4815            let operation_id = format!("reconstruction_01900000-0000-7000-8000-000000000{suffix}");
4816
4817            let crashed = catch_unwind(AssertUnwindSafe(|| {
4818                let _ = execute_root_reconstruction_with_phase_callback(
4819                    RootReconstructionOperation::new(
4820                        &plan,
4821                        &operation_id,
4822                        plan.package_index_sha256(),
4823                    )
4824                    .unwrap(),
4825                    &package,
4826                    &destination,
4827                    |phase| {
4828                        if phase == crash_phase {
4829                            panic!("simulated post-publication loss");
4830                        }
4831                    },
4832                );
4833            }));
4834            assert!(crashed.is_err());
4835            assert!(parent.join("restored").is_dir());
4836
4837            let replay = execute_root_reconstruction(
4838                RootReconstructionOperation::new(&plan, &operation_id, plan.package_index_sha256())
4839                    .unwrap(),
4840                &package,
4841                &destination,
4842            )
4843            .expect("published completion replays");
4844            assert!(replay.replayed());
4845            assert!(!parent.join(stage_owner_name(&operation_id)).exists());
4846            assert!(!parent.join(stage_proof_name(&operation_id)).exists());
4847        }
4848    }
4849
4850    #[test]
4851    fn durable_owned_stage_entry_without_proof_converges_on_retry() {
4852        let temporary = tempfile::tempdir().unwrap();
4853        let source = temporary.path().join("package");
4854        let parent = temporary.path().join("destinations");
4855        std::fs::create_dir(&source).unwrap();
4856        std::fs::create_dir(&parent).unwrap();
4857        let fixture = complete_fixture();
4858        write_package(&source, &fixture);
4859        let plan = plan_from_fixture(&fixture);
4860        let package = RetainedReconstructionPackage::open(&source).unwrap();
4861        let destination = RetainedReconstructionDestination::open(&parent, "restored").unwrap();
4862        let operation_id = "reconstruction_01900000-0000-7000-8000-000000000132";
4863
4864        let crashed = catch_unwind(AssertUnwindSafe(|| {
4865            let _ = execute_root_reconstruction_with_phase_callback(
4866                RootReconstructionOperation::new(&plan, operation_id, plan.package_index_sha256())
4867                    .unwrap(),
4868                &package,
4869                &destination,
4870                |phase| {
4871                    if phase == RootReconstructionPhase::StageEntryDurable {
4872                        panic!("simulated loss after durable stage entry");
4873                    }
4874                },
4875            );
4876        }));
4877        assert!(crashed.is_err());
4878        assert!(!parent.join("restored").exists());
4879
4880        let recovered = execute_root_reconstruction(
4881            RootReconstructionOperation::new(&plan, operation_id, plan.package_index_sha256())
4882                .unwrap(),
4883            &package,
4884            &destination,
4885        )
4886        .expect("exact owned stage resumes after loss before proof");
4887        assert!(!recovered.replayed());
4888        assert!(parent.join("restored").is_dir());
4889    }
4890
4891    #[test]
4892    fn same_byte_package_child_substitution_fails_closed() {
4893        let temporary = tempfile::tempdir().unwrap();
4894        let source = temporary.path().join("package");
4895        let parent = temporary.path().join("destinations");
4896        std::fs::create_dir(&source).unwrap();
4897        std::fs::create_dir(&parent).unwrap();
4898        let fixture = complete_fixture();
4899        write_package(&source, &fixture);
4900        let plan = plan_from_fixture(&fixture);
4901        let package = RetainedReconstructionPackage::open(&source).unwrap();
4902        let destination = RetainedReconstructionDestination::open(&parent, "restored").unwrap();
4903        let operation_id = "reconstruction_01900000-0000-7000-8000-000000000133";
4904        let chunk_name = std::fs::read_dir(source.join("chunks"))
4905            .unwrap()
4906            .next()
4907            .unwrap()
4908            .unwrap()
4909            .file_name();
4910        let chunk_path = source.join("chunks").join(chunk_name);
4911        let original = std::fs::read(&chunk_path).unwrap();
4912        let retained_chunk = temporary.path().join("retained-original-chunk");
4913        let mut substituted = false;
4914        let mut substitution_identities = None;
4915
4916        let result = execute_root_reconstruction_with_phase_callback(
4917            RootReconstructionOperation::new(&plan, operation_id, plan.package_index_sha256())
4918                .unwrap(),
4919            &package,
4920            &destination,
4921            |phase| {
4922                if phase == RootReconstructionPhase::PreparedJournal && !substituted {
4923                    let original_identity = PhysicalIdentity::from_path(&chunk_path).unwrap();
4924                    std::fs::rename(&chunk_path, &retained_chunk).unwrap();
4925                    std::fs::write(&chunk_path, &original).unwrap();
4926                    let replacement_identity = PhysicalIdentity::from_path(&chunk_path).unwrap();
4927                    substitution_identities = Some((original_identity, replacement_identity));
4928                    substituted = true;
4929                }
4930            },
4931        );
4932        let (original_identity, replacement_identity) =
4933            substitution_identities.expect("substitution identities");
4934        assert_ne!(
4935            replacement_identity, original_identity,
4936            "the adversarial replacement must be a distinct physical object"
4937        );
4938        assert!(matches!(
4939            result,
4940            Err(RootReconstructionError::PackageChanged(_))
4941        ));
4942        assert!(!parent.join("restored").exists());
4943    }
4944
4945    #[cfg(unix)]
4946    #[test]
4947    fn replay_operational_read_failure_is_not_destination_attention() {
4948        use std::os::unix::fs::PermissionsExt;
4949
4950        let temporary = tempfile::tempdir().unwrap();
4951        let source = temporary.path().join("package");
4952        let parent = temporary.path().join("destinations");
4953        std::fs::create_dir(&source).unwrap();
4954        std::fs::create_dir(&parent).unwrap();
4955        let fixture = complete_fixture();
4956        write_package(&source, &fixture);
4957        let plan = plan_from_fixture(&fixture);
4958        let package = RetainedReconstructionPackage::open(&source).unwrap();
4959        let destination = RetainedReconstructionDestination::open(&parent, "restored").unwrap();
4960        let operation_id = "reconstruction_01900000-0000-7000-8000-000000000134";
4961        execute_root_reconstruction(
4962            RootReconstructionOperation::new(&plan, operation_id, plan.package_index_sha256())
4963                .unwrap(),
4964            &package,
4965            &destination,
4966        )
4967        .unwrap();
4968
4969        let completion = parent.join("restored").join(COMPLETED_RECONSTRUCTION_PATH);
4970        std::fs::set_permissions(&completion, std::fs::Permissions::from_mode(0o000)).unwrap();
4971        let replay = execute_root_reconstruction(
4972            RootReconstructionOperation::new(&plan, operation_id, plan.package_index_sha256())
4973                .unwrap(),
4974            &package,
4975            &destination,
4976        );
4977        std::fs::set_permissions(&completion, std::fs::Permissions::from_mode(0o600)).unwrap();
4978
4979        assert!(replay.is_err());
4980        assert!(!matches!(
4981            replay,
4982            Err(RootReconstructionError::DestinationOccupied(_))
4983        ));
4984    }
4985
4986    #[cfg(unix)]
4987    #[test]
4988    fn unsafe_package_permissions_and_hardlink_aliases_fail_before_staging() {
4989        use std::os::unix::fs::PermissionsExt;
4990
4991        for (suffix, make_unsafe) in [("140", 0_u8), ("141", 1_u8)] {
4992            let temporary = tempfile::tempdir().unwrap();
4993            let source = temporary.path().join("package");
4994            let parent = temporary.path().join("destinations");
4995            std::fs::create_dir(&source).unwrap();
4996            std::fs::create_dir(&parent).unwrap();
4997            let fixture = complete_fixture();
4998            write_package(&source, &fixture);
4999            let plan = plan_from_fixture(&fixture);
5000            if make_unsafe == 0 {
5001                std::fs::set_permissions(
5002                    source.join("index.json"),
5003                    std::fs::Permissions::from_mode(0o666),
5004                )
5005                .unwrap();
5006            } else {
5007                let chunk = source.join("chunks").join(sha256(b"payload"));
5008                std::fs::hard_link(&chunk, temporary.path().join("chunk-alias")).unwrap();
5009            }
5010            let package = RetainedReconstructionPackage::open(&source).unwrap();
5011            let destination = RetainedReconstructionDestination::open(&parent, "restored").unwrap();
5012            let operation_id = format!("reconstruction_01900000-0000-7000-8000-000000000{suffix}");
5013            let result = execute_root_reconstruction(
5014                RootReconstructionOperation::new(&plan, &operation_id, plan.package_index_sha256())
5015                    .unwrap(),
5016                &package,
5017                &destination,
5018            );
5019            assert!(matches!(
5020                result,
5021                Err(RootReconstructionError::UnsafePackage(_))
5022            ));
5023            assert!(!parent.join("restored").exists());
5024            assert!(!parent.join(staged_root_name(&operation_id)).exists());
5025        }
5026    }
5027
5028    #[test]
5029    fn closure_rejects_missing_root_live_and_retained_tombstone_roles() {
5030        let mut missing_fidelity = complete_fixture();
5031        mutate_index(&mut missing_fidelity, |index| {
5032            index["tombstone_fidelity"] = json!([]);
5033        });
5034        assert!(matches!(
5035            plan(missing_fidelity),
5036            Err(RootReconstructionError::TombstoneFidelityMismatch)
5037        ));
5038
5039        let mut missing_root = complete_fixture();
5040        mutate_index(&mut missing_root, |index| {
5041            index["references"]
5042                .as_array_mut()
5043                .expect("references")
5044                .remove(0);
5045        });
5046        assert!(matches!(
5047            plan(missing_root),
5048            Err(RootReconstructionError::MissingReference { object_version_id })
5049                if object_version_id == ROOT_VERSION_ID
5050        ));
5051
5052        let mut missing_live = complete_fixture();
5053        mutate_index(&mut missing_live, |index| {
5054            index["references"]
5055                .as_array_mut()
5056                .expect("references")
5057                .remove(1);
5058        });
5059        assert!(matches!(
5060            plan(missing_live),
5061            Err(RootReconstructionError::MissingReference { object_version_id })
5062                if object_version_id == LIVE_VERSION_ID
5063        ));
5064
5065        let mut missing_tombstone_role = complete_fixture();
5066        mutate_index(&mut missing_tombstone_role, |index| {
5067            index["references"][1]["roles"] = json!(["live_regular_file"]);
5068        });
5069        assert!(matches!(
5070            plan(missing_tombstone_role),
5071            Err(RootReconstructionError::ReferenceMismatch { object_version_id })
5072                if object_version_id == LIVE_VERSION_ID
5073        ));
5074    }
5075
5076    #[test]
5077    fn closure_rejects_duplicate_extra_and_out_of_order_references() {
5078        let mut duplicate = complete_fixture();
5079        mutate_index(&mut duplicate, |index| {
5080            let repeated = index["references"][1].clone();
5081            index["references"]
5082                .as_array_mut()
5083                .expect("references")
5084                .push(repeated);
5085        });
5086        assert!(matches!(
5087            plan(duplicate),
5088            Err(RootReconstructionError::DuplicateReference { .. })
5089        ));
5090
5091        let mut extra = complete_fixture();
5092        mutate_index(&mut extra, |index| {
5093            index["references"]
5094                .as_array_mut()
5095                .expect("references")
5096                .push(json!({
5097                    "object_version_id": "version_01900000-0000-7000-8000-000000000099",
5098                    "object_id": "obj_01900000-0000-7000-8000-000000000099",
5099                    "roles": ["retained_tombstone"],
5100                    "chunk_manifest_sha256": "99".repeat(32)
5101                }));
5102        });
5103        assert!(matches!(
5104            plan(extra),
5105            Err(RootReconstructionError::UnexpectedReference { .. })
5106        ));
5107
5108        let mut reordered = complete_fixture();
5109        mutate_index(&mut reordered, |index| {
5110            index["references"]
5111                .as_array_mut()
5112                .expect("references")
5113                .swap(0, 1);
5114        });
5115        assert!(matches!(
5116            plan(reordered),
5117            Err(RootReconstructionError::ReferencesOutOfOrder)
5118        ));
5119    }
5120
5121    #[test]
5122    fn manifests_must_match_canonical_digest_and_version_digest_and_length() {
5123        let mut changed_plan = complete_fixture();
5124        let changed_manifest = manifest(b"changed", 0x33);
5125        changed_plan.manifests[0].encoded =
5126            Cursor::new(serde_json::to_vec(&changed_manifest).expect("encode changed manifest"));
5127        assert!(matches!(
5128            plan(changed_plan),
5129            Err(RootReconstructionError::ManifestDigestMismatch { .. })
5130        ));
5131
5132        let mut digest_mismatch = complete_fixture();
5133        let mut changed_digest = manifest(b"payload", 0x22);
5134        changed_digest.object_sha256 = "aa".repeat(32);
5135        replace_live_manifest(&mut digest_mismatch, changed_digest);
5136        assert!(matches!(
5137            plan(digest_mismatch),
5138            Err(RootReconstructionError::ManifestObjectMismatch { object_version_id })
5139                if object_version_id == LIVE_VERSION_ID
5140        ));
5141
5142        let mut length_mismatch = complete_fixture();
5143        let mut changed_length = manifest(b"payload", 0x22);
5144        changed_length.object_bytes += 1;
5145        changed_length.chunks[0].bytes += 1;
5146        replace_live_manifest(&mut length_mismatch, changed_length);
5147        assert!(matches!(
5148            plan(length_mismatch),
5149            Err(RootReconstructionError::ManifestObjectMismatch { object_version_id })
5150                if object_version_id == LIVE_VERSION_ID
5151        ));
5152    }
5153
5154    #[test]
5155    fn manifest_set_is_exact_without_missing_duplicate_or_unreferenced_documents() {
5156        let mut missing = complete_fixture();
5157        missing.manifests.pop();
5158        assert!(matches!(
5159            plan(missing),
5160            Err(RootReconstructionError::MissingManifest { .. })
5161        ));
5162
5163        let mut duplicate = complete_fixture();
5164        let digest = duplicate.manifests[0].digest().to_owned();
5165        let encoded = duplicate.manifests[0].encoded.get_ref().clone();
5166        duplicate
5167            .manifests
5168            .push(ManifestInput::new(digest, Cursor::new(encoded)));
5169        assert!(matches!(
5170            plan(duplicate),
5171            Err(RootReconstructionError::DuplicateManifest { .. })
5172        ));
5173
5174        let mut extra = complete_fixture();
5175        let extra_manifest = manifest(b"extra", 0x44);
5176        let extra_digest = extra_manifest.canonical_digest().expect("valid manifest");
5177        extra
5178            .manifests
5179            .push(manifest_input(extra_digest, extra_manifest));
5180        assert!(matches!(
5181            plan(extra),
5182            Err(RootReconstructionError::UnreferencedManifest { .. })
5183        ));
5184    }
5185
5186    #[test]
5187    fn fixed_limits_and_encoded_input_bounds_fail_closed() {
5188        let mut changed_limits = complete_fixture();
5189        mutate_index(&mut changed_limits, |index| {
5190            index["limits"]["max_visible_entries"] = json!(16_383);
5191        });
5192        assert!(matches!(
5193            plan(changed_limits),
5194            Err(RootReconstructionError::LimitsMismatch)
5195        ));
5196
5197        let too_many_references = serde_json::to_vec(&json!({
5198            "references": vec![Value::Null; MAX_PACKAGE_REFERENCES + 1]
5199        }))
5200        .expect("encode count probe");
5201        let empty_manifests: Vec<ManifestInput<Cursor<Vec<u8>>>> = Vec::new();
5202        assert!(matches!(
5203            decode_and_plan(
5204                too_many_references.as_slice(),
5205                std::io::empty(),
5206                empty_manifests
5207            ),
5208            Err(RootReconstructionError::TooManyReferences { .. })
5209        ));
5210
5211        let empty_manifests: Vec<ManifestInput<Cursor<Vec<u8>>>> = Vec::new();
5212        assert!(matches!(
5213            decode_and_plan(
5214                std::io::repeat(b' ').take(MAX_PACKAGE_INDEX_BYTES + 1),
5215                std::io::empty(),
5216                empty_manifests
5217            ),
5218            Err(RootReconstructionError::IndexTooLarge { .. })
5219        ));
5220
5221        let fixture = complete_fixture();
5222        let oversized_digest = fixture.manifests[0].digest().to_owned();
5223        let mut boxed_inputs: Vec<ManifestInput<Box<dyn std::io::Read>>> = Vec::new();
5224        for input in fixture.manifests {
5225            let reader: Box<dyn std::io::Read> = if input.digest() == oversized_digest {
5226                Box::new(std::io::repeat(b' ').take(MAX_PACKAGE_MANIFEST_BYTES + 1))
5227            } else {
5228                Box::new(input.encoded)
5229            };
5230            boxed_inputs.push(ManifestInput::new(input.chunk_manifest_sha256, reader));
5231        }
5232        assert!(matches!(
5233            decode_and_plan(
5234                fixture.index.as_slice(),
5235                fixture.version.as_slice(),
5236                boxed_inputs
5237            ),
5238            Err(RootReconstructionError::InvalidManifest {
5239                source: ManifestError::EncodedManifestTooLarge { .. },
5240                ..
5241            })
5242        ));
5243    }
5244
5245    fn complete_fixture() -> Fixture {
5246        let root_manifest = manifest(&root_manifest_bytes(), 0x11);
5247        let live_manifest = manifest(b"payload", 0x22);
5248        let root_manifest_digest = root_manifest.canonical_digest().expect("valid manifest");
5249        let live_manifest_digest = live_manifest.canonical_digest().expect("valid manifest");
5250        let version_value = version_json(&root_manifest, &live_manifest);
5251        let version = serde_json::to_vec(&version_value).expect("encode version");
5252        let decoded = FolderbaseVersion::decode_bounded(version.as_slice()).expect("valid version");
5253        let mut references = vec![
5254            json!({
5255                "object_version_id": ROOT_VERSION_ID,
5256                "roles": ["root_manifest"],
5257                "chunk_manifest_sha256": root_manifest_digest,
5258            }),
5259            json!({
5260                "object_version_id": LIVE_VERSION_ID,
5261                "object_id": LIVE_OBJECT_ID,
5262                "roles": ["live_regular_file", "retained_tombstone"],
5263                "chunk_manifest_sha256": live_manifest_digest,
5264            }),
5265        ];
5266        references.sort_by(|left, right| {
5267            left["object_version_id"]
5268                .as_str()
5269                .expect("object version")
5270                .as_bytes()
5271                .cmp(
5272                    right["object_version_id"]
5273                        .as_str()
5274                        .expect("object version")
5275                        .as_bytes(),
5276                )
5277        });
5278        let index = serde_json::to_vec(&json!({
5279            "format": "folderbase-root-reconstruction-package-v1",
5280            "folderbase_id": FOLDERBASE_ID,
5281            "folderbase_version_id": FOLDERBASE_VERSION_ID,
5282            "canonical_version_sha256": decoded.canonical_digest().expect("version digest"),
5283            "encoded_version_sha256": sha256(&version),
5284            "limits": package_limits(),
5285            "references": references,
5286            "tombstone_fidelity": [{
5287                "path": "previous.txt",
5288                "object_id": LIVE_OBJECT_ID,
5289                "object_version_id": LIVE_VERSION_ID,
5290                "executable": false
5291            }],
5292        }))
5293        .expect("encode index");
5294        let mut manifests = vec![
5295            manifest_input(root_manifest_digest, root_manifest),
5296            manifest_input(live_manifest_digest, live_manifest),
5297        ];
5298        manifests.sort_by(|left, right| left.digest().as_bytes().cmp(right.digest().as_bytes()));
5299        Fixture {
5300            index,
5301            version,
5302            manifests,
5303        }
5304    }
5305
5306    fn tombstone_only_fixture() -> Fixture {
5307        let root_manifest = manifest(&root_manifest_bytes(), 0x11);
5308        let retained_manifest = manifest(b"payload", 0x22);
5309        let root_manifest_digest = root_manifest.canonical_digest().expect("valid manifest");
5310        let retained_manifest_digest = retained_manifest
5311            .canonical_digest()
5312            .expect("valid manifest");
5313        let mut version_value = version_json(&root_manifest, &retained_manifest);
5314        version_value["bindings"] = json!([]);
5315        let version = serde_json::to_vec(&version_value).expect("encode version");
5316        let decoded = FolderbaseVersion::decode_bounded(version.as_slice()).expect("valid version");
5317        let mut references = vec![
5318            json!({
5319                "object_version_id": ROOT_VERSION_ID,
5320                "roles": ["root_manifest"],
5321                "chunk_manifest_sha256": root_manifest_digest,
5322            }),
5323            json!({
5324                "object_version_id": LIVE_VERSION_ID,
5325                "object_id": LIVE_OBJECT_ID,
5326                "roles": ["retained_tombstone"],
5327                "chunk_manifest_sha256": retained_manifest_digest,
5328            }),
5329        ];
5330        references.sort_by(|left, right| {
5331            left["object_version_id"]
5332                .as_str()
5333                .expect("object version")
5334                .as_bytes()
5335                .cmp(
5336                    right["object_version_id"]
5337                        .as_str()
5338                        .expect("object version")
5339                        .as_bytes(),
5340                )
5341        });
5342        let index = serde_json::to_vec(&json!({
5343            "format": "folderbase-root-reconstruction-package-v1",
5344            "folderbase_id": FOLDERBASE_ID,
5345            "folderbase_version_id": FOLDERBASE_VERSION_ID,
5346            "canonical_version_sha256": decoded.canonical_digest().expect("version digest"),
5347            "encoded_version_sha256": sha256(&version),
5348            "limits": package_limits(),
5349            "references": references,
5350            "tombstone_fidelity": [{
5351                "path": "previous.txt",
5352                "object_id": LIVE_OBJECT_ID,
5353                "object_version_id": LIVE_VERSION_ID,
5354                "executable": true
5355            }],
5356        }))
5357        .expect("encode index");
5358        let mut manifests = vec![
5359            manifest_input(root_manifest_digest, root_manifest),
5360            manifest_input(retained_manifest_digest, retained_manifest),
5361        ];
5362        manifests.sort_by(|left, right| left.digest().as_bytes().cmp(right.digest().as_bytes()));
5363        Fixture {
5364            index,
5365            version,
5366            manifests,
5367        }
5368    }
5369
5370    fn plan(fixture: Fixture) -> Result<super::RootReconstructionPlan, RootReconstructionError> {
5371        decode_and_plan(
5372            fixture.index.as_slice(),
5373            fixture.version.as_slice(),
5374            fixture.manifests,
5375        )
5376    }
5377
5378    fn plan_from_fixture(fixture: &Fixture) -> super::RootReconstructionPlan {
5379        let manifests = fixture
5380            .manifests
5381            .iter()
5382            .map(|input| {
5383                ManifestInput::new(input.digest(), Cursor::new(input.encoded.get_ref().clone()))
5384            })
5385            .collect::<Vec<_>>();
5386        decode_and_plan(
5387            fixture.index.as_slice(),
5388            fixture.version.as_slice(),
5389            manifests,
5390        )
5391        .expect("complete plan")
5392    }
5393
5394    fn write_package(root: &std::path::Path, fixture: &Fixture) {
5395        std::fs::create_dir(root.join("manifests")).expect("manifest directory");
5396        std::fs::create_dir(root.join("chunks")).expect("chunk directory");
5397        std::fs::write(root.join("index.json"), &fixture.index).expect("package index");
5398        std::fs::write(root.join("version.json"), &fixture.version).expect("package Version");
5399        for input in &fixture.manifests {
5400            std::fs::write(
5401                root.join("manifests")
5402                    .join(format!("{}.json", input.digest())),
5403                input.encoded.get_ref(),
5404            )
5405            .expect("package manifest");
5406        }
5407        for bytes in [root_manifest_bytes(), b"payload".to_vec()] {
5408            std::fs::write(root.join("chunks").join(sha256(&bytes)), bytes).expect("package chunk");
5409        }
5410    }
5411
5412    fn package_tree_snapshot(root: &Path) -> BTreeMap<String, Vec<u8>> {
5413        fn visit(root: &Path, relative: &Path, snapshot: &mut BTreeMap<String, Vec<u8>>) {
5414            let directory = root.join(relative);
5415            let mut entries = std::fs::read_dir(&directory)
5416                .expect("read package directory")
5417                .map(|entry| entry.expect("read package entry"))
5418                .collect::<Vec<_>>();
5419            entries.sort_by_key(|entry| entry.file_name());
5420            for entry in entries {
5421                let child_relative = relative.join(entry.file_name());
5422                let wire = child_relative
5423                    .components()
5424                    .map(|component| component.as_os_str().to_string_lossy())
5425                    .collect::<Vec<_>>()
5426                    .join("/");
5427                let metadata = entry.metadata().expect("package entry metadata");
5428                if metadata.is_dir() {
5429                    snapshot.insert(wire, b"directory".to_vec());
5430                    visit(root, &child_relative, snapshot);
5431                } else {
5432                    assert!(metadata.is_file(), "package contains only regular files");
5433                    snapshot.insert(wire, std::fs::read(entry.path()).expect("package bytes"));
5434                }
5435            }
5436        }
5437
5438        let mut snapshot = BTreeMap::new();
5439        visit(root, Path::new(""), &mut snapshot);
5440        snapshot
5441    }
5442
5443    fn root_manifest_bytes() -> Vec<u8> {
5444        serde_json::to_vec_pretty(&json!({
5445            "$schema": "https://folderbase.ai/protocol/0.5/folderbase.schema.json",
5446            "protocol_version": "0.5.0",
5447            "folderbase": {
5448                "id": FOLDERBASE_ID,
5449                "name": "Root reconstruction test",
5450                "kind": "project",
5451                "status": "active",
5452                "created_at": "2026-08-06T00:00:00Z"
5453            },
5454            "adapters": [],
5455            "policies": {
5456                "availability": "keep_local",
5457                "structural_changes": "approve",
5458                "archive": "manual",
5459                "cloud_sync": "disabled",
5460                "capture_ignore": {
5461                    "format": "folderbase-capture-ignore-v1",
5462                    "rules": []
5463                }
5464            }
5465        }))
5466        .expect("root manifest")
5467    }
5468
5469    fn mutate_index(fixture: &mut Fixture, mutate: impl FnOnce(&mut Value)) {
5470        let mut index: Value = serde_json::from_slice(&fixture.index).expect("decode index");
5471        mutate(&mut index);
5472        fixture.index = serde_json::to_vec(&index).expect("encode index");
5473    }
5474
5475    fn replace_live_manifest(fixture: &mut Fixture, replacement: ChunkManifest) {
5476        let replacement_digest = replacement.canonical_digest().expect("valid replacement");
5477        let mut previous_digest = None;
5478        mutate_index(fixture, |index| {
5479            let reference = &mut index["references"][1];
5480            previous_digest = Some(
5481                reference["chunk_manifest_sha256"]
5482                    .as_str()
5483                    .expect("manifest digest")
5484                    .to_owned(),
5485            );
5486            reference["chunk_manifest_sha256"] = json!(replacement_digest);
5487        });
5488        let previous_digest = previous_digest.expect("previous manifest digest");
5489        fixture
5490            .manifests
5491            .retain(|input| input.digest() != previous_digest);
5492        fixture
5493            .manifests
5494            .push(manifest_input(replacement_digest, replacement));
5495    }
5496
5497    fn version_json(root_manifest: &ChunkManifest, live_manifest: &ChunkManifest) -> Value {
5498        json!({
5499            "format": "folderbase-version-v1",
5500            "protocol_version": "0.5",
5501            "folderbase_id": FOLDERBASE_ID,
5502            "version_id": FOLDERBASE_VERSION_ID,
5503            "parents": [],
5504            "created_at": "2026-08-06T00:00:00Z",
5505            "path_policy": {
5506                "format": "folderbase-portable-path-v1",
5507                "normalization": "NFC",
5508                "normalization_unicode_version": "17.0.0",
5509                "case_folding": "full-default",
5510                "case_folding_unicode_version": "9.0.0"
5511            },
5512            "root_manifest": {
5513                "path": ".folderbase/manifest.json",
5514                "object_version_id": ROOT_VERSION_ID,
5515                "content_sha256": root_manifest.object_sha256,
5516                "bytes": root_manifest.object_bytes
5517            },
5518            "bindings": [
5519                {
5520                    "path": "current.txt",
5521                    "object_id": LIVE_OBJECT_ID,
5522                    "lifecycle": "live",
5523                    "kind": "regular_file",
5524                    "object_version_id": LIVE_VERSION_ID,
5525                    "content_sha256": live_manifest.object_sha256,
5526                    "bytes": live_manifest.object_bytes,
5527                    "executable": false
5528                },
5529                {
5530                    "path": "shortcut",
5531                    "object_id": "obj_01900000-0000-7000-8000-000000000007",
5532                    "lifecycle": "live",
5533                    "kind": "symlink",
5534                    "object_version_id": SYMLINK_VERSION_ID,
5535                    "target": "current.txt",
5536                    "target_safety": "relative-within-folderbase"
5537                }
5538            ],
5539            "tombstones": [{
5540                "path": "previous.txt",
5541                "object_id": LIVE_OBJECT_ID,
5542                "lifecycle": "deleted",
5543                "deleted_kind": "regular_file",
5544                "last_object_version_id": LIVE_VERSION_ID
5545            }],
5546            "exclusions": []
5547        })
5548    }
5549
5550    fn package_limits() -> Value {
5551        json!({
5552            "max_index_bytes": 8_388_608,
5553            "max_version_bytes": 67_108_864,
5554            "max_manifest_bytes": 67_108_864,
5555            "max_references": 16_385,
5556            "max_distinct_manifests": 16_385,
5557            "max_distinct_chunks": 1_048_576,
5558            "max_chunks_per_manifest": 262_144,
5559            "max_object_bytes": 1_099_511_627_776_u64,
5560            "max_total_object_bytes": 9_007_199_254_740_991_u64,
5561            "max_visible_entries": 16_384
5562        })
5563    }
5564
5565    fn manifest(bytes: &[u8], _chunk_byte: u8) -> ChunkManifest {
5566        ChunkManifest {
5567            format: MANIFEST_FORMAT_V1.to_owned(),
5568            algorithm: CHUNKING_ALGORITHM_V1.to_owned(),
5569            profile: STANDARD_PROFILE_V1.to_owned(),
5570            minimum_chunk_bytes: 256 * 1024,
5571            average_chunk_bytes: 1024 * 1024,
5572            maximum_chunk_bytes: 4 * 1024 * 1024,
5573            object_sha256: sha256(bytes),
5574            object_bytes: bytes.len() as u64,
5575            chunks: vec![ChunkDescriptor {
5576                index: 0,
5577                offset: 0,
5578                bytes: bytes.len() as u64,
5579                sha256: sha256(bytes),
5580            }],
5581        }
5582    }
5583
5584    fn manifest_input(digest: String, manifest: ChunkManifest) -> ManifestInput<Cursor<Vec<u8>>> {
5585        ManifestInput::new(
5586            digest,
5587            Cursor::new(serde_json::to_vec(&manifest).expect("encode manifest")),
5588        )
5589    }
5590
5591    fn sha256(bytes: &[u8]) -> String {
5592        format!("{:x}", Sha256::digest(bytes))
5593    }
5594}