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