Skip to main content

folderbase_core/
migration.rs

1mod transaction_v1;
2
3use std::{
4    cell::Cell,
5    collections::{BTreeMap, BTreeSet},
6    ffi::{OsStr, OsString},
7    fs,
8    io::{self, Read, Write},
9    path::{Component, Path, PathBuf},
10};
11
12#[cfg(unix)]
13use cap_fs_ext::DirExt;
14use cap_fs_ext::{FollowSymlinks, OpenOptionsFollowExt};
15use cap_std::fs::{Dir, OpenOptions as CapOpenOptions};
16use chrono::{DateTime, Utc};
17use serde::{Deserialize, Serialize};
18use sha2::{Digest, Sha256};
19use unicode_casefold::UnicodeCaseFold;
20use uuid::Uuid;
21
22#[cfg(test)]
23use crate::InitializationOptions;
24use crate::{
25    FolderbaseError, FolderbaseKind, NestedFolderbaseBoundary, ReconstructableTree, Result,
26    TemplateAnswerValue, TemplateArtifactKind, ValidationLevel,
27    folder_analysis::{AnalyzedFile, analyze_folder, expand_reconstructable_tree},
28    folderbase_capture::validate_folderbaseignore_content,
29    folderbase_state::FolderbaseState,
30    local_versions::{LocalVersionStore, StoreTransactionLock},
31    migration_filesystem::{
32        ExactDirectoryLeaf, ExactExistingClaimSource, ExactLeafClaimExpectation,
33        ExactLeafClaimRequest, ExactLeafClaimResult, ExactRegularLeaf, MigrationFilesystem,
34        MigrationRegularFact, VerifiedPrivateDirectory, VerifiedVisibleDirectory,
35    },
36    physical_identity::{PhysicalIdentity, RetainedPhysicalIdentity},
37    protocol_upgrade::scan_pending_work,
38    root_attestation::{DEFAULT_V05_CAPTURE_IGNORE_RULES, metadata_is_link_or_reparse},
39    template::{
40        load_builtin_template, render_template_for_capability_destination, template_package_sha256,
41    },
42    traversal_policy::{NestedFolderbaseBoundaryKind, classify_nested_folderbase_boundary},
43    validation::validate,
44    workspace::{has_nested_folderbase_marker, is_reserved_workspace_component},
45};
46use transaction_v1::{
47    MAX_JOURNAL_GENERATION_BYTES, MAX_JOURNAL_GENERATIONS, MAX_PROGRAM_BYTES, MutationProgramV1,
48    PrivatePublicationBindingV1, PrivatePublicationExactRegularFactV1, ProgramAbsentLeafV1,
49    ProgramGeneratedFileV1, ProgramGeneratedRoleV1, ProgramMaterializationV1, ProgramPrivateBlobV1,
50    ProgramStepV1, TRANSACTION_DIRECTORY, TransactionDirectionV1, TransactionJournalGenerationV1,
51    TransactionPhaseV1, validate_append, validate_chain,
52};
53
54const STATE_DIR: &str = ".folderbase";
55const MIGRATIONS_DIR: &str = ".folderbase/migrations";
56const MAX_MIGRATION_PLAN_BYTES: u64 = 8 * 1024 * 1024;
57const MAX_STRUCTURAL_TEXT_BYTES: u64 = 2 * 1024 * 1024;
58const GROUPED_ASSIGNMENT_THRESHOLD: usize = 32;
59const ASSIGNMENT_GROUP_RULE_VERSION: &str = "top_level_content_kind_v1";
60const GROUPED_ASSIGNMENTS_EXTENSION: &str = "x-folderbase-grouped-assignments-v1";
61const EXPANDED_RECONSTRUCTABLE_TREES_EXTENSION: &str =
62    "x-folderbase-expanded-reconstructable-trees-v1";
63const STRUCTURAL_PLAN_KIND: &str = "structural_reorganization";
64const SOURCE_TOPOLOGY_EXTENSION: &str = "x-folderbase-source-topology-v1";
65const MANAGED_BLOCK_BEGIN: &str = "<!-- folderbase:begin -->";
66const MANAGED_BLOCK_END: &str = "<!-- folderbase:end -->";
67const JOURNAL_GENERATION_STAGING_NAME: &str = ".next-generation.preparing";
68const JOURNAL_GENERATION_WRITE_NAME: &str = ".next-generation.writing";
69const JOURNAL_GENERATION_QUARANTINE_PREFIX: &str = ".next-generation-";
70const JOURNAL_GENERATION_QUARANTINE_SUFFIX: &str = ".quarantine";
71
72fn journal_generation_quarantine_name(generation: usize) -> String {
73    format!(
74        "{JOURNAL_GENERATION_QUARANTINE_PREFIX}{generation:020}{JOURNAL_GENERATION_QUARANTINE_SUFFIX}"
75    )
76}
77
78fn journal_generation_index(name: &OsStr) -> Option<usize> {
79    let name = name.to_str()?;
80    let digits = name.strip_suffix(".json")?;
81    if digits.len() != 20 || !digits.bytes().all(|byte| byte.is_ascii_digit()) {
82        return None;
83    }
84    let index = digits.parse::<usize>().ok()?;
85    (name == format!("{index:020}.json")).then_some(index)
86}
87
88fn journal_generation_quarantine_index(name: &OsStr) -> Option<usize> {
89    let name = name.to_str()?;
90    let digits = name
91        .strip_prefix(JOURNAL_GENERATION_QUARANTINE_PREFIX)?
92        .strip_suffix(JOURNAL_GENERATION_QUARANTINE_SUFFIX)?;
93    if digits.len() != 20 || !digits.bytes().all(|byte| byte.is_ascii_digit()) {
94        return None;
95    }
96    let index = digits.parse::<usize>().ok()?;
97    (name == journal_generation_quarantine_name(index)).then_some(index)
98}
99
100fn maximum_journal_directory_entries(maximum_generations: usize) -> usize {
101    maximum_generations.saturating_mul(2).saturating_add(2)
102}
103
104#[derive(Debug)]
105struct ClassifiedJournalEntries {
106    generation_names: Vec<OsString>,
107    staging_present: bool,
108    writing_present: bool,
109}
110
111fn classify_journal_entries(
112    filesystem: &MigrationFilesystem,
113    journal: &VerifiedPrivateDirectory,
114    journal_root: &Path,
115    entries: &[(OsString, bool)],
116    maximum_generations: usize,
117) -> Result<ClassifiedJournalEntries> {
118    let mut generations = Vec::new();
119    let mut quarantines = Vec::new();
120    let mut staging_present = false;
121    let mut writing_present = false;
122    for (name, is_directory) in entries {
123        if *is_directory {
124            return Err(FolderbaseError::InvalidRecord {
125                path: filesystem.display(&journal_root.join(name)),
126                message: "transaction journal contains an unexpected directory".to_owned(),
127            });
128        }
129        if name == OsStr::new(JOURNAL_GENERATION_STAGING_NAME) {
130            staging_present = true;
131        } else if name == OsStr::new(JOURNAL_GENERATION_WRITE_NAME) {
132            writing_present = true;
133        } else if let Some(index) = journal_generation_index(name) {
134            generations.push((index, name.clone()));
135        } else if let Some(index) = journal_generation_quarantine_index(name) {
136            quarantines.push((index, name.clone()));
137        } else {
138            return Err(FolderbaseError::InvalidRecord {
139                path: filesystem.display(&journal_root.join(name)),
140                message: "transaction journal contains an unknown artifact".to_owned(),
141            });
142        }
143    }
144    generations.sort_by_key(|(index, _)| *index);
145    for (expected, (observed, name)) in generations.iter().enumerate() {
146        if *observed != expected {
147            return Err(FolderbaseError::InvalidRecord {
148                path: filesystem.display(&journal_root.join(name)),
149                message: "transaction journal contains an unknown or gapped generation".to_owned(),
150            });
151        }
152    }
153    if generations.len() > maximum_generations {
154        return Err(FolderbaseError::InvalidRecord {
155            path: filesystem.display(journal_root),
156            message: "transaction journal exceeds its generation bound".to_owned(),
157        });
158    }
159    quarantines.sort_by_key(|(index, _)| *index);
160    for (index, name) in &quarantines {
161        if *index >= maximum_generations || *index > generations.len() {
162            return Err(FolderbaseError::InvalidRecord {
163                path: filesystem.display(&journal_root.join(name)),
164                message: "journal quarantine does not name a bounded durable generation".to_owned(),
165            });
166        }
167        journal.verify_bounded_private_regular(name, MAX_JOURNAL_GENERATION_BYTES)?;
168    }
169    Ok(ClassifiedJournalEntries {
170        generation_names: generations.into_iter().map(|(_, name)| name).collect(),
171        staging_present,
172        writing_present,
173    })
174}
175
176#[derive(Debug, Serialize, Deserialize, PartialEq, Eq)]
177pub struct MigrationAnalysis {
178    pub id: String,
179    #[serde(with = "crate::portable_wire_path::display")]
180    pub root: PathBuf,
181    pub captured_at: DateTime<Utc>,
182    pub inventory_digest: String,
183    pub file_count: u64,
184    pub total_bytes: u64,
185    pub questions: Vec<MigrationQuestion>,
186    pub proposed_boundaries: Vec<ProposedBoundary>,
187    #[serde(default)]
188    pub proposed_targets: Vec<MigrationTarget>,
189    #[serde(default)]
190    pub reconstructable_trees: Vec<ReconstructableTree>,
191    #[serde(default)]
192    pub nested_folderbases: Vec<NestedFolderbaseBoundary>,
193    #[serde(skip)]
194    files: Vec<AnalyzedFile>,
195    #[serde(skip)]
196    root_identity: Option<RetainedPhysicalIdentity>,
197}
198
199#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
200pub struct MigrationQuestion {
201    pub id: String,
202    pub prompt: String,
203    pub context: String,
204    pub kind: MigrationQuestionKind,
205    #[serde(default)]
206    pub options: Vec<MigrationOption>,
207    #[serde(default)]
208    pub recommended_option_id: String,
209}
210
211#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
212pub struct MigrationOption {
213    pub id: String,
214    pub label: String,
215    pub consequence: String,
216}
217
218#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
219#[serde(tag = "type", rename_all = "snake_case")]
220pub enum MigrationQuestionKind {
221    Decision,
222    Assignment {
223        #[serde(with = "crate::portable_wire_path::relative")]
224        source_path: PathBuf,
225        content_kind: MigrationContentKind,
226    },
227    AssignmentGroup {
228        rule_version: String,
229        #[serde(with = "crate::portable_wire_path::relative_or_current")]
230        source_root: PathBuf,
231        #[serde(with = "crate::portable_wire_path::relative::vec")]
232        source_paths: Vec<PathBuf>,
233        content_kind: MigrationContentKind,
234        coverage_digest: String,
235    },
236}
237
238#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord)]
239#[serde(rename_all = "snake_case")]
240pub enum MigrationContentKind {
241    Canonical,
242    Generated,
243    SecretShaped,
244    Temporary,
245}
246
247#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
248pub struct ProposedBoundary {
249    #[serde(with = "crate::portable_wire_path::relative")]
250    pub path: PathBuf,
251    pub suggested_name: String,
252    pub reason: String,
253}
254
255#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
256pub struct MigrationTarget {
257    pub id: String,
258    pub kind: MigrationTargetKind,
259    #[serde(with = "crate::portable_wire_path::relative_or_current")]
260    pub path: PathBuf,
261    pub suggested_name: String,
262    pub reason: String,
263}
264
265#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
266#[serde(rename_all = "snake_case")]
267pub enum MigrationTargetKind {
268    Folderbase,
269    Workspace,
270    ScopedView,
271    RetainedFolder,
272    Exclusion,
273}
274
275#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
276pub struct MigrationAnswer {
277    pub question_id: String,
278    pub answer: String,
279    #[serde(default, skip_serializing_if = "Vec::is_empty")]
280    pub exceptions: Vec<MigrationAnswerException>,
281}
282
283#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
284pub struct MigrationAnswerException {
285    #[serde(with = "crate::portable_wire_path::relative")]
286    pub source_path: PathBuf,
287    pub target_id: String,
288}
289
290#[derive(Debug, Serialize, Deserialize)]
291pub struct MigrationPlan {
292    pub protocol_version: String,
293    pub id: String,
294    #[serde(with = "crate::portable_wire_path::display")]
295    pub root: PathBuf,
296    pub state: MigrationState,
297    source_inventory: SourceInventory,
298    pub answers: Vec<MigrationAnswer>,
299    #[serde(default)]
300    pub template_references: Vec<String>,
301    pub targets: Vec<MigrationTarget>,
302    pub operations: Vec<MigrationOperation>,
303    pub exclusions: Vec<MigrationExclusion>,
304    #[serde(default, skip_serializing_if = "Option::is_none")]
305    approval_digest: Option<String>,
306    #[serde(default, flatten)]
307    extensions: BTreeMap<String, serde_json::Value>,
308    #[serde(skip)]
309    root_identity: Option<RetainedPhysicalIdentity>,
310}
311
312impl PartialEq for MigrationPlan {
313    fn eq(&self, other: &Self) -> bool {
314        self.protocol_version == other.protocol_version
315            && self.id == other.id
316            && self.root == other.root
317            && self.state == other.state
318            && self.source_inventory == other.source_inventory
319            && self.answers == other.answers
320            && self.template_references == other.template_references
321            && self.targets == other.targets
322            && self.operations == other.operations
323            && self.exclusions == other.exclusions
324            && self.approval_digest == other.approval_digest
325            && self.extensions == other.extensions
326    }
327}
328
329impl Eq for MigrationPlan {}
330
331impl MigrationPlan {
332    /// Return the immutable approval digest once this plan has been approved.
333    pub fn approval_digest(&self) -> Option<&str> {
334        self.approval_digest.as_deref()
335    }
336
337    /// Reopen a durable migration proposal by ID.
338    pub fn reopen(root: impl AsRef<Path>, migration_id: &str) -> Result<Self> {
339        let (root, retained_root) = canonical_root_with_identity(root.as_ref())?;
340        let mut plan = load_plan(&root, migration_id)?;
341        if plan
342            .root_identity
343            .as_ref()
344            .map(|identity| identity.identity())
345            != Some(retained_root.identity())
346        {
347            return Err(FolderbaseError::MigrationSourceChanged(root));
348        }
349        plan.root_identity = Some(retained_root);
350        Ok(plan)
351    }
352
353    /// Reject a proposed plan without applying content operations.
354    pub fn reject(mut self) -> Result<Self> {
355        require_state(self.state, MigrationState::Proposed)?;
356        self.state = MigrationState::Rejected;
357        persist_plan(&self)?;
358        Ok(self)
359    }
360
361    /// Propose a digest-bound reorganization of an initialized folderbase.
362    ///
363    /// Planning reads current bytes and persists a preview, but does not mutate
364    /// user content. Approval creates verified recovery snapshots before the
365    /// plan can become apply-capable.
366    pub fn propose_structural(
367        root: impl AsRef<Path>,
368        mut operations: Vec<MigrationOperation>,
369    ) -> Result<Self> {
370        let root = canonical_root(root.as_ref())?;
371        let report = validate(&root, ValidationLevel::Shallow)?;
372        if !report.valid {
373            return Err(FolderbaseError::InvalidRoot(root));
374        }
375        if operations.is_empty()
376            || operations
377                .iter()
378                .any(|operation| !operation.is_structural())
379        {
380            return Err(FolderbaseError::InvalidRecord {
381                path: root,
382                message: "a structural proposal requires at least one typed structural operation"
383                    .to_owned(),
384            });
385        }
386
387        let root_identity = RetainedPhysicalIdentity::from_path(&root)
388            .map_err(|source| FolderbaseError::io(&root, source))?;
389        let mut source_files = Vec::with_capacity(operations.len());
390        let mut source_keys = BTreeSet::new();
391        let mut move_destinations = BTreeSet::new();
392        for operation in &mut operations {
393            let source_path = operation
394                .structural_source_path()
395                .expect("structural operations always expose one mutable source");
396            refuse_nested_folderbase_path(&root, source_path)?;
397            if let Some(destination_path) = operation.structural_destination_path() {
398                refuse_nested_folderbase_path(&root, destination_path)?;
399            }
400            enrich_structural_operation(&root, operation)?;
401            let source_path = operation
402                .structural_source_path()
403                .expect("structural operations always expose one mutable source");
404            let source_key = portable_path_key(source_path);
405            if !source_keys.insert(source_key.clone()) {
406                return Err(FolderbaseError::InvalidRecord {
407                    path: root,
408                    message: format!(
409                        "structural operations may mutate a path only once: {}",
410                        source_path.display()
411                    ),
412                });
413            }
414            if let Some(destination) = operation.structural_destination_path() {
415                let destination_key = portable_path_key(destination);
416                if !move_destinations.insert(destination_key.clone())
417                    || destination_key == source_key
418                {
419                    return Err(FolderbaseError::InvalidRecord {
420                        path: root,
421                        message: format!(
422                            "structural move destination is ambiguous: {}",
423                            destination.display()
424                        ),
425                    });
426                }
427            }
428            let absolute = safe_join(&root, source_path)?;
429            let metadata = fs::symlink_metadata(&absolute)
430                .map_err(|source| FolderbaseError::io(&absolute, source))?;
431            source_files.push(SourceFile {
432                path: source_path.to_path_buf(),
433                bytes: metadata.len(),
434                sha256: operation
435                    .structural_expected_sha256()
436                    .expect("enriched structural operation has a digest")
437                    .to_owned(),
438            });
439        }
440        if source_keys
441            .iter()
442            .any(|source| move_destinations.contains(source))
443        {
444            return Err(FolderbaseError::InvalidRecord {
445                path: root,
446                message: "structural moves may not form chains or cycles in one approved batch"
447                    .to_owned(),
448            });
449        }
450        source_files.sort_by(|left, right| left.path.cmp(&right.path));
451        let source_digest = inventory_digest(&source_files)?;
452        let topology_analysis = analyze_folder(&root)?;
453        let source_topology = source_topology_snapshot(
454            &topology_analysis.files,
455            &topology_analysis.reconstructable_trees,
456            &topology_analysis.nested_folderbases,
457            &[],
458        );
459        let mut extensions = BTreeMap::new();
460        extensions.insert(
461            SOURCE_TOPOLOGY_EXTENSION.to_owned(),
462            serde_json::to_value(source_topology)
463                .map_err(|source| FolderbaseError::json(&root, source))?,
464        );
465        extensions.insert(
466            "plan_kind".to_owned(),
467            serde_json::Value::String(STRUCTURAL_PLAN_KIND.to_owned()),
468        );
469        extensions.insert(
470            "snapshot_required".to_owned(),
471            serde_json::Value::Bool(true),
472        );
473        extensions.insert(
474            "base_folderbase_version".to_owned(),
475            serde_json::Value::Null,
476        );
477        extensions.insert("questions".to_owned(), serde_json::Value::Array(Vec::new()));
478        extensions.insert(
479            "proposed_folderbases".to_owned(),
480            serde_json::Value::Array(Vec::new()),
481        );
482        extensions.insert(
483            "storage_impact".to_owned(),
484            serde_json::json!({
485                "local_bytes_delta": source_files.iter().map(|source| source.bytes).sum::<u64>(),
486                "cloud_bytes_delta": 0,
487                "reclaimable_local_bytes": 0,
488            }),
489        );
490        extensions.insert(
491            "rollback".to_owned(),
492            serde_json::json!({
493                "snapshot_required": true,
494                "strategy": "restore_snapshot",
495                "snapshot_id": null,
496            }),
497        );
498        let plan = Self {
499            protocol_version: "0.2.0".to_owned(),
500            id: format!("migration_{}", Uuid::now_v7()),
501            root,
502            state: MigrationState::Proposed,
503            source_inventory: SourceInventory {
504                algorithm: "sha256".to_owned(),
505                digest: source_digest,
506                files: source_files,
507            },
508            answers: Vec::new(),
509            template_references: Vec::new(),
510            targets: Vec::new(),
511            operations,
512            exclusions: Vec::new(),
513            approval_digest: None,
514            extensions,
515            root_identity: Some(root_identity),
516        };
517        persist_new_plan(&plan)?;
518        Ok(plan)
519    }
520}
521
522#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
523#[serde(rename_all = "snake_case")]
524pub enum MigrationState {
525    Analyzing,
526    Questions,
527    Proposed,
528    Approved,
529    Applying,
530    Verified,
531    Conflicted,
532    RollingBack,
533    Rejected,
534    RolledBack,
535}
536
537impl MigrationState {
538    fn as_str(self) -> &'static str {
539        match self {
540            Self::Analyzing => "analyzing",
541            Self::Questions => "questions",
542            Self::Proposed => "proposed",
543            Self::Approved => "approved",
544            Self::Applying => "applying",
545            Self::Verified => "verified",
546            Self::Conflicted => "conflicted",
547            Self::RollingBack => "rolling_back",
548            Self::Rejected => "rejected",
549            Self::RolledBack => "rolled_back",
550        }
551    }
552}
553
554#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
555#[serde(tag = "type", rename_all = "snake_case")]
556pub enum MigrationOperation {
557    CreateFolder {
558        #[serde(with = "crate::portable_wire_path::relative")]
559        path: PathBuf,
560    },
561    CopyFile {
562        #[serde(with = "crate::portable_wire_path::relative")]
563        source_path: PathBuf,
564        #[serde(with = "crate::portable_wire_path::relative")]
565        destination_path: PathBuf,
566        expected_sha256: String,
567    },
568    MoveObject {
569        #[serde(with = "crate::portable_wire_path::relative")]
570        source_path: PathBuf,
571        #[serde(with = "crate::portable_wire_path::relative")]
572        destination_path: PathBuf,
573        #[serde(default)]
574        expected_sha256: String,
575        #[serde(default, with = "crate::portable_wire_path::relative::option")]
576        snapshot_path: Option<PathBuf>,
577        #[serde(default)]
578        snapshot_sha256: Option<String>,
579    },
580    UpdateAdapter {
581        #[serde(with = "crate::portable_wire_path::relative")]
582        path: PathBuf,
583        managed_block: String,
584        #[serde(default)]
585        expected_sha256: String,
586        #[serde(default)]
587        expected_result_sha256: String,
588        #[serde(default, with = "crate::portable_wire_path::relative::option")]
589        snapshot_path: Option<PathBuf>,
590        #[serde(default)]
591        snapshot_sha256: Option<String>,
592    },
593    UpdateIgnorePolicy {
594        #[serde(with = "crate::portable_wire_path::relative")]
595        path: PathBuf,
596        content: String,
597        #[serde(default)]
598        expected_sha256: String,
599        #[serde(default)]
600        expected_result_sha256: String,
601        #[serde(default, with = "crate::portable_wire_path::relative::option")]
602        snapshot_path: Option<PathBuf>,
603        #[serde(default)]
604        snapshot_sha256: Option<String>,
605    },
606    UpdatePolicy {
607        #[serde(with = "crate::portable_wire_path::relative")]
608        manifest_path: PathBuf,
609        policy: String,
610        value: serde_json::Value,
611        #[serde(default)]
612        expected_sha256: String,
613        #[serde(default)]
614        expected_result_sha256: String,
615        #[serde(default, with = "crate::portable_wire_path::relative::option")]
616        snapshot_path: Option<PathBuf>,
617        #[serde(default)]
618        snapshot_sha256: Option<String>,
619    },
620    ChangeKind {
621        #[serde(with = "crate::portable_wire_path::relative")]
622        manifest_path: PathBuf,
623        new_kind: FolderbaseKind,
624        #[serde(default)]
625        expected_sha256: String,
626        #[serde(default)]
627        expected_result_sha256: String,
628        #[serde(default, with = "crate::portable_wire_path::relative::option")]
629        snapshot_path: Option<PathBuf>,
630        #[serde(default)]
631        snapshot_sha256: Option<String>,
632    },
633    MarkCanonical {
634        #[serde(with = "crate::portable_wire_path::relative")]
635        object_record_path: PathBuf,
636        #[serde(default)]
637        expected_sha256: String,
638        #[serde(default)]
639        expected_result_sha256: String,
640        #[serde(default, with = "crate::portable_wire_path::relative::option")]
641        snapshot_path: Option<PathBuf>,
642        #[serde(default)]
643        snapshot_sha256: Option<String>,
644    },
645    MarkSuperseded {
646        #[serde(with = "crate::portable_wire_path::relative")]
647        object_record_path: PathBuf,
648        superseded_by: String,
649        #[serde(default)]
650        expected_sha256: String,
651        #[serde(default)]
652        expected_result_sha256: String,
653        #[serde(default, with = "crate::portable_wire_path::relative::option")]
654        snapshot_path: Option<PathBuf>,
655        #[serde(default)]
656        snapshot_sha256: Option<String>,
657    },
658    ArchiveObject {
659        #[serde(with = "crate::portable_wire_path::relative")]
660        object_record_path: PathBuf,
661        #[serde(default)]
662        expected_sha256: String,
663        #[serde(default)]
664        expected_result_sha256: String,
665        #[serde(default, with = "crate::portable_wire_path::relative::option")]
666        snapshot_path: Option<PathBuf>,
667        #[serde(default)]
668        snapshot_sha256: Option<String>,
669    },
670    AddRelationship {
671        #[serde(with = "crate::portable_wire_path::relative")]
672        object_record_path: PathBuf,
673        relationship_type: String,
674        target_object_id: String,
675        #[serde(default)]
676        expected_sha256: String,
677        #[serde(default)]
678        expected_result_sha256: String,
679        #[serde(default, with = "crate::portable_wire_path::relative::option")]
680        snapshot_path: Option<PathBuf>,
681        #[serde(default)]
682        snapshot_sha256: Option<String>,
683    },
684}
685
686impl MigrationOperation {
687    pub fn move_object(
688        source_path: impl Into<PathBuf>,
689        destination_path: impl Into<PathBuf>,
690    ) -> Self {
691        Self::MoveObject {
692            source_path: source_path.into(),
693            destination_path: destination_path.into(),
694            expected_sha256: String::new(),
695            snapshot_path: None,
696            snapshot_sha256: None,
697        }
698    }
699
700    pub fn update_adapter(path: impl Into<PathBuf>, managed_block: impl Into<String>) -> Self {
701        Self::UpdateAdapter {
702            path: path.into(),
703            managed_block: managed_block.into(),
704            expected_sha256: String::new(),
705            expected_result_sha256: String::new(),
706            snapshot_path: None,
707            snapshot_sha256: None,
708        }
709    }
710
711    pub fn update_ignore_policy(content: impl Into<String>) -> Self {
712        Self::UpdateIgnorePolicy {
713            path: PathBuf::from(".folderbaseignore"),
714            content: content.into(),
715            expected_sha256: String::new(),
716            expected_result_sha256: String::new(),
717            snapshot_path: None,
718            snapshot_sha256: None,
719        }
720    }
721
722    pub fn update_policy(policy: impl Into<String>, value: serde_json::Value) -> Self {
723        Self::UpdatePolicy {
724            manifest_path: PathBuf::from(".folderbase/manifest.json"),
725            policy: policy.into(),
726            value,
727            expected_sha256: String::new(),
728            expected_result_sha256: String::new(),
729            snapshot_path: None,
730            snapshot_sha256: None,
731        }
732    }
733
734    pub fn change_kind(new_kind: FolderbaseKind) -> Self {
735        Self::ChangeKind {
736            manifest_path: PathBuf::from(".folderbase/manifest.json"),
737            new_kind,
738            expected_sha256: String::new(),
739            expected_result_sha256: String::new(),
740            snapshot_path: None,
741            snapshot_sha256: None,
742        }
743    }
744
745    pub fn mark_canonical(object_record_path: impl Into<PathBuf>) -> Self {
746        Self::MarkCanonical {
747            object_record_path: object_record_path.into(),
748            expected_sha256: String::new(),
749            expected_result_sha256: String::new(),
750            snapshot_path: None,
751            snapshot_sha256: None,
752        }
753    }
754
755    pub fn mark_superseded(
756        object_record_path: impl Into<PathBuf>,
757        superseded_by: impl Into<String>,
758    ) -> Self {
759        Self::MarkSuperseded {
760            object_record_path: object_record_path.into(),
761            superseded_by: superseded_by.into(),
762            expected_sha256: String::new(),
763            expected_result_sha256: String::new(),
764            snapshot_path: None,
765            snapshot_sha256: None,
766        }
767    }
768
769    pub fn archive_object(object_record_path: impl Into<PathBuf>) -> Self {
770        Self::ArchiveObject {
771            object_record_path: object_record_path.into(),
772            expected_sha256: String::new(),
773            expected_result_sha256: String::new(),
774            snapshot_path: None,
775            snapshot_sha256: None,
776        }
777    }
778
779    pub fn add_relationship(
780        object_record_path: impl Into<PathBuf>,
781        relationship_type: impl Into<String>,
782        target_object_id: impl Into<String>,
783    ) -> Self {
784        Self::AddRelationship {
785            object_record_path: object_record_path.into(),
786            relationship_type: relationship_type.into(),
787            target_object_id: target_object_id.into(),
788            expected_sha256: String::new(),
789            expected_result_sha256: String::new(),
790            snapshot_path: None,
791            snapshot_sha256: None,
792        }
793    }
794
795    fn is_structural(&self) -> bool {
796        !matches!(self, Self::CreateFolder { .. } | Self::CopyFile { .. })
797    }
798
799    fn structural_source_path(&self) -> Option<&Path> {
800        match self {
801            Self::MoveObject { source_path, .. } => Some(source_path),
802            Self::UpdateAdapter { path, .. } | Self::UpdateIgnorePolicy { path, .. } => Some(path),
803            Self::UpdatePolicy { manifest_path, .. } | Self::ChangeKind { manifest_path, .. } => {
804                Some(manifest_path)
805            }
806            Self::MarkCanonical {
807                object_record_path, ..
808            }
809            | Self::MarkSuperseded {
810                object_record_path, ..
811            }
812            | Self::ArchiveObject {
813                object_record_path, ..
814            }
815            | Self::AddRelationship {
816                object_record_path, ..
817            } => Some(object_record_path),
818            Self::CreateFolder { .. } | Self::CopyFile { .. } => None,
819        }
820    }
821
822    fn structural_destination_path(&self) -> Option<&Path> {
823        match self {
824            Self::MoveObject {
825                destination_path, ..
826            } => Some(destination_path),
827            _ => None,
828        }
829    }
830
831    fn structural_expected_sha256(&self) -> Option<&str> {
832        match self {
833            Self::MoveObject {
834                expected_sha256, ..
835            }
836            | Self::UpdateAdapter {
837                expected_sha256, ..
838            }
839            | Self::UpdateIgnorePolicy {
840                expected_sha256, ..
841            }
842            | Self::UpdatePolicy {
843                expected_sha256, ..
844            }
845            | Self::ChangeKind {
846                expected_sha256, ..
847            }
848            | Self::MarkCanonical {
849                expected_sha256, ..
850            }
851            | Self::MarkSuperseded {
852                expected_sha256, ..
853            }
854            | Self::ArchiveObject {
855                expected_sha256, ..
856            }
857            | Self::AddRelationship {
858                expected_sha256, ..
859            } => Some(expected_sha256),
860            Self::CreateFolder { .. } | Self::CopyFile { .. } => None,
861        }
862    }
863
864    fn structural_expected_result_sha256(&self) -> Option<&str> {
865        match self {
866            Self::MoveObject {
867                expected_sha256, ..
868            } => Some(expected_sha256),
869            Self::UpdateAdapter {
870                expected_result_sha256,
871                ..
872            }
873            | Self::UpdateIgnorePolicy {
874                expected_result_sha256,
875                ..
876            }
877            | Self::UpdatePolicy {
878                expected_result_sha256,
879                ..
880            }
881            | Self::ChangeKind {
882                expected_result_sha256,
883                ..
884            }
885            | Self::MarkCanonical {
886                expected_result_sha256,
887                ..
888            }
889            | Self::MarkSuperseded {
890                expected_result_sha256,
891                ..
892            }
893            | Self::ArchiveObject {
894                expected_result_sha256,
895                ..
896            }
897            | Self::AddRelationship {
898                expected_result_sha256,
899                ..
900            } => Some(expected_result_sha256),
901            Self::CreateFolder { .. } | Self::CopyFile { .. } => None,
902        }
903    }
904
905    fn structural_snapshot(&self) -> Option<(&Path, &str)> {
906        match self {
907            Self::MoveObject {
908                snapshot_path,
909                snapshot_sha256,
910                ..
911            }
912            | Self::UpdateAdapter {
913                snapshot_path,
914                snapshot_sha256,
915                ..
916            }
917            | Self::UpdateIgnorePolicy {
918                snapshot_path,
919                snapshot_sha256,
920                ..
921            }
922            | Self::UpdatePolicy {
923                snapshot_path,
924                snapshot_sha256,
925                ..
926            }
927            | Self::ChangeKind {
928                snapshot_path,
929                snapshot_sha256,
930                ..
931            }
932            | Self::MarkCanonical {
933                snapshot_path,
934                snapshot_sha256,
935                ..
936            }
937            | Self::MarkSuperseded {
938                snapshot_path,
939                snapshot_sha256,
940                ..
941            }
942            | Self::ArchiveObject {
943                snapshot_path,
944                snapshot_sha256,
945                ..
946            }
947            | Self::AddRelationship {
948                snapshot_path,
949                snapshot_sha256,
950                ..
951            } => snapshot_path.as_deref().zip(snapshot_sha256.as_deref()),
952            Self::CreateFolder { .. } | Self::CopyFile { .. } => None,
953        }
954    }
955
956    fn set_structural_snapshot(&mut self, path: PathBuf, sha256: String) {
957        match self {
958            Self::MoveObject {
959                snapshot_path,
960                snapshot_sha256,
961                ..
962            }
963            | Self::UpdateAdapter {
964                snapshot_path,
965                snapshot_sha256,
966                ..
967            }
968            | Self::UpdateIgnorePolicy {
969                snapshot_path,
970                snapshot_sha256,
971                ..
972            }
973            | Self::UpdatePolicy {
974                snapshot_path,
975                snapshot_sha256,
976                ..
977            }
978            | Self::ChangeKind {
979                snapshot_path,
980                snapshot_sha256,
981                ..
982            }
983            | Self::MarkCanonical {
984                snapshot_path,
985                snapshot_sha256,
986                ..
987            }
988            | Self::MarkSuperseded {
989                snapshot_path,
990                snapshot_sha256,
991                ..
992            }
993            | Self::ArchiveObject {
994                snapshot_path,
995                snapshot_sha256,
996                ..
997            }
998            | Self::AddRelationship {
999                snapshot_path,
1000                snapshot_sha256,
1001                ..
1002            } => {
1003                *snapshot_path = Some(path);
1004                *snapshot_sha256 = Some(sha256);
1005            }
1006            Self::CreateFolder { .. } | Self::CopyFile { .. } => {
1007                unreachable!("additive operation cannot receive a structural snapshot")
1008            }
1009        }
1010    }
1011}
1012
1013fn enrich_structural_operation(root: &Path, operation: &mut MigrationOperation) -> Result<()> {
1014    let source_path = operation
1015        .structural_source_path()
1016        .expect("structural operation has a source")
1017        .to_path_buf();
1018    ensure_safe_relative(&source_path)?;
1019    let source = safe_join(root, &source_path)?;
1020    let bytes = if matches!(operation, MigrationOperation::MoveObject { .. }) {
1021        let metadata =
1022            fs::symlink_metadata(&source).map_err(|error| FolderbaseError::io(&source, error))?;
1023        if !metadata.is_file() || metadata.file_type().is_symlink() {
1024            return Err(FolderbaseError::InvalidRecord {
1025                path: source.clone(),
1026                message: "structural move source must be a regular file".to_owned(),
1027            });
1028        }
1029        None
1030    } else {
1031        Some(read_bounded_regular(&source, MAX_MIGRATION_PLAN_BYTES)?)
1032    };
1033    let expected_sha256 = match bytes.as_deref() {
1034        Some(bytes) => sha256_bytes(bytes),
1035        None => sha256_path(&source)?,
1036    };
1037
1038    match operation {
1039        MigrationOperation::MoveObject {
1040            source_path,
1041            destination_path,
1042            expected_sha256: expected,
1043            snapshot_path,
1044            snapshot_sha256,
1045        } => {
1046            ensure_move_content_path(source_path)?;
1047            ensure_move_content_path(destination_path)?;
1048            refuse_tracked_move_path(root, source_path)?;
1049            refuse_tracked_move_path(root, destination_path)?;
1050            if portable_path_key(source_path) == portable_path_key(destination_path) {
1051                return Err(FolderbaseError::InvalidRecord {
1052                    path: source,
1053                    message: "move_object source and destination must be distinct".to_owned(),
1054                });
1055            }
1056            let destination = safe_join(root, destination_path)?;
1057            if destination.exists() {
1058                return Err(FolderbaseError::WouldOverwrite(destination));
1059            }
1060            let parent = destination
1061                .parent()
1062                .ok_or_else(|| FolderbaseError::UnsafePath(destination_path.clone()))?;
1063            let parent_metadata = fs::symlink_metadata(parent)
1064                .map_err(|source| FolderbaseError::io(parent, source))?;
1065            if !parent_metadata.is_dir() || parent_metadata.file_type().is_symlink() {
1066                return Err(FolderbaseError::UnsafePath(parent.to_path_buf()));
1067            }
1068            *expected = expected_sha256;
1069            *snapshot_path = None;
1070            *snapshot_sha256 = None;
1071        }
1072        MigrationOperation::UpdateAdapter {
1073            path,
1074            managed_block,
1075            expected_sha256: expected,
1076            expected_result_sha256,
1077            snapshot_path,
1078            snapshot_sha256,
1079        } => {
1080            let bytes = bytes
1081                .as_deref()
1082                .expect("adapter updates require bounded source bytes");
1083            if !matches!(
1084                path.file_name().and_then(|name| name.to_str()),
1085                Some("AGENTS.md" | "CLAUDE.md")
1086            ) {
1087                return Err(FolderbaseError::InvalidRecord {
1088                    path: source,
1089                    message: "update_adapter is limited to AGENTS.md or CLAUDE.md".to_owned(),
1090                });
1091            }
1092            let current =
1093                std::str::from_utf8(bytes).map_err(|_| FolderbaseError::InvalidRecord {
1094                    path: source.clone(),
1095                    message: "agent adapter must be UTF-8 text".to_owned(),
1096                })?;
1097            let merged = merge_managed_block(current, managed_block, &source)?;
1098            *expected = expected_sha256;
1099            *expected_result_sha256 = sha256_bytes(merged.as_bytes());
1100            *snapshot_path = None;
1101            *snapshot_sha256 = None;
1102        }
1103        MigrationOperation::UpdateIgnorePolicy {
1104            path,
1105            content,
1106            expected_sha256: expected,
1107            expected_result_sha256,
1108            snapshot_path,
1109            snapshot_sha256,
1110        } => {
1111            validate_typed_ignore_policy_update(root, path, content, &source)?;
1112            *expected = expected_sha256;
1113            *expected_result_sha256 = sha256_bytes(content.as_bytes());
1114            *snapshot_path = None;
1115            *snapshot_sha256 = None;
1116        }
1117        MigrationOperation::UpdatePolicy {
1118            manifest_path,
1119            policy,
1120            value,
1121            expected_sha256: expected,
1122            expected_result_sha256,
1123            snapshot_path,
1124            snapshot_sha256,
1125        } => {
1126            let bytes = bytes
1127                .as_deref()
1128                .expect("policy updates require bounded source bytes");
1129            if manifest_path != Path::new(".folderbase/manifest.json")
1130                || !is_lowercase_protocol_token(policy)
1131            {
1132                return Err(FolderbaseError::InvalidRecord {
1133                    path: source,
1134                    message: "manifest policy key is invalid".to_owned(),
1135                });
1136            }
1137            let mut document = parse_structural_json(&source, bytes)?;
1138            let policies = document
1139                .get_mut("policies")
1140                .and_then(serde_json::Value::as_object_mut)
1141                .ok_or_else(|| FolderbaseError::InvalidRecord {
1142                    path: source.clone(),
1143                    message: "manifest is missing its policies object".to_owned(),
1144                })?;
1145            policies.insert(policy.clone(), value.clone());
1146            let result = pretty_json_bytes(&source, &document)?;
1147            *expected = expected_sha256;
1148            *expected_result_sha256 = sha256_bytes(&result);
1149            *snapshot_path = None;
1150            *snapshot_sha256 = None;
1151        }
1152        MigrationOperation::ChangeKind {
1153            manifest_path,
1154            new_kind,
1155            expected_sha256: expected,
1156            expected_result_sha256,
1157            snapshot_path,
1158            snapshot_sha256,
1159        } => {
1160            let bytes = bytes
1161                .as_deref()
1162                .expect("kind changes require bounded source bytes");
1163            if manifest_path != Path::new(".folderbase/manifest.json") {
1164                return Err(FolderbaseError::InvalidRecord {
1165                    path: source,
1166                    message: "kind changes must target the canonical manifest".to_owned(),
1167                });
1168            }
1169            let mut document = parse_structural_json(&source, bytes)?;
1170            let folderbase = document
1171                .get_mut("folderbase")
1172                .and_then(serde_json::Value::as_object_mut)
1173                .ok_or_else(|| FolderbaseError::InvalidRecord {
1174                    path: source.clone(),
1175                    message: "manifest is missing its folderbase object".to_owned(),
1176                })?;
1177            folderbase.insert(
1178                "kind".to_owned(),
1179                serde_json::Value::String(structural_folderbase_kind_name(*new_kind).to_owned()),
1180            );
1181            let result = pretty_json_bytes(&source, &document)?;
1182            *expected = expected_sha256;
1183            *expected_result_sha256 = sha256_bytes(&result);
1184            *snapshot_path = None;
1185            *snapshot_sha256 = None;
1186        }
1187        MigrationOperation::MarkCanonical {
1188            object_record_path,
1189            expected_sha256: expected,
1190            expected_result_sha256,
1191            snapshot_path,
1192            snapshot_sha256,
1193        } => {
1194            let bytes = bytes
1195                .as_deref()
1196                .expect("lifecycle changes require bounded source bytes");
1197            validate_object_record_path(object_record_path, &source)?;
1198            let mut document = parse_structural_json(&source, bytes)?;
1199            set_object_lifecycle(&source, &mut document, "canonical", None)?;
1200            let result = pretty_json_bytes(&source, &document)?;
1201            *expected = expected_sha256;
1202            *expected_result_sha256 = sha256_bytes(&result);
1203            *snapshot_path = None;
1204            *snapshot_sha256 = None;
1205        }
1206        MigrationOperation::ArchiveObject {
1207            object_record_path,
1208            expected_sha256: expected,
1209            expected_result_sha256,
1210            snapshot_path,
1211            snapshot_sha256,
1212        } => {
1213            let bytes = bytes
1214                .as_deref()
1215                .expect("lifecycle changes require bounded source bytes");
1216            validate_object_record_path(object_record_path, &source)?;
1217            let mut document = parse_structural_json(&source, bytes)?;
1218            set_object_lifecycle(&source, &mut document, "archived", None)?;
1219            validate_archive_lifecycle(&source, &document)?;
1220            let result = pretty_json_bytes(&source, &document)?;
1221            *expected = expected_sha256;
1222            *expected_result_sha256 = sha256_bytes(&result);
1223            *snapshot_path = None;
1224            *snapshot_sha256 = None;
1225        }
1226        MigrationOperation::MarkSuperseded {
1227            object_record_path,
1228            superseded_by,
1229            expected_sha256: expected,
1230            expected_result_sha256,
1231            snapshot_path,
1232            snapshot_sha256,
1233        } => {
1234            let bytes = bytes
1235                .as_deref()
1236                .expect("lifecycle changes require bounded source bytes");
1237            validate_object_record_path(object_record_path, &source)?;
1238            validate_object_id(&source, superseded_by)?;
1239            let mut document = parse_structural_json(&source, bytes)?;
1240            set_object_lifecycle(
1241                &source,
1242                &mut document,
1243                "superseded",
1244                Some(superseded_by.as_str()),
1245            )?;
1246            let result = pretty_json_bytes(&source, &document)?;
1247            *expected = expected_sha256;
1248            *expected_result_sha256 = sha256_bytes(&result);
1249            *snapshot_path = None;
1250            *snapshot_sha256 = None;
1251        }
1252        MigrationOperation::AddRelationship {
1253            object_record_path,
1254            relationship_type,
1255            target_object_id,
1256            expected_sha256: expected,
1257            expected_result_sha256,
1258            snapshot_path,
1259            snapshot_sha256,
1260        } => {
1261            let bytes = bytes
1262                .as_deref()
1263                .expect("relationship changes require bounded source bytes");
1264            validate_object_record_path(object_record_path, &source)?;
1265            if !is_lowercase_protocol_token(relationship_type) {
1266                return Err(FolderbaseError::InvalidRecord {
1267                    path: source,
1268                    message: "relationship type must be lowercase snake_case".to_owned(),
1269                });
1270            }
1271            validate_object_id(&source, target_object_id)?;
1272            let mut document = parse_structural_json(&source, bytes)?;
1273            let object =
1274                document
1275                    .as_object_mut()
1276                    .ok_or_else(|| FolderbaseError::InvalidRecord {
1277                        path: source.clone(),
1278                        message: "object record must be a JSON object".to_owned(),
1279                    })?;
1280            let relationships = object
1281                .entry("relationships")
1282                .or_insert_with(|| serde_json::Value::Array(Vec::new()))
1283                .as_array_mut()
1284                .ok_or_else(|| FolderbaseError::InvalidRecord {
1285                    path: source.clone(),
1286                    message: "object relationships must be an array".to_owned(),
1287                })?;
1288            let relationship = serde_json::json!({
1289                "type": relationship_type,
1290                "target": target_object_id,
1291            });
1292            if !relationships.contains(&relationship) {
1293                relationships.push(relationship);
1294            }
1295            let result = pretty_json_bytes(&source, &document)?;
1296            *expected = expected_sha256;
1297            *expected_result_sha256 = sha256_bytes(&result);
1298            *snapshot_path = None;
1299            *snapshot_sha256 = None;
1300        }
1301        MigrationOperation::CreateFolder { .. } | MigrationOperation::CopyFile { .. } => {
1302            unreachable!("additive operations are rejected before structural enrichment")
1303        }
1304    }
1305    Ok(())
1306}
1307
1308fn read_bounded_regular(path: &Path, maximum_bytes: u64) -> Result<Vec<u8>> {
1309    let metadata =
1310        fs::symlink_metadata(path).map_err(|source| FolderbaseError::io(path, source))?;
1311    if !metadata.is_file() || metadata.file_type().is_symlink() || metadata.len() > maximum_bytes {
1312        return Err(FolderbaseError::InvalidRecord {
1313            path: path.to_path_buf(),
1314            message: "structural source must be a bounded regular file".to_owned(),
1315        });
1316    }
1317    fs::read(path).map_err(|source| FolderbaseError::io(path, source))
1318}
1319
1320fn sha256_bytes(bytes: &[u8]) -> String {
1321    format!("{:x}", Sha256::digest(bytes))
1322}
1323
1324fn parse_structural_json(path: &Path, bytes: &[u8]) -> Result<serde_json::Value> {
1325    serde_json::from_slice(bytes).map_err(|source| FolderbaseError::json(path, source))
1326}
1327
1328fn pretty_json_bytes(path: &Path, value: &serde_json::Value) -> Result<Vec<u8>> {
1329    let mut bytes =
1330        serde_json::to_vec_pretty(value).map_err(|source| FolderbaseError::json(path, source))?;
1331    bytes.push(b'\n');
1332    Ok(bytes)
1333}
1334
1335fn structural_folderbase_kind_name(kind: FolderbaseKind) -> &'static str {
1336    match kind {
1337        FolderbaseKind::Person => "person",
1338        FolderbaseKind::Organization => "organization",
1339        FolderbaseKind::Engagement => "engagement",
1340        FolderbaseKind::Project => "project",
1341        FolderbaseKind::Customer => "customer",
1342        FolderbaseKind::Temporary => "temporary",
1343        FolderbaseKind::Custom => "custom",
1344    }
1345}
1346
1347fn validate_object_record_path(path: &Path, absolute: &Path) -> Result<()> {
1348    if !path.starts_with(".folderbase/objects")
1349        || path.extension().and_then(|extension| extension.to_str()) != Some("json")
1350    {
1351        return Err(FolderbaseError::InvalidRecord {
1352            path: absolute.to_path_buf(),
1353            message: "lifecycle and relationship changes require an object record".to_owned(),
1354        });
1355    }
1356    Ok(())
1357}
1358
1359fn validate_object_id(path: &Path, object_id: &str) -> Result<()> {
1360    if object_id
1361        .strip_prefix("obj_")
1362        .is_none_or(|value| Uuid::parse_str(value).is_err())
1363    {
1364        return Err(FolderbaseError::InvalidRecord {
1365            path: path.to_path_buf(),
1366            message: "object identifier is invalid".to_owned(),
1367        });
1368    }
1369    Ok(())
1370}
1371
1372fn is_lowercase_protocol_token(value: &str) -> bool {
1373    value
1374        .chars()
1375        .next()
1376        .is_some_and(|first| first.is_ascii_lowercase())
1377        && value
1378            .chars()
1379            .all(|character| character.is_ascii_lowercase() || character == '_')
1380}
1381
1382fn set_object_lifecycle(
1383    path: &Path,
1384    document: &mut serde_json::Value,
1385    status: &str,
1386    superseded_by: Option<&str>,
1387) -> Result<()> {
1388    let object = document
1389        .as_object_mut()
1390        .ok_or_else(|| FolderbaseError::InvalidRecord {
1391            path: path.to_path_buf(),
1392            message: "object record must be a JSON object".to_owned(),
1393        })?;
1394    let lifecycle = object
1395        .entry("lifecycle")
1396        .or_insert_with(|| serde_json::json!({}))
1397        .as_object_mut()
1398        .ok_or_else(|| FolderbaseError::InvalidRecord {
1399            path: path.to_path_buf(),
1400            message: "object lifecycle must be an object".to_owned(),
1401        })?;
1402    lifecycle.insert(
1403        "status".to_owned(),
1404        serde_json::Value::String(status.to_owned()),
1405    );
1406    if let Some(replacement) = superseded_by {
1407        lifecycle.insert(
1408            "superseded_by".to_owned(),
1409            serde_json::Value::String(replacement.to_owned()),
1410        );
1411    } else {
1412        lifecycle.remove("superseded_by");
1413    }
1414    Ok(())
1415}
1416
1417fn validate_archive_lifecycle(path: &Path, document: &serde_json::Value) -> Result<()> {
1418    let lifecycle = document
1419        .get("lifecycle")
1420        .and_then(serde_json::Value::as_object)
1421        .ok_or_else(|| FolderbaseError::InvalidRecord {
1422            path: path.to_path_buf(),
1423            message: "archived object requires lifecycle metadata".to_owned(),
1424        })?;
1425    if ["remote_size", "expected_restore_size"]
1426        .iter()
1427        .any(|field| !lifecycle.get(*field).is_some_and(serde_json::Value::is_u64))
1428    {
1429        return Err(FolderbaseError::InvalidRecord {
1430            path: path.to_path_buf(),
1431            message: "archiving requires remote_size and expected_restore_size recovery metadata"
1432                .to_owned(),
1433        });
1434    }
1435    Ok(())
1436}
1437
1438fn merge_managed_block(current: &str, body: &str, path: &Path) -> Result<String> {
1439    validate_managed_block_body(body, path)?;
1440    let managed = format!(
1441        "{MANAGED_BLOCK_BEGIN}\n{}\n{MANAGED_BLOCK_END}",
1442        body.trim_end()
1443    );
1444    let begins = current
1445        .match_indices(MANAGED_BLOCK_BEGIN)
1446        .collect::<Vec<_>>();
1447    let ends = current.match_indices(MANAGED_BLOCK_END).collect::<Vec<_>>();
1448    match (begins.as_slice(), ends.as_slice()) {
1449        ([], []) => {
1450            let separator = if current.is_empty() || current.ends_with("\n\n") {
1451                ""
1452            } else if current.ends_with('\n') {
1453                "\n"
1454            } else {
1455                "\n\n"
1456            };
1457            Ok(format!("{current}{separator}{managed}\n"))
1458        }
1459        ([(begin, _)], [(end, _)]) if begin < end => {
1460            let after = end + MANAGED_BLOCK_END.len();
1461            Ok(format!(
1462                "{}{}{}",
1463                &current[..*begin],
1464                managed,
1465                &current[after..]
1466            ))
1467        }
1468        _ => Err(FolderbaseError::InvalidRecord {
1469            path: path.to_path_buf(),
1470            message: "adapter contains ambiguous Folderbase managed blocks".to_owned(),
1471        }),
1472    }
1473}
1474
1475pub(crate) fn validate_managed_block_body(body: &str, path: &Path) -> Result<()> {
1476    if body.contains(MANAGED_BLOCK_BEGIN)
1477        || body.contains(MANAGED_BLOCK_END)
1478        || body.len() as u64 > MAX_STRUCTURAL_TEXT_BYTES
1479        || body.contains('\0')
1480    {
1481        return Err(FolderbaseError::InvalidRecord {
1482            path: path.to_path_buf(),
1483            message: "managed adapter body is invalid".to_owned(),
1484        });
1485    }
1486    Ok(())
1487}
1488
1489pub(crate) fn validate_managed_block_body_syntax(body: &str, path: &Path) -> Result<()> {
1490    if body.contains("<!-- folderbase:") || body.contains('\0') {
1491        return Err(FolderbaseError::InvalidRecord {
1492            path: path.to_path_buf(),
1493            message: "managed adapter body is invalid".to_owned(),
1494        });
1495    }
1496    Ok(())
1497}
1498
1499fn validate_typed_ignore_policy_update(
1500    root: &Path,
1501    path: &Path,
1502    content: &str,
1503    error_path: &Path,
1504) -> Result<()> {
1505    if path != Path::new(".folderbaseignore") || content.contains('\0') {
1506        return Err(FolderbaseError::InvalidRecord {
1507            path: error_path.to_path_buf(),
1508            message: "ignore policy must be capture-compatible UTF-8 for .folderbaseignore"
1509                .to_owned(),
1510        });
1511    }
1512    validate_folderbaseignore_content(root, content).map_err(|error| {
1513        FolderbaseError::InvalidRecord {
1514            path: error_path.to_path_buf(),
1515            message: format!("ignore policy is not capture-compatible: {error}"),
1516        }
1517    })
1518}
1519
1520fn validate_typed_ignore_policy_updates(plan: &MigrationPlan) -> Result<()> {
1521    for operation in &plan.operations {
1522        if let MigrationOperation::UpdateIgnorePolicy { path, content, .. } = operation {
1523            let source = safe_join(&plan.root, path)?;
1524            validate_typed_ignore_policy_update(&plan.root, path, content, &source)?;
1525        }
1526    }
1527    Ok(())
1528}
1529
1530#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1531pub struct MigrationExclusion {
1532    #[serde(with = "crate::portable_wire_path::relative")]
1533    pub path: PathBuf,
1534    pub reason: String,
1535}
1536
1537#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1538pub struct MigrationPreview {
1539    pub migration_id: String,
1540    pub targets: Vec<MigrationTarget>,
1541    #[serde(with = "crate::portable_wire_path::relative::vec")]
1542    pub creates_directories: Vec<PathBuf>,
1543    pub copies: Vec<MigrationCopyPreview>,
1544    pub source_bytes: u64,
1545    pub additional_local_bytes: u64,
1546    pub source_files_remain: bool,
1547    #[serde(default)]
1548    pub structural_operations: Vec<MigrationOperation>,
1549}
1550
1551#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1552pub struct MigrationCopyPreview {
1553    #[serde(with = "crate::portable_wire_path::relative")]
1554    pub source_path: PathBuf,
1555    #[serde(with = "crate::portable_wire_path::relative")]
1556    pub destination_path: PathBuf,
1557    pub bytes: u64,
1558}
1559
1560/// An approval token tied to a specific immutable plan digest.
1561#[derive(Debug)]
1562pub struct ApprovedMigration {
1563    plan: MigrationPlan,
1564    approval_digest: String,
1565}
1566
1567impl ApprovedMigration {
1568    /// Return the digest which binds this token to its immutable approved plan.
1569    pub fn approval_digest(&self) -> &str {
1570        &self.approval_digest
1571    }
1572
1573    /// Reopen an approved durable plan as an apply-capable token.
1574    pub fn reopen(root: impl AsRef<Path>, migration_id: &str) -> Result<Self> {
1575        let plan = MigrationPlan::reopen(root, migration_id)?;
1576        require_state(plan.state, MigrationState::Approved)?;
1577        let approval_digest = plan
1578            .approval_digest
1579            .clone()
1580            .ok_or(FolderbaseError::MigrationApprovalMismatch)?;
1581        if plan_digest(&plan)? != approval_digest {
1582            return Err(FolderbaseError::MigrationApprovalMismatch);
1583        }
1584        Ok(Self {
1585            plan,
1586            approval_digest,
1587        })
1588    }
1589}
1590
1591#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1592pub struct MigrationResult {
1593    pub migration_id: String,
1594    #[serde(with = "crate::portable_wire_path::display")]
1595    pub root: PathBuf,
1596    pub state: MigrationState,
1597    #[serde(with = "crate::portable_wire_path::relative::vec")]
1598    pub created_paths: Vec<PathBuf>,
1599    #[serde(with = "crate::portable_wire_path::relative")]
1600    pub journal_path: PathBuf,
1601}
1602
1603#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1604pub struct RollbackResult {
1605    pub migration_id: String,
1606    #[serde(with = "crate::portable_wire_path::relative::vec")]
1607    pub removed_paths: Vec<PathBuf>,
1608    pub state: MigrationState,
1609}
1610
1611/// The caller-selected Folderbase root for one migration command.
1612///
1613/// `Current` is the public command boundary. The approval-carrying variant is
1614/// used only by the released `apply_migration` adapter so its already-retained
1615/// root authority is not weakened while that adapter moves behind
1616/// `MigrationExecution`.
1617#[derive(Debug)]
1618#[allow(clippy::large_enum_variant)]
1619pub enum RootClaim<'a> {
1620    Current {
1621        display_root: &'a Path,
1622    },
1623    #[doc(hidden)]
1624    Approved {
1625        approved_migration: ApprovedMigration,
1626    },
1627}
1628
1629#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1630pub enum MigrationCommand<'a> {
1631    Apply {
1632        migration_id: &'a str,
1633        approval_digest: &'a str,
1634    },
1635    Recover {
1636        migration_id: &'a str,
1637    },
1638    Rollback {
1639        migration_id: &'a str,
1640    },
1641}
1642
1643#[derive(Debug, Clone, Copy, Serialize, PartialEq, Eq)]
1644#[serde(rename_all = "snake_case")]
1645#[non_exhaustive]
1646pub enum MigrationConflictDirection {
1647    Apply,
1648    Rollback,
1649    /// A released legacy result recorded a conflict without durably recording
1650    /// which execution direction produced it.
1651    LegacyUnknown,
1652}
1653
1654#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
1655#[non_exhaustive]
1656pub struct MigrationConflict {
1657    pub operation_index: Option<usize>,
1658    #[serde(with = "crate::portable_wire_path::relative::vec")]
1659    pub affected_paths: Vec<PathBuf>,
1660    pub expected: String,
1661    pub observed: String,
1662    pub phase: String,
1663    pub direction: MigrationConflictDirection,
1664    #[serde(with = "crate::portable_wire_path::relative::option")]
1665    pub preserved_artifact: Option<PathBuf>,
1666}
1667
1668#[derive(Debug, Serialize)]
1669#[non_exhaustive]
1670pub enum MigrationOutcome {
1671    Applied(MigrationResult),
1672    RolledBack(RollbackResult),
1673    Conflicted {
1674        migration_id: String,
1675        conflicts: Vec<MigrationConflict>,
1676    },
1677    RecoveryRequired {
1678        migration_id: String,
1679        work: String,
1680    },
1681}
1682
1683#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1684enum ExecutionFormat {
1685    None,
1686    PrePreparedTransactionV1,
1687    TransactionV1,
1688    LegacyResult,
1689}
1690
1691/// The single semantic execution boundary for apply, recovery, and rollback.
1692pub struct MigrationExecution;
1693
1694impl MigrationExecution {
1695    pub fn run(root: RootClaim<'_>, command: MigrationCommand<'_>) -> Result<MigrationOutcome> {
1696        let migration_id = migration_command_id(command).to_owned();
1697        match Self::run_inner(root, command) {
1698            Err(FolderbaseError::RecoveryRequired { work }) => {
1699                Ok(MigrationOutcome::RecoveryRequired { migration_id, work })
1700            }
1701            result => result,
1702        }
1703    }
1704
1705    fn run_inner(root: RootClaim<'_>, command: MigrationCommand<'_>) -> Result<MigrationOutcome> {
1706        match (root, command) {
1707            (
1708                RootClaim::Current { display_root },
1709                MigrationCommand::Apply {
1710                    migration_id,
1711                    approval_digest,
1712                },
1713            ) => run_current_transaction_v1_apply_with_hooks(
1714                display_root,
1715                migration_id,
1716                approval_digest,
1717                || {},
1718                |_| {},
1719                |_| {},
1720            ),
1721            (
1722                RootClaim::Approved { approved_migration },
1723                MigrationCommand::Apply {
1724                    migration_id,
1725                    approval_digest,
1726                },
1727            ) => {
1728                if approved_migration.plan.id != migration_id
1729                    || approved_migration.approval_digest != approval_digest
1730                {
1731                    return Err(FolderbaseError::MigrationApprovalMismatch);
1732                }
1733                apply_transaction_v1_migration_outcome_with_hook(approved_migration, |_| {})
1734            }
1735            (RootClaim::Current { display_root }, MigrationCommand::Recover { migration_id }) => {
1736                run_current_migration_command_with_hooks(
1737                    display_root,
1738                    MigrationCommand::Recover { migration_id },
1739                    || {},
1740                    |_| {},
1741                )
1742            }
1743            (RootClaim::Current { display_root }, MigrationCommand::Rollback { migration_id }) => {
1744                run_current_migration_command_with_hooks(
1745                    display_root,
1746                    MigrationCommand::Rollback { migration_id },
1747                    || {},
1748                    |_| {},
1749                )
1750            }
1751            (
1752                RootClaim::Approved { .. },
1753                MigrationCommand::Recover { .. } | MigrationCommand::Rollback { .. },
1754            ) => Err(FolderbaseError::InvalidMigrationState {
1755                expected: "current_root_claim",
1756                actual: "approved_root_claim".to_owned(),
1757            }),
1758        }
1759    }
1760}
1761
1762#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1763struct SourceFile {
1764    #[serde(with = "crate::portable_wire_path::relative")]
1765    path: PathBuf,
1766    bytes: u64,
1767    sha256: String,
1768}
1769
1770#[derive(Debug, Clone, Serialize, Deserialize)]
1771struct MigrationJournal {
1772    protocol_version: String,
1773    id: String,
1774    #[serde(with = "crate::portable_wire_path::display")]
1775    root: PathBuf,
1776    state: MigrationState,
1777    approval_digest: String,
1778    #[serde(default, skip_serializing_if = "Option::is_none")]
1779    approval_scheme: Option<String>,
1780    source_inventory: SourceInventory,
1781    answers: Vec<MigrationAnswer>,
1782    #[serde(default)]
1783    template_references: Vec<String>,
1784    #[serde(default)]
1785    targets: Vec<MigrationTarget>,
1786    operations: Vec<MigrationOperation>,
1787    exclusions: Vec<MigrationExclusion>,
1788    #[serde(default)]
1789    plan_extensions: BTreeMap<String, serde_json::Value>,
1790    #[serde(default)]
1791    materialized_folderbases: Vec<MaterializedFolderbase>,
1792    #[serde(default)]
1793    materialized_workspace: Option<MaterializedWorkspace>,
1794    #[serde(with = "crate::portable_wire_path::relative::vec")]
1795    created_paths: Vec<PathBuf>,
1796    completed_operations: usize,
1797    in_flight_operation: Option<usize>,
1798    #[serde(default, skip_serializing_if = "Option::is_none")]
1799    transaction_program_digest: Option<String>,
1800    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1801    operation_precondition_identities: Vec<Option<String>>,
1802    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1803    operation_result_identities: Vec<Option<String>>,
1804}
1805
1806#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1807struct SourceInventory {
1808    algorithm: String,
1809    digest: String,
1810    #[serde(default)]
1811    files: Vec<SourceFile>,
1812}
1813
1814#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1815struct SourceTopologySnapshot {
1816    version: String,
1817    #[serde(with = "crate::portable_wire_path::relative::vec")]
1818    files: Vec<PathBuf>,
1819    #[serde(with = "crate::portable_wire_path::relative::vec")]
1820    reconstructable_trees: Vec<PathBuf>,
1821    nested_folderbases: Vec<NestedFolderbaseBoundary>,
1822}
1823
1824#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1825struct MaterializedFolderbase {
1826    target_id: String,
1827    #[serde(with = "crate::portable_wire_path::relative")]
1828    path: PathBuf,
1829    folderbase_id: String,
1830    name: String,
1831    template_reference: String,
1832    state: MaterializationState,
1833    #[serde(with = "crate::portable_wire_path::relative::vec")]
1834    created_directories: Vec<PathBuf>,
1835    #[serde(with = "crate::portable_wire_path::relative::map")]
1836    created_files: BTreeMap<PathBuf, String>,
1837}
1838
1839#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
1840#[serde(rename_all = "snake_case")]
1841enum MaterializationState {
1842    Planned,
1843    Verified,
1844}
1845
1846#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1847struct MaterializedWorkspace {
1848    #[serde(with = "crate::portable_wire_path::relative")]
1849    path: PathBuf,
1850    workspace_id: String,
1851    name: String,
1852    state: MaterializationState,
1853    folderbases: Vec<WorkspaceFolderbaseLink>,
1854    #[serde(with = "crate::portable_wire_path::relative::map")]
1855    created_files: BTreeMap<PathBuf, String>,
1856}
1857
1858#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1859struct WorkspaceFolderbaseLink {
1860    folderbase_id: String,
1861    label: String,
1862    #[serde(with = "crate::portable_wire_path::relative")]
1863    path: PathBuf,
1864}
1865
1866#[derive(Debug, Clone, PartialEq, Eq)]
1867struct FolderbaseMaterializationSpec {
1868    target_id: String,
1869    name: String,
1870    path: PathBuf,
1871}
1872
1873#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1874enum CanonicalScopeAnswer {
1875    OneFolderbase,
1876    ProposedBoundaries,
1877}
1878
1879#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1880enum GeneratedContentAnswer {
1881    Exclude,
1882    Include,
1883}
1884
1885#[derive(Debug, Clone, PartialEq, Eq)]
1886struct ParsedMigrationAnswers {
1887    canonical_scope: CanonicalScopeAnswer,
1888    generated_content: GeneratedContentAnswer,
1889    assignments: BTreeMap<PathBuf, ParsedAssignment>,
1890    grouped_assignments: Vec<GroupedAssignmentContract>,
1891}
1892
1893#[derive(Debug, Clone, PartialEq, Eq)]
1894struct ParsedAssignment {
1895    content_kind: MigrationContentKind,
1896    target_id: String,
1897}
1898
1899#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
1900#[serde(rename_all = "snake_case")]
1901enum AssignmentSourceKind {
1902    #[serde(rename = "regular_file")]
1903    File,
1904    ReconstructableTree,
1905}
1906
1907#[derive(Debug, Clone, PartialEq, Eq)]
1908struct AssignmentGroupMember {
1909    path: PathBuf,
1910    kind: AssignmentSourceKind,
1911}
1912
1913#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1914struct GroupedAssignmentContract {
1915    question_id: String,
1916    rule_version: String,
1917    #[serde(with = "crate::portable_wire_path::relative_or_current")]
1918    source_root: PathBuf,
1919    members: Vec<GroupedAssignmentMemberContract>,
1920    content_kind: MigrationContentKind,
1921    coverage_digest: String,
1922    default_target_id: String,
1923    exceptions: Vec<MigrationAnswerException>,
1924}
1925
1926#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1927struct GroupedAssignmentMemberContract {
1928    #[serde(with = "crate::portable_wire_path::relative")]
1929    source_path: PathBuf,
1930    source_kind: AssignmentSourceKind,
1931}
1932
1933#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1934struct GroupedAssignmentsExtension {
1935    version: String,
1936    groups: Vec<GroupedAssignmentContract>,
1937}
1938
1939#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1940struct ExpandedReconstructableTreesExtension {
1941    version: String,
1942    trees: Vec<ExpandedReconstructableTreeMembership>,
1943}
1944
1945#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1946struct ExpandedReconstructableTreeMembership {
1947    #[serde(with = "crate::portable_wire_path::relative")]
1948    source_root: PathBuf,
1949    #[serde(with = "crate::portable_wire_path::relative::vec")]
1950    source_paths: Vec<PathBuf>,
1951}
1952
1953impl ParsedMigrationAnswers {
1954    fn assignment_for(&self, path: &Path) -> Option<&ParsedAssignment> {
1955        self.assignments.get(path)
1956    }
1957}
1958
1959/// Analyze a folder without changing it.
1960pub fn analyze_migration(root: impl AsRef<Path>) -> Result<MigrationAnalysis> {
1961    let root = canonical_root(root.as_ref())?;
1962    let root_identity = RetainedPhysicalIdentity::from_path(&root)
1963        .map_err(|source| FolderbaseError::io(&root, source))?;
1964    let folder = analyze_folder(&root)?;
1965    let files = folder.files;
1966    let mut proposed_boundaries = folder
1967        .boundary_hints
1968        .iter()
1969        .filter(|hint| {
1970            hint.kind == "permission" && hint.path.components().count() == 1
1971        })
1972        .map(|hint| {
1973            let name = hint.path.to_string_lossy();
1974            ProposedBoundary {
1975                path: hint.path.clone(),
1976                suggested_name: humanize_name(&name),
1977                reason: "Top-level content suggests a distinct project, client, commercial, or restricted scope.".to_owned(),
1978            }
1979        })
1980        .collect::<Vec<_>>();
1981    proposed_boundaries.sort_by(|left, right| left.path.cmp(&right.path));
1982    proposed_boundaries.dedup_by(|left, right| left.path == right.path);
1983    let mut proposed_targets = vec![
1984        MigrationTarget {
1985            id: "target_primary_folderbase".to_owned(),
1986            kind: MigrationTargetKind::Folderbase,
1987            path: PathBuf::from("."),
1988            suggested_name: root
1989                .file_name()
1990                .and_then(|name| name.to_str())
1991                .map(humanize_name)
1992                .unwrap_or_else(|| "Primary Folderbase".to_owned()),
1993            reason: "The ordinary folder can remain one explicit folderbase boundary.".to_owned(),
1994        },
1995        MigrationTarget {
1996            id: "target_retained_source".to_owned(),
1997            kind: MigrationTargetKind::RetainedFolder,
1998            path: PathBuf::from("."),
1999            suggested_name: "Retained source folder".to_owned(),
2000            reason: "Content may remain in the unmanaged source without being copied.".to_owned(),
2001        },
2002        MigrationTarget {
2003            id: "target_exclusion".to_owned(),
2004            kind: MigrationTargetKind::Exclusion,
2005            path: PathBuf::from("."),
2006            suggested_name: "Explicit exclusion".to_owned(),
2007            reason: "Content is left in the source and recorded as excluded from the proposal."
2008                .to_owned(),
2009        },
2010    ];
2011    for boundary in &proposed_boundaries {
2012        let suggested_kind = target_kind_for_boundary(&boundary.path);
2013        let suggested_prefix = match suggested_kind {
2014            MigrationTargetKind::Folderbase => "target_folderbase",
2015            MigrationTargetKind::Workspace => "target_workspace",
2016            MigrationTargetKind::ScopedView => "target_scoped_view",
2017            MigrationTargetKind::RetainedFolder | MigrationTargetKind::Exclusion => unreachable!(),
2018        };
2019        proposed_targets.push(MigrationTarget {
2020            id: stable_path_id(suggested_prefix, &boundary.path)?,
2021            kind: suggested_kind,
2022            path: boundary.path.clone(),
2023            suggested_name: boundary.suggested_name.clone(),
2024            reason: boundary.reason.clone(),
2025        });
2026        if suggested_kind != MigrationTargetKind::Folderbase {
2027            proposed_targets.push(MigrationTarget {
2028                id: stable_path_id("target_folderbase", &boundary.path)?,
2029                kind: MigrationTargetKind::Folderbase,
2030                path: boundary.path.clone(),
2031                suggested_name: boundary.suggested_name.clone(),
2032                reason: "Explicit alternative if the user confirms this folder needs its own durable permission boundary."
2033                    .to_owned(),
2034            });
2035        }
2036    }
2037    if proposed_targets
2038        .iter()
2039        .any(|target| target.kind == MigrationTargetKind::ScopedView)
2040        || proposed_targets
2041            .iter()
2042            .filter(|target| target.kind == MigrationTargetKind::Folderbase)
2043            .count()
2044            > 1
2045    {
2046        proposed_targets.push(MigrationTarget {
2047            id: "target_workspace".to_owned(),
2048            kind: MigrationTargetKind::Workspace,
2049            path: PathBuf::from("."),
2050            suggested_name: "Migration workspace".to_owned(),
2051            reason:
2052                "A workspace may compose approved folderbases and scoped views but never owns content."
2053                    .to_owned(),
2054        });
2055    }
2056    let inventory_digest = metadata_inventory_digest(
2057        &files,
2058        &folder.reconstructable_trees,
2059        &folder.nested_folderbases,
2060    )?;
2061    let total_bytes = folder.inventory.total_bytes;
2062    let captured_at = fs::metadata(&root)
2063        .and_then(|metadata| metadata.modified())
2064        .map(DateTime::<Utc>::from)
2065        .map_err(|source| FolderbaseError::io(&root, source))?;
2066
2067    let mut questions = vec![
2068        MigrationQuestion {
2069            id: "question_canonical_scope".to_owned(),
2070            prompt: "Choose `one_folderbase` or `proposed_boundaries`.".to_owned(),
2071            context: "A proposed-boundaries plan stages each detected boundary as an independent folderbase-shaped root; folder nesting alone never grants access.".to_owned(),
2072            kind: MigrationQuestionKind::Decision,
2073            options: vec![
2074                MigrationOption {
2075                    id: "one_folderbase".to_owned(),
2076                    label: "One folderbase".to_owned(),
2077                    consequence: "Keep included canonical content under one permission boundary."
2078                        .to_owned(),
2079                },
2080                MigrationOption {
2081                    id: "proposed_boundaries".to_owned(),
2082                    label: "Review proposed boundaries".to_owned(),
2083                    consequence: "Stage only explicitly assigned folderbase targets as independent permission boundaries."
2084                        .to_owned(),
2085                },
2086            ],
2087            recommended_option_id: "one_folderbase".to_owned(),
2088        },
2089        MigrationQuestion {
2090            id: "question_generated_content".to_owned(),
2091            prompt: "Choose `exclude_generated` or `include_generated`.".to_owned(),
2092            context: "Dependencies such as node_modules should normally be reconstructed, while final generated deliverables may be canonical evidence worth including.".to_owned(),
2093            kind: MigrationQuestionKind::Decision,
2094            options: vec![
2095                MigrationOption {
2096                    id: "exclude_generated".to_owned(),
2097                    label: "Keep generated content out of the migration".to_owned(),
2098                    consequence: "Leave reconstructable trees in the source and record the exclusion in the proposal."
2099                        .to_owned(),
2100                },
2101                MigrationOption {
2102                    id: "include_generated".to_owned(),
2103                    label: "Include generated content".to_owned(),
2104                    consequence: "Expand reconstructable trees during planning and assign their files to an approved destination."
2105                        .to_owned(),
2106                },
2107            ],
2108            recommended_option_id: "exclude_generated".to_owned(),
2109        },
2110    ];
2111    if files.iter().any(AnalyzedFile::is_secret_shaped) {
2112        questions.push(MigrationQuestion {
2113            id: "question_secrets".to_owned(),
2114            prompt: "Secret-shaped files were detected. Confirm `local_only`.".to_owned(),
2115            context: "Folderbase never assumes a secret-shaped file is safe to copy into a shareable folderbase.".to_owned(),
2116            kind: MigrationQuestionKind::Decision,
2117            options: vec![MigrationOption {
2118                id: "local_only".to_owned(),
2119                label: "Keep secret-shaped content local".to_owned(),
2120                consequence:
2121                    "Retain secret-shaped files in the source and exclude them from the migration."
2122                        .to_owned(),
2123            }],
2124            recommended_option_id: "local_only".to_owned(),
2125        });
2126    }
2127    questions.extend(assignment_questions(
2128        &files,
2129        &folder.reconstructable_trees,
2130        &proposed_targets,
2131    )?);
2132
2133    Ok(MigrationAnalysis {
2134        id: format!("analysis_{inventory_digest}"),
2135        root,
2136        captured_at,
2137        inventory_digest,
2138        file_count: files.len() as u64,
2139        total_bytes,
2140        questions,
2141        proposed_boundaries,
2142        proposed_targets,
2143        reconstructable_trees: folder.reconstructable_trees,
2144        nested_folderbases: folder.nested_folderbases,
2145        files,
2146        root_identity: Some(root_identity),
2147    })
2148}
2149
2150/// Turn a read-only analysis and founder answers into an explicit proposal.
2151///
2152/// The initial engine is deliberately conservative: generated and
2153/// secret-shaped content is excluded, while canonical source content may be
2154/// copied into a user-selected staging folder. Source bytes are never removed.
2155pub fn plan_migration(
2156    analysis: MigrationAnalysis,
2157    answers: Vec<MigrationAnswer>,
2158    destination_folder: impl AsRef<Path>,
2159) -> Result<MigrationPlan> {
2160    let destination_folder = destination_folder.as_ref().to_path_buf();
2161    ensure_safe_relative(&destination_folder)?;
2162    let current_root = PhysicalIdentity::from_path(&analysis.root)
2163        .map_err(|source| FolderbaseError::io(&analysis.root, source))?;
2164    if analysis.root_identity.as_ref().map(|root| root.identity()) != Some(current_root) {
2165        return Err(FolderbaseError::MigrationSourceChanged(
2166            analysis.root.clone(),
2167        ));
2168    }
2169    let refreshed = analyze_folder(&analysis.root)?;
2170    let refreshed_digest = metadata_inventory_digest(
2171        &refreshed.files,
2172        &refreshed.reconstructable_trees,
2173        &refreshed.nested_folderbases,
2174    )?;
2175    if refreshed_digest != analysis.inventory_digest {
2176        return Err(FolderbaseError::MigrationSourceChanged(
2177            analysis.root.clone(),
2178        ));
2179    }
2180    let parsed_answers = validate_answers(&analysis, &answers)?;
2181
2182    let mut operations = vec![MigrationOperation::CreateFolder {
2183        path: destination_folder.clone(),
2184    }];
2185    let mut exclusions = Vec::new();
2186    let mut target_destinations = BTreeMap::new();
2187    let mut target_destination_keys = BTreeSet::new();
2188    let mut source_files = Vec::new();
2189    let mut candidate_files = analysis.files.clone();
2190    let mut expanded_tree_assignments = BTreeMap::new();
2191    let mut expanded_tree_memberships = Vec::new();
2192    if parsed_answers.generated_content == GeneratedContentAnswer::Include {
2193        for tree in &analysis.reconstructable_trees {
2194            let assignment = parsed_answers.assignment_for(&tree.path).ok_or_else(|| {
2195                FolderbaseError::InvalidRecord {
2196                    path: analysis.root.clone(),
2197                    message: format!(
2198                        "missing explicit migration assignment for {}",
2199                        tree.path.display()
2200                    ),
2201                }
2202            })?;
2203            let target = analysis
2204                .proposed_targets
2205                .iter()
2206                .find(|target| target.id == assignment.target_id)
2207                .ok_or_else(|| FolderbaseError::InvalidRecord {
2208                    path: analysis.root.clone(),
2209                    message: format!("unknown migration target: {}", assignment.target_id),
2210                })?;
2211            if matches!(
2212                target.kind,
2213                MigrationTargetKind::Exclusion | MigrationTargetKind::RetainedFolder
2214            ) {
2215                exclusions.push(MigrationExclusion {
2216                    path: tree.path.clone(),
2217                    reason: "Explicit generated-content destination".to_owned(),
2218                });
2219                continue;
2220            }
2221            let absolute = safe_join(&analysis.root, &tree.path)?;
2222            let expanded = expand_reconstructable_tree(&absolute)?;
2223            if !expanded.nested_folderbases.is_empty() {
2224                return Err(FolderbaseError::InvalidRecord {
2225                    path: analysis.root.clone(),
2226                    message: format!(
2227                        "expanded generated tree {} contains an unreviewed nested folderbase boundary",
2228                        tree.path.display()
2229                    ),
2230                });
2231            }
2232            if expanded.files.iter().any(AnalyzedFile::is_secret_shaped) {
2233                return Err(FolderbaseError::InvalidRecord {
2234                    path: analysis.root.clone(),
2235                    message: format!(
2236                        "expanded generated tree {} contains secret-shaped content and requires a new explicit local policy",
2237                        tree.path.display()
2238                    ),
2239                });
2240            }
2241            let mut expanded_files = expanded
2242                .files
2243                .into_iter()
2244                .map(|mut file| {
2245                    file.path = tree.path.join(file.path);
2246                    expanded_tree_assignments.insert(file.path.clone(), assignment.clone());
2247                    file
2248                })
2249                .collect::<Vec<_>>();
2250            expanded_files.sort_by(|left, right| left.path.cmp(&right.path));
2251            expanded_tree_memberships.push(ExpandedReconstructableTreeMembership {
2252                source_root: tree.path.clone(),
2253                source_paths: expanded_files
2254                    .iter()
2255                    .map(|file| file.path.clone())
2256                    .collect(),
2257            });
2258            candidate_files.extend(expanded_files);
2259        }
2260        candidate_files.sort_by(|left, right| left.path.cmp(&right.path));
2261    } else {
2262        exclusions.extend(
2263            analysis
2264                .reconstructable_trees
2265                .iter()
2266                .map(|tree| MigrationExclusion {
2267                    path: tree.path.clone(),
2268                    reason: "Explicit generated or reconstructable exclusion".to_owned(),
2269                }),
2270        );
2271    }
2272
2273    if parsed_answers.canonical_scope == CanonicalScopeAnswer::ProposedBoundaries {
2274        let selected_folderbase_targets = parsed_answers
2275            .assignments
2276            .values()
2277            .filter_map(|assignment| {
2278                analysis
2279                    .proposed_targets
2280                    .iter()
2281                    .find(|target| {
2282                        target.id == assignment.target_id
2283                            && target.kind == MigrationTargetKind::Folderbase
2284                    })
2285                    .map(|target| target.id.as_str())
2286            })
2287            .collect::<BTreeSet<_>>();
2288        for target in analysis.proposed_targets.iter().filter(|target| {
2289            target.kind == MigrationTargetKind::Folderbase
2290                && selected_folderbase_targets.contains(target.id.as_str())
2291        }) {
2292            let folder_name = if target.id == "target_primary_folderbase" {
2293                "Primary.folderbase".to_owned()
2294            } else {
2295                format!("{}.folderbase", safe_boundary_name(&target.suggested_name))
2296            };
2297            let destination = destination_folder.join(folder_name);
2298            if !target_destination_keys.insert(portable_path_key(&destination)) {
2299                return Err(FolderbaseError::InvalidRecord {
2300                    path: analysis.root.clone(),
2301                    message: format!(
2302                        "multiple folderbase targets resolve to {}",
2303                        destination.display()
2304                    ),
2305                });
2306            }
2307            operations.push(MigrationOperation::CreateFolder {
2308                path: destination.clone(),
2309            });
2310            target_destinations.insert(target.id.clone(), destination);
2311        }
2312    }
2313
2314    let mut planned_destination_keys = BTreeSet::new();
2315    for file in &candidate_files {
2316        let assignment = parsed_answers
2317            .assignment_for(&file.path)
2318            .or_else(|| expanded_tree_assignments.get(&file.path))
2319            .ok_or_else(|| FolderbaseError::InvalidRecord {
2320                path: analysis.root.clone(),
2321                message: format!(
2322                    "missing explicit migration assignment for {}",
2323                    file.path.display()
2324                ),
2325            })?;
2326        let target = analysis
2327            .proposed_targets
2328            .iter()
2329            .find(|target| target.id == assignment.target_id)
2330            .ok_or_else(|| FolderbaseError::InvalidRecord {
2331                path: analysis.root.clone(),
2332                message: format!("unknown migration target: {}", assignment.target_id),
2333            })?;
2334        if file.is_secret_shaped() && target.kind != MigrationTargetKind::RetainedFolder {
2335            return Err(FolderbaseError::InvalidRecord {
2336                path: analysis.root.clone(),
2337                message: format!(
2338                    "secret-shaped content requires an explicit retained-local target: {}",
2339                    file.path.display()
2340                ),
2341            });
2342        }
2343        if file.is_generated()
2344            && parsed_answers.generated_content == GeneratedContentAnswer::Exclude
2345            && target.kind == MigrationTargetKind::Folderbase
2346        {
2347            return Err(FolderbaseError::InvalidRecord {
2348                path: analysis.root.clone(),
2349                message: format!(
2350                    "excluded generated content cannot target a folderbase: {}",
2351                    file.path.display()
2352                ),
2353            });
2354        }
2355        if matches!(
2356            target.kind,
2357            MigrationTargetKind::RetainedFolder | MigrationTargetKind::Exclusion
2358        ) {
2359            exclusions.push(MigrationExclusion {
2360                path: file.path.clone(),
2361                reason: match target.kind {
2362                    MigrationTargetKind::RetainedFolder => {
2363                        "Explicitly retained in the source folder".to_owned()
2364                    }
2365                    MigrationTargetKind::Exclusion => "Explicit migration exclusion".to_owned(),
2366                    _ => unreachable!(),
2367                },
2368            });
2369            continue;
2370        }
2371        if !matches!(target.kind, MigrationTargetKind::Folderbase) {
2372            return Err(FolderbaseError::InvalidRecord {
2373                path: analysis.root.clone(),
2374                message: format!("navigation target cannot own content: {}", target.id),
2375            });
2376        }
2377        let absolute = safe_join(&analysis.root, &file.path)?;
2378        let metadata = fs::symlink_metadata(&absolute)
2379            .map_err(|_| FolderbaseError::MigrationSourceChanged(file.path.clone()))?;
2380        if !metadata.is_file() || metadata.file_type().is_symlink() || metadata.len() != file.bytes
2381        {
2382            return Err(FolderbaseError::MigrationSourceChanged(file.path.clone()));
2383        }
2384        let source_file = SourceFile {
2385            path: file.path.clone(),
2386            bytes: file.bytes,
2387            sha256: sha256_path(&absolute)?,
2388        };
2389        let destination_path = match parsed_answers.canonical_scope {
2390            CanonicalScopeAnswer::OneFolderbase => destination_folder.join(&file.path),
2391            CanonicalScopeAnswer::ProposedBoundaries => {
2392                let destination = target_destinations.get(&target.id).ok_or_else(|| {
2393                    FolderbaseError::InvalidRecord {
2394                        path: analysis.root.clone(),
2395                        message: format!("folderbase target was not materialized: {}", target.id),
2396                    }
2397                })?;
2398                let relative = if target.id == "target_primary_folderbase" {
2399                    file.path.as_path()
2400                } else {
2401                    file.path
2402                        .strip_prefix(&target.path)
2403                        .unwrap_or(file.path.as_path())
2404                };
2405                destination.join(relative)
2406            }
2407        };
2408        let destination_key = portable_path_key(&destination_path);
2409        if planned_destination_keys.iter().any(|existing: &PathBuf| {
2410            destination_key.starts_with(existing) || existing.starts_with(&destination_key)
2411        }) {
2412            return Err(FolderbaseError::InvalidRecord {
2413                path: analysis.root.clone(),
2414                message: format!(
2415                    "multiple source objects resolve to {}",
2416                    destination_path.display()
2417                ),
2418            });
2419        }
2420        planned_destination_keys.insert(destination_key);
2421        operations.push(MigrationOperation::CopyFile {
2422            source_path: file.path.clone(),
2423            destination_path,
2424            expected_sha256: source_file.sha256.clone(),
2425        });
2426        source_files.push(source_file);
2427    }
2428
2429    let destination_roots = additive_destination_roots(&operations);
2430    let source_topology = source_topology_snapshot(
2431        &analysis.files,
2432        &analysis.reconstructable_trees,
2433        &analysis.nested_folderbases,
2434        &destination_roots,
2435    );
2436    let mut extensions = BTreeMap::new();
2437    extensions.insert(
2438        SOURCE_TOPOLOGY_EXTENSION.to_owned(),
2439        serde_json::to_value(source_topology)
2440            .map_err(|source| FolderbaseError::json(&analysis.root, source))?,
2441    );
2442    if !parsed_answers.grouped_assignments.is_empty() {
2443        extensions.insert(
2444            GROUPED_ASSIGNMENTS_EXTENSION.to_owned(),
2445            serde_json::to_value(GroupedAssignmentsExtension {
2446                version: "1".to_owned(),
2447                groups: parsed_answers.grouped_assignments.clone(),
2448            })
2449            .map_err(|source| FolderbaseError::json(&analysis.root, source))?,
2450        );
2451    }
2452    if !expanded_tree_memberships.is_empty() {
2453        extensions.insert(
2454            EXPANDED_RECONSTRUCTABLE_TREES_EXTENSION.to_owned(),
2455            serde_json::to_value(ExpandedReconstructableTreesExtension {
2456                version: "1".to_owned(),
2457                trees: expanded_tree_memberships,
2458            })
2459            .map_err(|source| FolderbaseError::json(&analysis.root, source))?,
2460        );
2461    }
2462    let source_inventory_digest = inventory_digest(&source_files)?;
2463    let plan = MigrationPlan {
2464        protocol_version: "0.2.0".to_owned(),
2465        id: format!("migration_{}", Uuid::now_v7()),
2466        root: analysis.root,
2467        state: MigrationState::Proposed,
2468        source_inventory: SourceInventory {
2469            algorithm: "sha256".to_owned(),
2470            digest: source_inventory_digest,
2471            files: source_files,
2472        },
2473        answers,
2474        template_references: vec!["folderbase.project@0.2.2".to_owned()],
2475        targets: analysis.proposed_targets,
2476        operations,
2477        exclusions,
2478        approval_digest: None,
2479        extensions,
2480        root_identity: analysis.root_identity,
2481    };
2482    persist_new_plan(&plan)?;
2483    Ok(plan)
2484}
2485
2486pub fn preview_migration(plan: &MigrationPlan) -> Result<MigrationPreview> {
2487    require_state(plan.state, MigrationState::Proposed)?;
2488    let mut creates_directories = Vec::new();
2489    let mut copies = Vec::new();
2490    let mut source_bytes = 0;
2491    let mut structural_operations = Vec::new();
2492
2493    for operation in &plan.operations {
2494        match operation {
2495            MigrationOperation::CreateFolder { path } => {
2496                ensure_safe_relative(path)?;
2497                creates_directories.push(path.clone());
2498            }
2499            MigrationOperation::CopyFile {
2500                source_path,
2501                destination_path,
2502                ..
2503            } => {
2504                ensure_safe_relative(source_path)?;
2505                ensure_safe_relative(destination_path)?;
2506                let bytes = plan
2507                    .source_inventory
2508                    .files
2509                    .iter()
2510                    .find(|file| file.path == *source_path)
2511                    .map(|file| file.bytes)
2512                    .ok_or_else(|| FolderbaseError::MigrationSourceChanged(source_path.clone()))?;
2513                source_bytes += bytes;
2514                copies.push(MigrationCopyPreview {
2515                    source_path: source_path.clone(),
2516                    destination_path: destination_path.clone(),
2517                    bytes,
2518                });
2519            }
2520            operation if operation.is_structural() => {
2521                let source_path = operation
2522                    .structural_source_path()
2523                    .expect("structural operation has a source");
2524                source_bytes += plan
2525                    .source_inventory
2526                    .files
2527                    .iter()
2528                    .find(|file| file.path == source_path)
2529                    .map(|file| file.bytes)
2530                    .ok_or_else(|| {
2531                        FolderbaseError::MigrationSourceChanged(source_path.to_path_buf())
2532                    })?;
2533                structural_operations.push(operation.clone());
2534            }
2535            _ => unreachable!("all migration operations are additive or structural"),
2536        }
2537    }
2538    let source_files_remain = !structural_operations
2539        .iter()
2540        .any(|operation| matches!(operation, MigrationOperation::MoveObject { .. }));
2541
2542    Ok(MigrationPreview {
2543        migration_id: plan.id.clone(),
2544        targets: plan.targets.clone(),
2545        creates_directories,
2546        copies,
2547        source_bytes,
2548        additional_local_bytes: source_bytes,
2549        source_files_remain,
2550        structural_operations,
2551    })
2552}
2553
2554pub fn approve_migration(mut plan: MigrationPlan) -> Result<ApprovedMigration> {
2555    require_state(plan.state, MigrationState::Proposed)?;
2556    let stored = load_plan(&plan.root, &plan.id)?;
2557    require_state(stored.state, MigrationState::Proposed)?;
2558    if plan_digest(&plan)? != plan_digest(&stored)? {
2559        return Err(FolderbaseError::MigrationApprovalMismatch);
2560    }
2561    plan = stored;
2562    if is_structural_plan(&plan) {
2563        validate_typed_ignore_policy_updates(&plan)?;
2564        prepare_structural_snapshots(&mut plan)?;
2565    }
2566    plan.state = MigrationState::Approved;
2567    let approval_digest = plan_digest(&plan)?;
2568    plan.approval_digest = Some(approval_digest.clone());
2569    persist_plan(&plan)?;
2570    Ok(ApprovedMigration {
2571        plan,
2572        approval_digest,
2573    })
2574}
2575
2576fn is_structural_plan(plan: &MigrationPlan) -> bool {
2577    plan.extensions.get("plan_kind")
2578        == Some(&serde_json::Value::String(STRUCTURAL_PLAN_KIND.to_owned()))
2579        && plan
2580            .extensions
2581            .get("snapshot_required")
2582            .and_then(serde_json::Value::as_bool)
2583            == Some(true)
2584}
2585
2586fn is_structural_journal(journal: &MigrationJournal) -> bool {
2587    journal.plan_extensions.get("plan_kind")
2588        == Some(&serde_json::Value::String(STRUCTURAL_PLAN_KIND.to_owned()))
2589        && journal
2590            .plan_extensions
2591            .get("snapshot_required")
2592            .and_then(serde_json::Value::as_bool)
2593            == Some(true)
2594}
2595
2596fn prepare_structural_snapshots(plan: &mut MigrationPlan) -> Result<()> {
2597    verify_root_identity(plan)?;
2598    verify_source_files(plan)?;
2599    let migration_relative = PathBuf::from(MIGRATIONS_DIR).join(&plan.id);
2600    let snapshots_relative = migration_relative.join("snapshots");
2601    let snapshots = safe_join(&plan.root, &snapshots_relative)?;
2602    if snapshots.exists() {
2603        return bind_existing_structural_snapshots(plan, &snapshots_relative, &snapshots);
2604    }
2605    let temporary_relative = migration_relative.join(format!("snapshots.{}.tmp", Uuid::now_v7()));
2606    let temporary = safe_join(&plan.root, &temporary_relative)?;
2607    create_private_directory_new(&temporary)?;
2608    sync_parent(&temporary)?;
2609
2610    let result = (|| -> Result<()> {
2611        for (index, operation) in plan.operations.iter_mut().enumerate() {
2612            let source_path = operation
2613                .structural_source_path()
2614                .ok_or_else(|| {
2615                    invalid_journal(&plan.root, "snapshot requested for additive operation")
2616                })?
2617                .to_path_buf();
2618            let expected = operation
2619                .structural_expected_sha256()
2620                .ok_or_else(|| invalid_journal(&plan.root, "structural digest is missing"))?
2621                .to_owned();
2622            let source = safe_join(&plan.root, &source_path)?;
2623            if sha256_path(&source)? != expected {
2624                return Err(FolderbaseError::MigrationSourceChanged(source_path));
2625            }
2626            let snapshot_name = format!("{index}.bin");
2627            let temporary_snapshot = temporary.join(&snapshot_name);
2628            copy_new(&source, &temporary_snapshot)?;
2629            if sha256_path(&temporary_snapshot)? != expected {
2630                return Err(FolderbaseError::MigrationVerificationFailed(
2631                    temporary_snapshot,
2632                ));
2633            }
2634            operation.set_structural_snapshot(snapshots_relative.join(snapshot_name), expected);
2635        }
2636        sync_directory(&temporary)?;
2637        fs::rename(&temporary, &snapshots)
2638            .map_err(|source| FolderbaseError::io(&snapshots, source))?;
2639        sync_parent(&snapshots)
2640    })();
2641    if result.is_err() {
2642        let _ = fs::remove_dir_all(&temporary);
2643    }
2644    result
2645}
2646
2647fn bind_existing_structural_snapshots(
2648    plan: &mut MigrationPlan,
2649    snapshots_relative: &Path,
2650    snapshots: &Path,
2651) -> Result<()> {
2652    let metadata =
2653        fs::symlink_metadata(snapshots).map_err(|source| FolderbaseError::io(snapshots, source))?;
2654    if !metadata.is_dir() || metadata.file_type().is_symlink() {
2655        return Err(FolderbaseError::MigrationVerificationFailed(
2656            snapshots.to_path_buf(),
2657        ));
2658    }
2659    let entries = fs::read_dir(snapshots)
2660        .map_err(|source| FolderbaseError::io(snapshots, source))?
2661        .collect::<std::io::Result<Vec<_>>>()
2662        .map_err(|source| FolderbaseError::io(snapshots, source))?;
2663    if entries.len() != plan.operations.len() {
2664        return Err(FolderbaseError::MigrationVerificationFailed(
2665            snapshots.to_path_buf(),
2666        ));
2667    }
2668    for (index, operation) in plan.operations.iter_mut().enumerate() {
2669        let expected = operation
2670            .structural_expected_sha256()
2671            .ok_or_else(|| invalid_journal(&plan.root, "structural digest is missing"))?
2672            .to_owned();
2673        let snapshot_name = format!("{index}.bin");
2674        let snapshot_relative = snapshots_relative.join(&snapshot_name);
2675        let snapshot = safe_join(&plan.root, &snapshot_relative)?;
2676        let metadata = fs::symlink_metadata(&snapshot)
2677            .map_err(|source| FolderbaseError::io(&snapshot, source))?;
2678        if !metadata.is_file()
2679            || metadata.file_type().is_symlink()
2680            || sha256_path(&snapshot)? != expected
2681        {
2682            return Err(FolderbaseError::MigrationVerificationFailed(snapshot));
2683        }
2684        operation.set_structural_snapshot(snapshot_relative, expected);
2685    }
2686    Ok(())
2687}
2688
2689/// Compatibility adapter for applying an approved migration.
2690///
2691/// The adapter retains the released `ApprovedMigration` API and maps semantic
2692/// transaction conflicts into its legacy `Result` error shape. New callers
2693/// that need explicit `Conflicted` or `RecoveryRequired` outcomes should use
2694/// [`MigrationExecution::run`] with [`MigrationCommand::Apply`].
2695///
2696/// Core durably records execution before ordinary-folder mutation and never
2697/// overwrites pre-existing content. Recovery direction is selected through the
2698/// durable execution format rather than inferred from an adapter error.
2699pub fn apply_migration(approved: ApprovedMigration) -> Result<MigrationResult> {
2700    apply_migration_with_hook(approved, |_| {})
2701}
2702
2703#[derive(Debug, Clone, Copy, PartialEq, Eq)]
2704enum ApplyCheckpoint {
2705    ExistingFolderbaseDetected,
2706    MutationAuthorityBound,
2707    JournalPrepared,
2708}
2709
2710#[derive(Debug, Clone, Copy, PartialEq, Eq)]
2711enum TransactionV1Checkpoint {
2712    ApplyIntentPersisted(usize),
2713    PrivatePublishClaimStaged(usize),
2714    ReplacePublishClaimPrepared(usize),
2715    ClaimComplete(usize),
2716    ParentsRevalidatedBeforePublish(usize),
2717    VisiblePublishComplete(usize),
2718    PrivateApplyReceiptPersisted(usize),
2719    JournalApplyReceiptPersisted(usize),
2720    PrivatePublicationOwnershipRetired(usize),
2721    RollbackRequested,
2722    InverseClaimComplete(usize),
2723    PrivateRollbackReceiptPersisted(usize),
2724    JournalRollbackReceiptPersisted(usize),
2725    PrivateAbortReceiptPersisted(usize),
2726    JournalAbortReceiptPersisted(usize),
2727    MoveAbortRollbackClaimRetired(usize),
2728    MoveAbortSourceClaimRetired(usize),
2729    ConflictRecorded(usize),
2730}
2731
2732#[cfg(test)]
2733#[allow(dead_code)]
2734#[derive(Debug, Clone, Copy, PartialEq, Eq)]
2735enum StructuralRollbackCheckpoint {
2736    Started,
2737    OperationPlanned(usize),
2738    OperationApplied(usize),
2739    OperationCompleted(usize),
2740    Completed,
2741}
2742
2743fn apply_migration_with_hook(
2744    approved: ApprovedMigration,
2745    checkpoint: impl FnMut(ApplyCheckpoint),
2746) -> Result<MigrationResult> {
2747    let migration_id = approved.plan.id.clone();
2748    let approval_digest = approved.approval_digest.clone();
2749    match MigrationExecution::run_apply_with_hook(
2750        RootClaim::Approved {
2751            approved_migration: approved,
2752        },
2753        MigrationCommand::Apply {
2754            migration_id: &migration_id,
2755            approval_digest: &approval_digest,
2756        },
2757        checkpoint,
2758    )? {
2759        MigrationOutcome::Applied(result) => Ok(result),
2760        MigrationOutcome::RolledBack(_) | MigrationOutcome::Conflicted { .. } => {
2761            Err(FolderbaseError::InvalidMigrationState {
2762                expected: MigrationState::Verified.as_str(),
2763                actual: MigrationState::Conflicted.as_str().to_owned(),
2764            })
2765        }
2766        MigrationOutcome::RecoveryRequired { work, .. } => {
2767            Err(FolderbaseError::RecoveryRequired { work })
2768        }
2769    }
2770}
2771
2772impl MigrationExecution {
2773    fn run_apply_with_hook(
2774        root: RootClaim<'_>,
2775        command: MigrationCommand<'_>,
2776        checkpoint: impl FnMut(ApplyCheckpoint),
2777    ) -> Result<MigrationOutcome> {
2778        match (root, command) {
2779            (
2780                RootClaim::Approved { approved_migration },
2781                MigrationCommand::Apply {
2782                    migration_id,
2783                    approval_digest,
2784                },
2785            ) => {
2786                if approved_migration.plan.id != migration_id
2787                    || approved_migration.approval_digest != approval_digest
2788                {
2789                    return Err(FolderbaseError::MigrationApprovalMismatch);
2790                }
2791                apply_transaction_v1_migration_outcome_with_hook(approved_migration, checkpoint)
2792            }
2793            (
2794                RootClaim::Current { display_root },
2795                MigrationCommand::Apply {
2796                    migration_id,
2797                    approval_digest,
2798                },
2799            ) => run_current_transaction_v1_apply_with_hooks(
2800                display_root,
2801                migration_id,
2802                approval_digest,
2803                || {},
2804                checkpoint,
2805                |_| {},
2806            ),
2807            (_, _) => Err(FolderbaseError::InvalidMigrationState {
2808                expected: MigrationState::Approved.as_str(),
2809                actual: "non_apply_command".to_owned(),
2810            }),
2811        }
2812    }
2813}
2814
2815fn apply_transaction_v1_migration_outcome_with_hook(
2816    approved: ApprovedMigration,
2817    checkpoint: impl FnMut(ApplyCheckpoint),
2818) -> Result<MigrationOutcome> {
2819    apply_transaction_v1_migration_outcome_with_hooks(approved, checkpoint, |_| {})
2820}
2821
2822fn apply_transaction_v1_migration_outcome_with_hooks(
2823    approved: ApprovedMigration,
2824    mut checkpoint: impl FnMut(ApplyCheckpoint),
2825    transaction_checkpoint: impl FnMut(TransactionV1Checkpoint),
2826) -> Result<MigrationOutcome> {
2827    let in_memory_plan = approved.plan;
2828    require_state(in_memory_plan.state, MigrationState::Approved)?;
2829    if plan_digest(&in_memory_plan)? != approved.approval_digest {
2830        return Err(FolderbaseError::MigrationApprovalMismatch);
2831    }
2832    let approved_root_identity = in_memory_plan
2833        .root_identity
2834        .as_ref()
2835        .ok_or_else(|| FolderbaseError::MigrationSourceChanged(in_memory_plan.root.clone()))?
2836        .identity();
2837    let transaction_coordinator = acquire_existing_folderbase_transaction_lock_with_hook(
2838        &in_memory_plan.root,
2839        approved_root_identity,
2840        || {
2841            checkpoint(ApplyCheckpoint::ExistingFolderbaseDetected);
2842        },
2843    )?;
2844    require_no_pending_work_except(&transaction_coordinator.state, &in_memory_plan.id)?;
2845    let migration_filesystem =
2846        transaction_coordinator.migration_filesystem(&in_memory_plan.root)?;
2847    let execution_format = classify_execution_format(&migration_filesystem, &in_memory_plan.id)?;
2848    apply_transaction_v1_migration_in_with_hooks(
2849        &migration_filesystem,
2850        &in_memory_plan.id,
2851        &approved.approval_digest,
2852        approved_root_identity.stable_sha256(),
2853        execution_format,
2854        checkpoint,
2855        transaction_checkpoint,
2856    )
2857}
2858
2859fn apply_transaction_v1_migration_in_with_hooks(
2860    migration_filesystem: &MigrationFilesystem,
2861    migration_id: &str,
2862    approval_digest: &str,
2863    root_identity_sha256: String,
2864    execution_format: ExecutionFormat,
2865    mut checkpoint: impl FnMut(ApplyCheckpoint),
2866    transaction_checkpoint: impl FnMut(TransactionV1Checkpoint),
2867) -> Result<MigrationOutcome> {
2868    match execution_format {
2869        ExecutionFormat::None
2870        | ExecutionFormat::PrePreparedTransactionV1
2871        | ExecutionFormat::TransactionV1 => {}
2872        ExecutionFormat::LegacyResult => {
2873            return Err(FolderbaseError::InvalidMigrationState {
2874                expected: MigrationState::Approved.as_str(),
2875                actual: "legacy_result".to_owned(),
2876            });
2877        }
2878    }
2879    let plan = load_plan_from(migration_filesystem, migration_id)?;
2880    require_state(plan.state, MigrationState::Approved)?;
2881    if plan.approval_digest.as_deref() != Some(approval_digest)
2882        || plan_digest(&plan)? != approval_digest
2883    {
2884        return Err(FolderbaseError::MigrationApprovalMismatch);
2885    }
2886    validate_typed_ignore_policy_updates(&plan)?;
2887    if matches!(
2888        execution_format,
2889        ExecutionFormat::None | ExecutionFormat::PrePreparedTransactionV1
2890    ) {
2891        let verification = (|| -> Result<()> {
2892            verify_source_files_in(migration_filesystem, &plan)?;
2893            if !is_structural_plan(&plan) {
2894                verify_additive_source_topology_in(migration_filesystem, &plan)?;
2895                verify_expanded_reconstructable_trees_in(migration_filesystem, &plan)?;
2896            }
2897            Ok(())
2898        })();
2899        if let Err(error) = verification {
2900            // A no-follow leaf rejection reports its concrete absolute display
2901            // path and is a durable migration conflict even before a journal
2902            // exists. Topology drift remains an Approved plan that the user may
2903            // restore and retry.
2904            if matches!(
2905                &error,
2906                FolderbaseError::UnsafePath(path) if path.is_absolute()
2907            ) {
2908                persist_plan_transition_in(
2909                    migration_filesystem,
2910                    &plan.id,
2911                    &[MigrationState::Approved],
2912                    MigrationState::Conflicted,
2913                )?;
2914            }
2915            return Err(error);
2916        }
2917    }
2918    checkpoint(ApplyCheckpoint::MutationAuthorityBound);
2919    let mut transaction = prepare_transaction_v1(
2920        migration_filesystem,
2921        &plan,
2922        approval_digest,
2923        root_identity_sha256,
2924    )?;
2925    checkpoint(ApplyCheckpoint::JournalPrepared);
2926    let migration_root = PathBuf::from(MIGRATIONS_DIR).join(&plan.id);
2927    let conflict_recorded = Cell::new(false);
2928    let mut transaction_checkpoint = transaction_checkpoint;
2929    let mut tracked_checkpoint = |checkpoint| {
2930        if matches!(checkpoint, TransactionV1Checkpoint::ConflictRecorded(_)) {
2931            conflict_recorded.set(true);
2932        }
2933        transaction_checkpoint(checkpoint);
2934    };
2935    let result = execute_transaction_v1_apply_with_hook(
2936        migration_filesystem,
2937        &mut transaction,
2938        &mut tracked_checkpoint,
2939    )
2940    .map(MigrationOutcome::Applied);
2941    map_durable_transaction_v1_conflict(
2942        migration_filesystem,
2943        &migration_root,
2944        &plan.id,
2945        result,
2946        conflict_recorded.get(),
2947    )
2948}
2949
2950#[cfg(test)]
2951fn applied_result_from_outcome(outcome: MigrationOutcome) -> Result<MigrationResult> {
2952    match outcome {
2953        MigrationOutcome::Applied(result) => Ok(result),
2954        MigrationOutcome::RolledBack(_) | MigrationOutcome::Conflicted { .. } => {
2955            Err(FolderbaseError::InvalidMigrationState {
2956                expected: MigrationState::Verified.as_str(),
2957                actual: MigrationState::Conflicted.as_str().to_owned(),
2958            })
2959        }
2960        MigrationOutcome::RecoveryRequired { work, .. } => {
2961            Err(FolderbaseError::RecoveryRequired { work })
2962        }
2963    }
2964}
2965
2966#[cfg(test)]
2967fn apply_migration_with_transaction_hook(
2968    approved: ApprovedMigration,
2969    checkpoint: impl FnMut(TransactionV1Checkpoint),
2970) -> Result<MigrationResult> {
2971    applied_result_from_outcome(apply_transaction_v1_migration_outcome_with_hooks(
2972        approved,
2973        |_| {},
2974        checkpoint,
2975    )?)
2976}
2977
2978struct PreparedTransactionV1 {
2979    program: MutationProgramV1,
2980    program_digest: String,
2981    generations: Vec<TransactionJournalGenerationV1>,
2982    private: PrivateTransactionV1,
2983}
2984
2985struct PrivateTransactionV1 {
2986    _transaction: VerifiedPrivateDirectory,
2987    journal: VerifiedPrivateDirectory,
2988    stages: VerifiedPrivateDirectory,
2989    claims: VerifiedPrivateDirectory,
2990    snapshots: VerifiedPrivateDirectory,
2991    receipts: VerifiedPrivateDirectory,
2992}
2993
2994#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
2995#[serde(rename_all = "snake_case")]
2996enum PrivateReceiptDirectionV1 {
2997    Apply,
2998    Rollback,
2999}
3000
3001#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
3002#[serde(deny_unknown_fields)]
3003struct PrivateLeafReceiptV1 {
3004    format: String,
3005    transaction_id: String,
3006    program_digest: String,
3007    operation_index: usize,
3008    direction: PrivateReceiptDirectionV1,
3009    before_identity_sha256: Option<String>,
3010    after_identity_sha256: Option<String>,
3011    checksum: String,
3012}
3013
3014impl PrivateLeafReceiptV1 {
3015    fn new(
3016        transaction: &PreparedTransactionV1,
3017        operation_index: usize,
3018        direction: PrivateReceiptDirectionV1,
3019        before_identity_sha256: Option<String>,
3020        after_identity_sha256: Option<String>,
3021    ) -> Result<Self> {
3022        let mut receipt = Self {
3023            format: "folderbase-private-leaf-receipt-v1".to_owned(),
3024            transaction_id: transaction.program.transaction_id().to_owned(),
3025            program_digest: transaction.program_digest.clone(),
3026            operation_index,
3027            direction,
3028            before_identity_sha256,
3029            after_identity_sha256,
3030            checksum: String::new(),
3031        };
3032        receipt.checksum = receipt.calculate_checksum()?;
3033        Ok(receipt)
3034    }
3035
3036    fn calculate_checksum(&self) -> Result<String> {
3037        let controlled = (
3038            &self.format,
3039            &self.transaction_id,
3040            &self.program_digest,
3041            self.operation_index,
3042            self.direction,
3043            &self.before_identity_sha256,
3044            &self.after_identity_sha256,
3045        );
3046        let bytes = serde_json::to_vec(&controlled).map_err(|source| {
3047            FolderbaseError::json(Path::new("<private-leaf-receipt-v1>"), source)
3048        })?;
3049        Ok(sha256_bytes(
3050            [b"folderbase-private-leaf-receipt-v1\0".as_slice(), &bytes]
3051                .concat()
3052                .as_slice(),
3053        ))
3054    }
3055
3056    fn encode(&self) -> Result<Vec<u8>> {
3057        if self.format != "folderbase-private-leaf-receipt-v1"
3058            || self.checksum != self.calculate_checksum()?
3059            || self
3060                .before_identity_sha256
3061                .as_deref()
3062                .is_some_and(|digest| !is_sha256(digest))
3063            || self
3064                .after_identity_sha256
3065                .as_deref()
3066                .is_some_and(|digest| !is_sha256(digest))
3067        {
3068            return Err(invalid_journal(
3069                Path::new("<private-leaf-receipt-v1>"),
3070                "private leaf receipt is invalid",
3071            ));
3072        }
3073        serde_json::to_vec(self)
3074            .map_err(|source| FolderbaseError::json(Path::new("<private-leaf-receipt-v1>"), source))
3075    }
3076
3077    fn decode(path: &Path, bytes: &[u8]) -> Result<Self> {
3078        let receipt: Self =
3079            serde_json::from_slice(bytes).map_err(|source| FolderbaseError::json(path, source))?;
3080        if receipt.encode()? != bytes {
3081            return Err(invalid_journal(
3082                path,
3083                "private leaf receipt is not canonical",
3084            ));
3085        }
3086        Ok(receipt)
3087    }
3088}
3089
3090#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
3091#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
3092enum PrivateAbortClaimV1 {
3093    Regular {
3094        name: String,
3095        physical_identity_sha256: String,
3096        device_sha256: String,
3097        bytes: u64,
3098        sha256: String,
3099        read_only: bool,
3100        executable: bool,
3101        link_count: u64,
3102    },
3103    Directory {
3104        name: String,
3105        physical_identity_sha256: String,
3106        device_sha256: String,
3107        read_only: bool,
3108        executable: bool,
3109        empty: bool,
3110    },
3111}
3112
3113impl PrivateAbortClaimV1 {
3114    fn name(&self) -> &str {
3115        match self {
3116            Self::Regular { name, .. } | Self::Directory { name, .. } => name,
3117        }
3118    }
3119
3120    fn is_directory(&self) -> bool {
3121        matches!(self, Self::Directory { .. })
3122    }
3123
3124    fn exact_regular(&self) -> Option<ExactRegularLeaf<'_>> {
3125        match self {
3126            Self::Regular {
3127                physical_identity_sha256,
3128                device_sha256,
3129                bytes,
3130                sha256,
3131                read_only,
3132                executable,
3133                link_count,
3134                ..
3135            } => Some(ExactRegularLeaf {
3136                physical_identity_sha256,
3137                device_sha256,
3138                bytes: *bytes,
3139                sha256,
3140                read_only: *read_only,
3141                executable: *executable,
3142                link_count: *link_count,
3143            }),
3144            Self::Directory { .. } => None,
3145        }
3146    }
3147
3148    fn exact_directory(&self) -> Option<ExactDirectoryLeaf<'_>> {
3149        match self {
3150            Self::Directory {
3151                physical_identity_sha256,
3152                device_sha256,
3153                read_only,
3154                executable,
3155                ..
3156            } => Some(ExactDirectoryLeaf {
3157                physical_identity_sha256,
3158                device_sha256,
3159                read_only: *read_only,
3160                executable: *executable,
3161            }),
3162            Self::Regular { .. } => None,
3163        }
3164    }
3165
3166    fn validate(&self) -> bool {
3167        match self {
3168            Self::Regular {
3169                name,
3170                physical_identity_sha256,
3171                device_sha256,
3172                sha256,
3173                link_count,
3174                ..
3175            } => {
3176                !name.is_empty()
3177                    && Path::new(name).file_name() == Some(OsStr::new(name))
3178                    && is_sha256(physical_identity_sha256)
3179                    && is_sha256(device_sha256)
3180                    && is_sha256(sha256)
3181                    && *link_count > 0
3182            }
3183            Self::Directory {
3184                name,
3185                physical_identity_sha256,
3186                device_sha256,
3187                empty,
3188                ..
3189            } => {
3190                !name.is_empty()
3191                    && Path::new(name).file_name() == Some(OsStr::new(name))
3192                    && is_sha256(physical_identity_sha256)
3193                    && is_sha256(device_sha256)
3194                    && *empty
3195            }
3196        }
3197    }
3198}
3199
3200#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
3201#[serde(deny_unknown_fields)]
3202struct PrivateAbortWorkReceiptV1 {
3203    format: String,
3204    transaction_id: String,
3205    program_digest: String,
3206    operation_index: usize,
3207    visible_post_identity_sha256: Option<String>,
3208    claims: Vec<PrivateAbortClaimV1>,
3209    checksum: String,
3210}
3211
3212impl PrivateAbortWorkReceiptV1 {
3213    fn new(
3214        transaction: &PreparedTransactionV1,
3215        operation_index: usize,
3216        visible_post_identity_sha256: Option<String>,
3217        mut claims: Vec<PrivateAbortClaimV1>,
3218    ) -> Result<Self> {
3219        claims.sort_by(|left, right| left.name().cmp(right.name()));
3220        let mut receipt = Self {
3221            format: "folderbase-private-abort-work-v1".to_owned(),
3222            transaction_id: transaction.program.transaction_id().to_owned(),
3223            program_digest: transaction.program_digest.clone(),
3224            operation_index,
3225            visible_post_identity_sha256,
3226            claims,
3227            checksum: String::new(),
3228        };
3229        receipt.checksum = receipt.calculate_checksum()?;
3230        receipt.validate(Path::new("<private-abort-work-receipt-v1>"))?;
3231        Ok(receipt)
3232    }
3233
3234    fn calculate_checksum(&self) -> Result<String> {
3235        let controlled = (
3236            &self.format,
3237            &self.transaction_id,
3238            &self.program_digest,
3239            self.operation_index,
3240            &self.visible_post_identity_sha256,
3241            &self.claims,
3242        );
3243        let bytes = serde_json::to_vec(&controlled).map_err(|source| {
3244            FolderbaseError::json(Path::new("<private-abort-work-receipt-v1>"), source)
3245        })?;
3246        Ok(sha256_bytes(
3247            [b"folderbase-private-abort-work-v1\0".as_slice(), &bytes]
3248                .concat()
3249                .as_slice(),
3250        ))
3251    }
3252
3253    fn validate(&self, path: &Path) -> Result<()> {
3254        let sorted_unique = self
3255            .claims
3256            .windows(2)
3257            .all(|pair| pair[0].name() < pair[1].name());
3258        if self.format != "folderbase-private-abort-work-v1"
3259            || self.checksum != self.calculate_checksum()?
3260            || self
3261                .visible_post_identity_sha256
3262                .as_deref()
3263                .is_some_and(|digest| !is_sha256(digest))
3264            || !sorted_unique
3265            || self.claims.iter().any(|claim| !claim.validate())
3266        {
3267            return Err(invalid_journal(
3268                path,
3269                "private abort-work receipt is invalid",
3270            ));
3271        }
3272        Ok(())
3273    }
3274
3275    fn encode(&self) -> Result<Vec<u8>> {
3276        self.validate(Path::new("<private-abort-work-receipt-v1>"))?;
3277        serde_json::to_vec(self).map_err(|source| {
3278            FolderbaseError::json(Path::new("<private-abort-work-receipt-v1>"), source)
3279        })
3280    }
3281
3282    fn decode(path: &Path, bytes: &[u8]) -> Result<Self> {
3283        let receipt: Self =
3284            serde_json::from_slice(bytes).map_err(|source| FolderbaseError::json(path, source))?;
3285        receipt.validate(path)?;
3286        if receipt.encode()? != bytes {
3287            return Err(invalid_journal(
3288                path,
3289                "private abort-work receipt is not canonical",
3290            ));
3291        }
3292        Ok(receipt)
3293    }
3294
3295    fn encoded_sha256(&self) -> Result<String> {
3296        Ok(sha256_bytes(&self.encode()?))
3297    }
3298}
3299
3300fn private_claim_name(operation_index: usize, kind: &str) -> String {
3301    format!("{operation_index:08}.{kind}.claim")
3302}
3303
3304fn private_abort_receipt_name(operation_index: usize) -> String {
3305    format!("{operation_index:08}.abort.receipt")
3306}
3307
3308fn private_receipt_name(operation_index: usize, direction: PrivateReceiptDirectionV1) -> String {
3309    let direction = match direction {
3310        PrivateReceiptDirectionV1::Apply => "apply",
3311        PrivateReceiptDirectionV1::Rollback => "rollback",
3312    };
3313    format!("{operation_index:08}.{direction}.receipt")
3314}
3315
3316fn recoverable_receipt_final_name(name: &OsStr) -> Option<String> {
3317    name.to_str()?
3318        .strip_prefix('.')?
3319        .strip_suffix(".preparing")
3320        .map(str::to_owned)
3321}
3322
3323fn persist_private_leaf_receipt(
3324    transaction: &PreparedTransactionV1,
3325    receipt: &PrivateLeafReceiptV1,
3326) -> Result<()> {
3327    let name = private_receipt_name(receipt.operation_index, receipt.direction);
3328    transaction.private.receipts.publish_recoverable_new(
3329        &name,
3330        &format!(".{name}.preparing"),
3331        &receipt.encode()?,
3332    )
3333}
3334
3335fn load_private_leaf_receipt(
3336    transaction: &PreparedTransactionV1,
3337    operation_index: usize,
3338    direction: PrivateReceiptDirectionV1,
3339) -> Result<Option<PrivateLeafReceiptV1>> {
3340    let name = private_receipt_name(operation_index, direction);
3341    let bytes = match transaction
3342        .private
3343        .receipts
3344        .read_regular_bounded(OsStr::new(&name), 16 * 1024)
3345    {
3346        Ok(bytes) => bytes,
3347        Err(FolderbaseError::Io { source, .. })
3348            if source.kind() == std::io::ErrorKind::NotFound =>
3349        {
3350            return Ok(None);
3351        }
3352        Err(error) => return Err(error),
3353    };
3354    let receipt_path = transaction.private.receipts.display_path(OsStr::new(&name));
3355    let receipt = PrivateLeafReceiptV1::decode(&receipt_path, &bytes)?;
3356    if receipt.transaction_id != transaction.program.transaction_id()
3357        || receipt.program_digest != transaction.program_digest
3358        || receipt.operation_index != operation_index
3359        || receipt.direction != direction
3360    {
3361        return Err(invalid_journal(
3362            &receipt_path,
3363            "private leaf receipt is bound to another transaction",
3364        ));
3365    }
3366    Ok(Some(receipt))
3367}
3368
3369fn persist_private_abort_work_receipt(
3370    transaction: &PreparedTransactionV1,
3371    receipt: &PrivateAbortWorkReceiptV1,
3372) -> Result<()> {
3373    let name = private_abort_receipt_name(receipt.operation_index);
3374    transaction.private.receipts.publish_recoverable_new(
3375        &name,
3376        &format!(".{name}.preparing"),
3377        &receipt.encode()?,
3378    )
3379}
3380
3381fn load_private_abort_work_receipt(
3382    transaction: &PreparedTransactionV1,
3383    operation_index: usize,
3384) -> Result<Option<PrivateAbortWorkReceiptV1>> {
3385    let name = private_abort_receipt_name(operation_index);
3386    let bytes = match transaction
3387        .private
3388        .receipts
3389        .read_regular_bounded(OsStr::new(&name), 64 * 1024)
3390    {
3391        Ok(bytes) => bytes,
3392        Err(FolderbaseError::Io { source, .. })
3393            if source.kind() == std::io::ErrorKind::NotFound =>
3394        {
3395            return Ok(None);
3396        }
3397        Err(error) => return Err(error),
3398    };
3399    let path = transaction.private.receipts.display_path(OsStr::new(&name));
3400    let receipt = PrivateAbortWorkReceiptV1::decode(&path, &bytes)?;
3401    if receipt.transaction_id != transaction.program.transaction_id()
3402        || receipt.program_digest != transaction.program_digest
3403        || receipt.operation_index != operation_index
3404    {
3405        return Err(invalid_journal(
3406            &path,
3407            "private abort-work receipt is bound to another transaction",
3408        ));
3409    }
3410    Ok(Some(receipt))
3411}
3412
3413fn validate_staged_private_receipt_context(
3414    filesystem: &MigrationFilesystem,
3415    transaction: &PreparedTransactionV1,
3416    final_name: &str,
3417    bytes: &[u8],
3418) -> Result<()> {
3419    let current = transaction
3420        .generations
3421        .last()
3422        .ok_or_else(|| invalid_journal(Path::new("<transaction-v1>"), "journal is empty"))?;
3423    let in_flight = current.in_flight_operation();
3424    for operation_index in 0..transaction.program.operation_count() {
3425        for direction in [
3426            PrivateReceiptDirectionV1::Apply,
3427            PrivateReceiptDirectionV1::Rollback,
3428        ] {
3429            if final_name != private_receipt_name(operation_index, direction) {
3430                continue;
3431            }
3432            let path = transaction
3433                .private
3434                .receipts
3435                .display_path(OsStr::new(final_name));
3436            let receipt = PrivateLeafReceiptV1::decode(&path, bytes)?;
3437            if receipt.transaction_id != transaction.program.transaction_id()
3438                || receipt.program_digest != transaction.program_digest
3439                || receipt.operation_index != operation_index
3440                || receipt.direction != direction
3441                || in_flight != Some(operation_index)
3442            {
3443                return Err(invalid_journal(
3444                    &path,
3445                    "staged private leaf receipt is outside the exact in-flight context",
3446                ));
3447            }
3448            let expected_direction = match (
3449                current.direction(),
3450                current.phase(),
3451                current.receipt_identity(operation_index),
3452            ) {
3453                (TransactionDirectionV1::Rollback, TransactionPhaseV1::RollbackRequested, None) => {
3454                    PrivateReceiptDirectionV1::Apply
3455                }
3456                (TransactionDirectionV1::Apply, _, _) => PrivateReceiptDirectionV1::Apply,
3457                (TransactionDirectionV1::Rollback, _, _) => PrivateReceiptDirectionV1::Rollback,
3458            };
3459            if direction != expected_direction {
3460                return Err(invalid_journal(
3461                    &path,
3462                    "staged private leaf receipt has the wrong transaction direction",
3463                ));
3464            }
3465            match direction {
3466                PrivateReceiptDirectionV1::Apply => {
3467                    let expected_before = match transaction.program.step(operation_index)? {
3468                        ProgramStepV1::CreateDirectory { .. }
3469                        | ProgramStepV1::CreateFile { .. } => None,
3470                        ProgramStepV1::ReplaceFile { target, .. } => {
3471                            Some(target.physical_identity_sha256.to_owned())
3472                        }
3473                        ProgramStepV1::MoveFile { source, .. } => {
3474                            Some(source.physical_identity_sha256.to_owned())
3475                        }
3476                    };
3477                    if receipt.before_identity_sha256 != expected_before
3478                        || receipt.after_identity_sha256.is_none()
3479                    {
3480                        return Err(invalid_journal(
3481                            &path,
3482                            "staged private apply receipt tuple disagrees with the program",
3483                        ));
3484                    }
3485                    verify_apply_private_receipt(filesystem, transaction, operation_index, &receipt)
3486                }
3487                PrivateReceiptDirectionV1::Rollback => {
3488                    let expected_before = current
3489                        .apply_receipt_records()
3490                        .into_iter()
3491                        .find_map(|(index, identity)| {
3492                            (index == operation_index).then_some(identity)
3493                        })
3494                        .ok_or_else(|| {
3495                            invalid_journal(
3496                                &path,
3497                                "staged rollback receipt has no durable apply identity",
3498                            )
3499                        })?;
3500                    let after_shape_is_valid = match transaction.program.step(operation_index)? {
3501                        ProgramStepV1::CreateDirectory { .. } => {
3502                            receipt.after_identity_sha256.is_none()
3503                                || receipt.after_identity_sha256 == expected_before
3504                        }
3505                        ProgramStepV1::CreateFile { .. } => receipt.after_identity_sha256.is_none(),
3506                        ProgramStepV1::ReplaceFile { .. } | ProgramStepV1::MoveFile { .. } => {
3507                            receipt.after_identity_sha256.is_some()
3508                        }
3509                    };
3510                    if receipt.before_identity_sha256 != expected_before || !after_shape_is_valid {
3511                        return Err(invalid_journal(
3512                            &path,
3513                            "staged private rollback receipt tuple disagrees with the program",
3514                        ));
3515                    }
3516                    verify_rollback_private_receipt(
3517                        filesystem,
3518                        transaction,
3519                        operation_index,
3520                        &receipt,
3521                    )
3522                }
3523            }?;
3524            return Ok(());
3525        }
3526
3527        if final_name == private_abort_receipt_name(operation_index) {
3528            let path = transaction
3529                .private
3530                .receipts
3531                .display_path(OsStr::new(final_name));
3532            let receipt = PrivateAbortWorkReceiptV1::decode(&path, bytes)?;
3533            if receipt.transaction_id != transaction.program.transaction_id()
3534                || receipt.program_digest != transaction.program_digest
3535                || receipt.operation_index != operation_index
3536                || current.direction() != TransactionDirectionV1::Rollback
3537                || current.phase() != TransactionPhaseV1::RollbackRequested
3538                || in_flight != Some(operation_index)
3539                || current.receipt_identity(operation_index).is_some()
3540                || current.abort_receipt_sha256(operation_index).is_some()
3541            {
3542                return Err(invalid_journal(
3543                    &path,
3544                    "staged abort receipt is outside the exact in-flight context",
3545                ));
3546            }
3547            return verify_private_abort_work_receipt(
3548                filesystem,
3549                transaction,
3550                operation_index,
3551                &receipt,
3552            );
3553        }
3554    }
3555    Err(invalid_journal(
3556        Path::new("<private-leaf-receipt-v1>"),
3557        "staged receipt name is not admitted by the program",
3558    ))
3559}
3560
3561fn repair_recoverable_private_receipt_staging(
3562    filesystem: &MigrationFilesystem,
3563    transaction: &PreparedTransactionV1,
3564) -> Result<()> {
3565    let maximum_entries = transaction
3566        .program
3567        .operation_count()
3568        .saturating_mul(6)
3569        .saturating_add(1);
3570    let entries = transaction
3571        .private
3572        .receipts
3573        .closed_entries(maximum_entries)?;
3574    let names = entries
3575        .iter()
3576        .map(|(name, _)| name.clone())
3577        .collect::<BTreeSet<_>>();
3578    let staged_names = names
3579        .iter()
3580        .filter(|name| recoverable_receipt_final_name(name).is_some())
3581        .cloned()
3582        .collect::<Vec<_>>();
3583    for staged_name in staged_names {
3584        let final_name = recoverable_receipt_final_name(&staged_name)
3585            .expect("staged names were filtered by this parser");
3586        let final_name_os = OsStr::new(&final_name);
3587        let final_exists = names.contains(final_name_os);
3588        let maximum_bytes = if final_name.ends_with(".abort.receipt") {
3589            64 * 1024
3590        } else {
3591            16 * 1024
3592        };
3593        let staged_bytes = transaction
3594            .private
3595            .receipts
3596            .read_relaxed_regular_bounded(&staged_name, maximum_bytes)?;
3597        validate_staged_private_receipt_context(
3598            filesystem,
3599            transaction,
3600            &final_name,
3601            &staged_bytes,
3602        )?;
3603        let (staged_fact, staged_sha256) = transaction
3604            .private
3605            .receipts
3606            .relaxed_regular_fact_observed(&staged_name)?;
3607        if final_exists {
3608            let (final_fact, final_sha256) = transaction
3609                .private
3610                .receipts
3611                .relaxed_regular_fact_observed(final_name_os)?;
3612            if staged_fact.physical_identity_sha256 != final_fact.physical_identity_sha256
3613                || staged_fact.device_sha256 != final_fact.device_sha256
3614                || staged_fact.bytes != final_fact.bytes
3615                || staged_fact.link_count != 2
3616                || final_fact.link_count != 2
3617                || staged_sha256 != final_sha256
3618            {
3619                return Err(invalid_journal(
3620                    transaction.private.receipts.display_path(final_name_os),
3621                    "receipt final and staging are not one exact publication",
3622                ));
3623            }
3624            transaction
3625                .private
3626                .receipts
3627                .retire_exact_recoverable_regular(&staged_name, &staged_fact, &staged_sha256, 2)?;
3628        } else {
3629            if staged_fact.link_count != 1 {
3630                return Err(invalid_journal(
3631                    transaction.private.receipts.display_path(&staged_name),
3632                    "receipt staging has an unexpected alias topology",
3633                ));
3634            }
3635            transaction.private.receipts.install_recoverable_regular(
3636                &staged_name,
3637                final_name_os,
3638                &staged_sha256,
3639                staged_bytes.len() as u64,
3640            )?;
3641        }
3642        transaction.private.receipts.verify_regular(final_name_os)?;
3643    }
3644    Ok(())
3645}
3646
3647fn validate_private_leaf_receipt_set(transaction: &PreparedTransactionV1) -> Result<()> {
3648    let current = transaction
3649        .generations
3650        .last()
3651        .ok_or_else(|| invalid_journal(Path::new("<transaction-v1>"), "journal is empty"))?;
3652    let apply_records = current
3653        .apply_receipt_records()
3654        .into_iter()
3655        .collect::<BTreeMap<_, _>>();
3656    let rollback_records = current
3657        .inverse_receipt_records()
3658        .into_iter()
3659        .collect::<BTreeMap<_, _>>();
3660    let mut admitted = BTreeSet::new();
3661
3662    for (operation_index, expected_identity) in &apply_records {
3663        let receipt_name = private_receipt_name(*operation_index, PrivateReceiptDirectionV1::Apply);
3664        let receipt_path = transaction
3665            .private
3666            .receipts
3667            .display_path(OsStr::new(&receipt_name));
3668        let receipt = load_private_leaf_receipt(
3669            transaction,
3670            *operation_index,
3671            PrivateReceiptDirectionV1::Apply,
3672        )?
3673        .ok_or_else(|| {
3674            invalid_journal(
3675                &receipt_path,
3676                "journal apply receipt has no matching private receipt",
3677            )
3678        })?;
3679        let expected_before = match transaction.program.step(*operation_index)? {
3680            ProgramStepV1::CreateDirectory { .. } | ProgramStepV1::CreateFile { .. } => None,
3681            ProgramStepV1::ReplaceFile { target, .. } => {
3682                Some(target.physical_identity_sha256.to_owned())
3683            }
3684            ProgramStepV1::MoveFile { source, .. } => {
3685                Some(source.physical_identity_sha256.to_owned())
3686            }
3687        };
3688        if receipt.before_identity_sha256 != expected_before
3689            || receipt.after_identity_sha256 != *expected_identity
3690            || receipt.after_identity_sha256.is_none()
3691        {
3692            return Err(invalid_journal(
3693                Path::new("<private-leaf-receipt-v1>"),
3694                "private apply receipt tuple disagrees with the program or journal",
3695            ));
3696        }
3697        admitted.insert(OsString::from(private_receipt_name(
3698            *operation_index,
3699            PrivateReceiptDirectionV1::Apply,
3700        )));
3701    }
3702    for (operation_index, expected_identity) in &rollback_records {
3703        let receipt_name =
3704            private_receipt_name(*operation_index, PrivateReceiptDirectionV1::Rollback);
3705        let receipt_path = transaction
3706            .private
3707            .receipts
3708            .display_path(OsStr::new(&receipt_name));
3709        let receipt = load_private_leaf_receipt(
3710            transaction,
3711            *operation_index,
3712            PrivateReceiptDirectionV1::Rollback,
3713        )?
3714        .ok_or_else(|| {
3715            invalid_journal(
3716                &receipt_path,
3717                "journal rollback receipt has no matching private receipt",
3718            )
3719        })?;
3720        let expected_before = apply_records.get(operation_index).cloned().ok_or_else(|| {
3721            invalid_journal(
3722                Path::new("<private-leaf-receipt-v1>"),
3723                "private rollback receipt has no durable apply identity",
3724            )
3725        })?;
3726        let after_shape_is_valid = match transaction.program.step(*operation_index)? {
3727            ProgramStepV1::CreateDirectory { .. } => {
3728                expected_identity.is_none() || expected_identity == &expected_before
3729            }
3730            ProgramStepV1::CreateFile { .. } => expected_identity.is_none(),
3731            ProgramStepV1::ReplaceFile { .. } | ProgramStepV1::MoveFile { .. } => {
3732                expected_identity.is_some()
3733            }
3734        };
3735        if receipt.before_identity_sha256 != expected_before
3736            || receipt.after_identity_sha256 != *expected_identity
3737            || !after_shape_is_valid
3738        {
3739            return Err(invalid_journal(
3740                Path::new("<private-leaf-receipt-v1>"),
3741                "private rollback receipt tuple disagrees with the program or journal",
3742            ));
3743        }
3744        admitted.insert(OsString::from(private_receipt_name(
3745            *operation_index,
3746            PrivateReceiptDirectionV1::Rollback,
3747        )));
3748    }
3749
3750    if let Some(operation_index) = current.in_flight_operation() {
3751        let direction = match (
3752            current.direction(),
3753            current.phase(),
3754            current.receipt_identity(operation_index),
3755        ) {
3756            (TransactionDirectionV1::Rollback, TransactionPhaseV1::RollbackRequested, None) => {
3757                PrivateReceiptDirectionV1::Apply
3758            }
3759            (TransactionDirectionV1::Apply, _, _) => PrivateReceiptDirectionV1::Apply,
3760            (TransactionDirectionV1::Rollback, _, _) => PrivateReceiptDirectionV1::Rollback,
3761        };
3762        if let Some(receipt) = load_private_leaf_receipt(transaction, operation_index, direction)? {
3763            let valid = match direction {
3764                PrivateReceiptDirectionV1::Apply => {
3765                    let expected_before = match transaction.program.step(operation_index)? {
3766                        ProgramStepV1::CreateDirectory { .. }
3767                        | ProgramStepV1::CreateFile { .. } => None,
3768                        ProgramStepV1::ReplaceFile { target, .. } => {
3769                            Some(target.physical_identity_sha256.to_owned())
3770                        }
3771                        ProgramStepV1::MoveFile { source, .. } => {
3772                            Some(source.physical_identity_sha256.to_owned())
3773                        }
3774                    };
3775                    receipt.before_identity_sha256 == expected_before
3776                        && receipt.after_identity_sha256.is_some()
3777                }
3778                PrivateReceiptDirectionV1::Rollback => {
3779                    let expected_before =
3780                        apply_records
3781                            .get(&operation_index)
3782                            .cloned()
3783                            .ok_or_else(|| {
3784                                invalid_journal(
3785                                    Path::new("<private-leaf-receipt-v1>"),
3786                                    "in-flight rollback receipt has no durable apply identity",
3787                                )
3788                            })?;
3789                    let after_shape_is_valid = match transaction.program.step(operation_index)? {
3790                        ProgramStepV1::CreateDirectory { .. } => {
3791                            receipt.after_identity_sha256.is_none()
3792                                || receipt.after_identity_sha256 == expected_before
3793                        }
3794                        ProgramStepV1::CreateFile { .. } => receipt.after_identity_sha256.is_none(),
3795                        ProgramStepV1::ReplaceFile { .. } | ProgramStepV1::MoveFile { .. } => {
3796                            receipt.after_identity_sha256.is_some()
3797                        }
3798                    };
3799                    receipt.before_identity_sha256 == expected_before && after_shape_is_valid
3800                }
3801            };
3802            if !valid {
3803                return Err(invalid_journal(
3804                    Path::new("<private-leaf-receipt-v1>"),
3805                    "in-flight private receipt tuple disagrees with the program or journal",
3806                ));
3807            }
3808            admitted.insert(OsString::from(private_receipt_name(
3809                operation_index,
3810                direction,
3811            )));
3812        }
3813    }
3814
3815    for (operation_index, expected_sha256) in current.abort_receipt_records() {
3816        let name = private_abort_receipt_name(operation_index);
3817        let path = transaction.private.receipts.display_path(OsStr::new(&name));
3818        let receipt =
3819            load_private_abort_work_receipt(transaction, operation_index)?.ok_or_else(|| {
3820                invalid_journal(
3821                    &path,
3822                    "journal abort receipt has no matching private abort-work receipt",
3823                )
3824            })?;
3825        if receipt.encoded_sha256()? != expected_sha256 {
3826            return Err(invalid_journal(
3827                &path,
3828                "private abort-work receipt digest disagrees with the journal",
3829            ));
3830        }
3831        admitted.insert(OsString::from(name));
3832    }
3833
3834    if current.direction() == TransactionDirectionV1::Rollback
3835        && current.phase() == TransactionPhaseV1::RollbackRequested
3836        && let Some(operation_index) = current.in_flight_operation()
3837        && current.receipt_identity(operation_index).is_none()
3838        && current.abort_receipt_sha256(operation_index).is_none()
3839        && let Some(_receipt) = load_private_abort_work_receipt(transaction, operation_index)?
3840    {
3841        admitted.insert(OsString::from(private_abort_receipt_name(operation_index)));
3842    }
3843
3844    let actual = transaction
3845        .private
3846        .receipts
3847        .closed_regular_file_names(
3848            transaction
3849                .program
3850                .operation_count()
3851                .saturating_mul(3)
3852                .saturating_add(1),
3853        )?
3854        .into_iter()
3855        .collect::<BTreeSet<_>>();
3856    if actual != admitted {
3857        return Err(invalid_journal(
3858            Path::new("<private-leaf-receipt-v1>"),
3859            "private receipt set is ahead of or inconsistent with the durable journal",
3860        ));
3861    }
3862    Ok(())
3863}
3864
3865fn validate_private_abort_work_receipts(
3866    filesystem: &MigrationFilesystem,
3867    transaction: &PreparedTransactionV1,
3868) -> Result<()> {
3869    let current = transaction
3870        .generations
3871        .last()
3872        .ok_or_else(|| invalid_journal(Path::new("<transaction-v1>"), "journal is empty"))?;
3873    for (operation_index, expected_sha256) in current.abort_receipt_records() {
3874        let name = private_abort_receipt_name(operation_index);
3875        let path = transaction.private.receipts.display_path(OsStr::new(&name));
3876        let receipt =
3877            load_private_abort_work_receipt(transaction, operation_index)?.ok_or_else(|| {
3878                invalid_journal(
3879                    &path,
3880                    "journal abort receipt has no matching private abort-work receipt",
3881                )
3882            })?;
3883        if receipt.encoded_sha256()? != expected_sha256 {
3884            return Err(invalid_journal(
3885                &path,
3886                "journal abort receipt disagrees with its private exact bytes",
3887            ));
3888        }
3889        verify_private_abort_work_receipt(filesystem, transaction, operation_index, &receipt)?;
3890    }
3891    if current.direction() == TransactionDirectionV1::Rollback
3892        && current.phase() == TransactionPhaseV1::RollbackRequested
3893        && let Some(operation_index) = current.in_flight_operation()
3894        && current.receipt_identity(operation_index).is_none()
3895        && current.abort_receipt_sha256(operation_index).is_none()
3896        && let Some(receipt) = load_private_abort_work_receipt(transaction, operation_index)?
3897    {
3898        verify_private_abort_work_receipt(filesystem, transaction, operation_index, &receipt)?;
3899    }
3900    Ok(())
3901}
3902
3903fn append_transaction_v1_generation(
3904    filesystem: &MigrationFilesystem,
3905    transaction: &mut PreparedTransactionV1,
3906    generation: TransactionJournalGenerationV1,
3907) -> Result<()> {
3908    append_transaction_v1_generation_parts(
3909        filesystem,
3910        &transaction.program,
3911        &transaction.program_digest,
3912        &mut transaction.generations,
3913        &transaction.private,
3914        generation,
3915    )
3916}
3917
3918fn append_transaction_v1_generation_parts(
3919    filesystem: &MigrationFilesystem,
3920    program: &MutationProgramV1,
3921    program_digest: &str,
3922    generations: &mut Vec<TransactionJournalGenerationV1>,
3923    private: &PrivateTransactionV1,
3924    generation: TransactionJournalGenerationV1,
3925) -> Result<()> {
3926    validate_append(program, program_digest, generations, &generation)?;
3927    let journal_root = PathBuf::from(MIGRATIONS_DIR)
3928        .join(program.transaction_id())
3929        .join(TRANSACTION_DIRECTORY)
3930        .join("journal");
3931    let generation_name = generation.file_name();
3932    let quarantine_name = journal_generation_quarantine_name(generations.len());
3933    let path = journal_root.join(&generation_name);
3934    let bytes = generation.encode(&filesystem.display(&path))?;
3935    private
3936        .journal
3937        .publish_recoverable_new_via_uncommitted_write(
3938            &generation_name,
3939            JOURNAL_GENERATION_STAGING_NAME,
3940            JOURNAL_GENERATION_WRITE_NAME,
3941            &quarantine_name,
3942            &bytes,
3943        )?;
3944    let reopened_bytes = private
3945        .journal
3946        .read_regular_bounded(OsStr::new(&generation_name), MAX_JOURNAL_GENERATION_BYTES)?;
3947    let reopened =
3948        TransactionJournalGenerationV1::decode(&filesystem.display(&path), &reopened_bytes)?;
3949    if reopened != generation {
3950        return Err(FolderbaseError::MigrationVerificationFailed(
3951            filesystem.display(&path),
3952        ));
3953    }
3954    generations.push(reopened);
3955    validate_chain(program, program_digest, generations)
3956}
3957
3958fn transaction_v1_journal_path(migration_id: &str) -> PathBuf {
3959    PathBuf::from(MIGRATIONS_DIR)
3960        .join(migration_id)
3961        .join(TRANSACTION_DIRECTORY)
3962        .join("journal")
3963}
3964
3965fn transaction_v1_result(
3966    filesystem: &MigrationFilesystem,
3967    transaction: &PreparedTransactionV1,
3968    state: MigrationState,
3969) -> MigrationResult {
3970    MigrationResult {
3971        migration_id: transaction.program.transaction_id().to_owned(),
3972        root: filesystem.display_root().to_path_buf(),
3973        state,
3974        created_paths: transaction.program.created_paths(),
3975        journal_path: transaction_v1_journal_path(transaction.program.transaction_id()),
3976    }
3977}
3978
3979#[allow(clippy::too_many_arguments)]
3980fn prepare_journal_bound_private_publish_claim(
3981    filesystem: &MigrationFilesystem,
3982    program: &MutationProgramV1,
3983    program_digest: &str,
3984    generations: &mut Vec<TransactionJournalGenerationV1>,
3985    private: &PrivateTransactionV1,
3986    operation_index: usize,
3987    direction: TransactionDirectionV1,
3988    blob: ProgramPrivateBlobV1<'_>,
3989    claim_name: &str,
3990    checkpoint: &mut impl FnMut(TransactionV1Checkpoint),
3991) -> Result<MigrationRegularFact> {
3992    let binding = match generations
3993        .last()
3994        .and_then(TransactionJournalGenerationV1::active_publication)
3995        .cloned()
3996    {
3997        Some(binding) => {
3998            if binding.operation_index() != operation_index
3999                || binding.direction() != direction
4000                || binding.claim_name() != claim_name
4001            {
4002                return Err(invalid_journal(
4003                    Path::new("<migration-journal-v1>"),
4004                    "active private publication does not match the requested claim",
4005                ));
4006            }
4007            binding
4008        }
4009        None => {
4010            let staged = filesystem.stage_new_private_publish_claim(
4011                match blob.directory {
4012                    "stages" => &private.stages,
4013                    "snapshots" => &private.snapshots,
4014                    _ => {
4015                        return Err(invalid_journal(
4016                            Path::new("<mutation-program-v1>"),
4017                            "program blob names an unsupported private directory",
4018                        ));
4019                    }
4020                },
4021                blob.name,
4022                &private.claims,
4023                claim_name,
4024                blob.sha256,
4025                blob.bytes,
4026                blob.fidelity.read_only,
4027                blob.fidelity.executable,
4028            )?;
4029            let binding = PrivatePublicationBindingV1::new(
4030                program.transaction_id().to_owned(),
4031                program_digest.to_owned(),
4032                operation_index,
4033                direction,
4034                claim_name.to_owned(),
4035                PrivatePublicationExactRegularFactV1::new(&staged.stage, staged.stage_sha256),
4036                PrivatePublicationExactRegularFactV1::new(
4037                    &staged.ownership_record,
4038                    staged.ownership_record_sha256,
4039                ),
4040            );
4041            let current = generations
4042                .last()
4043                .ok_or_else(|| invalid_journal(Path::new("<transaction-v1>"), "journal is empty"))?
4044                .clone();
4045            let bound = current.next_private_publication_bound(program, binding)?;
4046            append_transaction_v1_generation_parts(
4047                filesystem,
4048                program,
4049                program_digest,
4050                generations,
4051                private,
4052                bound,
4053            )?;
4054            checkpoint(TransactionV1Checkpoint::PrivatePublishClaimStaged(
4055                operation_index,
4056            ));
4057            generations
4058                .last()
4059                .and_then(TransactionJournalGenerationV1::active_publication)
4060                .cloned()
4061                .expect("the appended publication binding is the journal head")
4062        }
4063    };
4064    filesystem.install_private_publish_claim(
4065        &private.claims,
4066        claim_name,
4067        binding.stage().exact(1),
4068        binding.ownership_record().exact(1),
4069    )
4070}
4071
4072fn finish_receipted_private_publication(
4073    filesystem: &MigrationFilesystem,
4074    transaction: &mut PreparedTransactionV1,
4075    checkpoint: &mut impl FnMut(TransactionV1Checkpoint),
4076) -> Result<bool> {
4077    let current = transaction
4078        .generations
4079        .last()
4080        .ok_or_else(|| invalid_journal(Path::new("<transaction-v1>"), "journal is empty"))?
4081        .clone();
4082    let Some(binding) = current.active_publication().cloned() else {
4083        return Ok(false);
4084    };
4085    let operation_index = binding.operation_index();
4086    if !private_publication_is_receipted(&current, &binding) {
4087        return Ok(false);
4088    }
4089    filesystem.retire_journal_bound_private_publication(
4090        &transaction.private.claims,
4091        binding.claim_name(),
4092        binding.ownership_record().exact(1),
4093    )?;
4094    checkpoint(TransactionV1Checkpoint::PrivatePublicationOwnershipRetired(
4095        operation_index,
4096    ));
4097    let cleared = current.next_private_publication_cleared(&transaction.program)?;
4098    append_transaction_v1_generation(filesystem, transaction, cleared)?;
4099    Ok(true)
4100}
4101
4102fn regular_fact_matches_program(
4103    filesystem: &MigrationFilesystem,
4104    path: &Path,
4105    expected_identity: Option<&str>,
4106    expected_bytes: u64,
4107    expected_sha256: &str,
4108    expected_read_only: bool,
4109    expected_executable: bool,
4110) -> Result<Option<String>> {
4111    let Some(metadata) = filesystem.metadata(path)? else {
4112        return Ok(None);
4113    };
4114    if !metadata.is_file() || metadata.file_type().is_symlink() {
4115        return Ok(None);
4116    }
4117    let fact = match filesystem.regular_fact_with_sha256(path, Some(expected_sha256)) {
4118        Ok(fact) => fact,
4119        Err(FolderbaseError::MigrationSourceChanged(_)) => return Ok(None),
4120        Err(error) => return Err(error),
4121    };
4122    let fidelity = transaction_v1::ProgramFidelityV1 {
4123        read_only: fact.read_only,
4124        executable: regular_fact_executable(&fact),
4125    };
4126    if fact.bytes == expected_bytes
4127        && expected_identity.is_none_or(|identity| identity == fact.physical_identity_sha256)
4128        && fidelity.read_only == expected_read_only
4129        && fidelity.executable == expected_executable
4130    {
4131        Ok(Some(fact.physical_identity_sha256))
4132    } else {
4133        Ok(None)
4134    }
4135}
4136
4137fn require_program_absent(
4138    filesystem: &MigrationFilesystem,
4139    target: ProgramAbsentLeafV1<'_>,
4140) -> Result<()> {
4141    if filesystem.metadata(target.path)?.is_some() {
4142        return Err(FolderbaseError::WouldOverwrite(
4143            filesystem.display(target.path),
4144        ));
4145    }
4146    let parent = target.path.parent().unwrap_or_else(|| Path::new(""));
4147    for name in filesystem.directory_entry_names(parent, 65_536)? {
4148        if portable_path_key(Path::new(&name))
4149            == portable_path_key(Path::new(target.path.file_name().ok_or_else(|| {
4150                invalid_journal(target.path, "program target has no leaf name")
4151            })?))
4152        {
4153            return Err(FolderbaseError::WouldOverwrite(
4154                filesystem.display(target.path),
4155            ));
4156        }
4157    }
4158    Ok(())
4159}
4160
4161fn transaction_v1_environment_path(step: ProgramStepV1<'_>) -> Option<&Path> {
4162    let path = match step {
4163        ProgramStepV1::CreateDirectory { .. } => return None,
4164        ProgramStepV1::CreateFile { target, .. } => target.path,
4165        ProgramStepV1::ReplaceFile { target, .. } => target.path,
4166        ProgramStepV1::MoveFile { source, .. } => source.path,
4167    };
4168    matches!(
4169        path,
4170        path if path == Path::new(".folderbase/manifest.json")
4171            || path == Path::new(".folderbaseignore")
4172    )
4173    .then_some(path)
4174}
4175
4176fn transaction_v1_post_environment_matches(
4177    filesystem: &MigrationFilesystem,
4178    step: ProgramStepV1<'_>,
4179    expected_identity: &str,
4180) -> Result<bool> {
4181    let (path, image) = match step {
4182        ProgramStepV1::CreateFile { target, image } => (target.path, image),
4183        ProgramStepV1::ReplaceFile { target, image, .. } => (target.path, image),
4184        _ => return Ok(false),
4185    };
4186    Ok(regular_fact_matches_program(
4187        filesystem,
4188        path,
4189        Some(expected_identity),
4190        image.bytes,
4191        image.sha256,
4192        image.fidelity.read_only,
4193        image.fidelity.executable,
4194    )?
4195    .is_some())
4196}
4197
4198fn transaction_v1_pre_environment_matches(
4199    filesystem: &MigrationFilesystem,
4200    step: ProgramStepV1<'_>,
4201    expected_identity: &str,
4202) -> Result<bool> {
4203    let target = match step {
4204        ProgramStepV1::ReplaceFile { target, .. } => target,
4205        _ => return Ok(false),
4206    };
4207    Ok(regular_fact_matches_program(
4208        filesystem,
4209        target.path,
4210        Some(expected_identity),
4211        target.bytes,
4212        target.sha256,
4213        target.fidelity.read_only,
4214        target.fidelity.executable,
4215    )?
4216    .is_some())
4217}
4218
4219fn transaction_v1_private_regular_claim(
4220    transaction: &PreparedTransactionV1,
4221    operation_index: usize,
4222    kind: &str,
4223    expected_sha256: &str,
4224    expected_bytes: u64,
4225) -> Result<Option<MigrationRegularFact>> {
4226    let name = private_claim_name(operation_index, kind);
4227    match transaction
4228        .private
4229        .claims
4230        .relaxed_regular_fact(OsStr::new(&name), expected_sha256)
4231    {
4232        Ok(fact) if fact.bytes == expected_bytes => Ok(Some(fact)),
4233        Ok(_) => Err(FolderbaseError::MigrationVerificationFailed(
4234            transaction.private.claims.display_path(OsStr::new(&name)),
4235        )),
4236        Err(FolderbaseError::Io { source, .. })
4237            if source.kind() == std::io::ErrorKind::NotFound =>
4238        {
4239            Ok(None)
4240        }
4241        Err(error) => Err(error),
4242    }
4243}
4244
4245fn validate_transaction_v1_environment_leaf(
4246    filesystem: &MigrationFilesystem,
4247    transaction: &PreparedTransactionV1,
4248    current: &TransactionJournalGenerationV1,
4249    path: &Path,
4250) -> Result<()> {
4251    let current_environment_operation = match current.in_flight_operation() {
4252        Some(index) => {
4253            let step = transaction.program.step(index)?;
4254            (transaction_v1_environment_path(step) == Some(path)).then_some((index, step))
4255        }
4256        None => None,
4257    };
4258
4259    if let Some((operation_index, step)) = current_environment_operation {
4260        match (current.direction(), step) {
4261            (TransactionDirectionV1::Apply, ProgramStepV1::ReplaceFile { target, image, .. }) => {
4262                let source = transaction_v1_private_regular_claim(
4263                    transaction,
4264                    operation_index,
4265                    "source",
4266                    target.sha256,
4267                    target.bytes,
4268                )?;
4269                let Some(source) = source else {
4270                    return transaction
4271                        .program
4272                        .validate_initial_environment_leaf(filesystem, path);
4273                };
4274                if source.physical_identity_sha256 != target.physical_identity_sha256 {
4275                    return Err(FolderbaseError::MigrationVerificationFailed(
4276                        transaction
4277                            .private
4278                            .claims
4279                            .display_path(OsStr::new(&private_claim_name(
4280                                operation_index,
4281                                "source",
4282                            ))),
4283                    ));
4284                }
4285                let publish =
4286                    transaction_v1_private_regular_claim(
4287                        transaction,
4288                        operation_index,
4289                        "publish",
4290                        image.sha256,
4291                        image.bytes,
4292                    )?
4293                    .ok_or_else(|| {
4294                        FolderbaseError::MigrationVerificationFailed(
4295                            transaction.private.claims.display_path(OsStr::new(
4296                                &private_claim_name(operation_index, "publish"),
4297                            )),
4298                        )
4299                    })?;
4300                if let Some(receipt) = load_private_leaf_receipt(
4301                    transaction,
4302                    operation_index,
4303                    PrivateReceiptDirectionV1::Apply,
4304                )? {
4305                    if receipt.before_identity_sha256.as_deref()
4306                        != Some(target.physical_identity_sha256)
4307                        || receipt.after_identity_sha256.as_deref()
4308                            != Some(publish.physical_identity_sha256.as_str())
4309                    {
4310                        return Err(FolderbaseError::MigrationVerificationFailed(
4311                            transaction.private.receipts.display_path(OsStr::new(
4312                                &private_receipt_name(
4313                                    operation_index,
4314                                    PrivateReceiptDirectionV1::Apply,
4315                                ),
4316                            )),
4317                        ));
4318                    }
4319                    return require_environment_match(
4320                        filesystem,
4321                        path,
4322                        transaction_v1_post_environment_matches(
4323                            filesystem,
4324                            step,
4325                            &publish.physical_identity_sha256,
4326                        )?,
4327                    );
4328                }
4329                if filesystem.metadata(path)?.is_none() {
4330                    return Ok(());
4331                }
4332                return require_environment_match(
4333                    filesystem,
4334                    path,
4335                    transaction_v1_post_environment_matches(
4336                        filesystem,
4337                        step,
4338                        &publish.physical_identity_sha256,
4339                    )?,
4340                );
4341            }
4342            (
4343                TransactionDirectionV1::Rollback,
4344                ProgramStepV1::ReplaceFile { target, image, .. },
4345            ) => {
4346                let applied_identity =
4347                    current.receipt_identity(operation_index).ok_or_else(|| {
4348                        invalid_journal(path, "rollback environment step has no apply identity")
4349                    })?;
4350                if let Some(receipt) = load_private_leaf_receipt(
4351                    transaction,
4352                    operation_index,
4353                    PrivateReceiptDirectionV1::Rollback,
4354                )? {
4355                    let restored_identity =
4356                        receipt.after_identity_sha256.as_deref().ok_or_else(|| {
4357                            invalid_journal(
4358                                Path::new("<private-leaf-receipt-v1>"),
4359                                "environment rollback receipt has no restored identity",
4360                            )
4361                        })?;
4362                    if receipt.before_identity_sha256.as_deref() != Some(applied_identity) {
4363                        return Err(FolderbaseError::MigrationVerificationFailed(
4364                            transaction.private.receipts.display_path(OsStr::new(
4365                                &private_receipt_name(
4366                                    operation_index,
4367                                    PrivateReceiptDirectionV1::Rollback,
4368                                ),
4369                            )),
4370                        ));
4371                    }
4372                    return require_environment_match(
4373                        filesystem,
4374                        path,
4375                        transaction_v1_pre_environment_matches(
4376                            filesystem,
4377                            step,
4378                            restored_identity,
4379                        )?,
4380                    );
4381                }
4382                if let Some(restore) = transaction_v1_private_regular_claim(
4383                    transaction,
4384                    operation_index,
4385                    "restore",
4386                    target.sha256,
4387                    target.bytes,
4388                )? {
4389                    if filesystem.metadata(path)?.is_none() {
4390                        return Ok(());
4391                    }
4392                    return require_environment_match(
4393                        filesystem,
4394                        path,
4395                        transaction_v1_pre_environment_matches(
4396                            filesystem,
4397                            step,
4398                            &restore.physical_identity_sha256,
4399                        )?,
4400                    );
4401                }
4402                if let Some(rollback) = transaction_v1_private_regular_claim(
4403                    transaction,
4404                    operation_index,
4405                    "rollback",
4406                    image.sha256,
4407                    image.bytes,
4408                )? {
4409                    if rollback.physical_identity_sha256 != applied_identity {
4410                        return Err(FolderbaseError::MigrationVerificationFailed(
4411                            transaction.private.claims.display_path(OsStr::new(
4412                                &private_claim_name(operation_index, "rollback"),
4413                            )),
4414                        ));
4415                    }
4416                    return if filesystem.metadata(path)?.is_none() {
4417                        Ok(())
4418                    } else {
4419                        Err(FolderbaseError::MigrationSourceChanged(
4420                            filesystem.display(path),
4421                        ))
4422                    };
4423                }
4424                return require_environment_match(
4425                    filesystem,
4426                    path,
4427                    transaction_v1_post_environment_matches(filesystem, step, applied_identity)?,
4428                );
4429            }
4430            _ => {}
4431        }
4432        return Err(FolderbaseError::MigrationSourceChanged(
4433            filesystem.display(path),
4434        ));
4435    }
4436
4437    let inverse_records = current.inverse_receipt_records();
4438    let inverse = inverse_records
4439        .iter()
4440        .map(|(index, _)| *index)
4441        .collect::<BTreeSet<_>>();
4442    for (operation_index, expected_identity) in current.apply_receipt_records().into_iter().rev() {
4443        if inverse.contains(&operation_index) {
4444            continue;
4445        }
4446        let step = transaction.program.step(operation_index)?;
4447        if transaction_v1_environment_path(step) != Some(path) {
4448            continue;
4449        }
4450        let expected_identity = expected_identity.ok_or_else(|| {
4451            invalid_journal(
4452                path,
4453                "environment replacement has no durable published identity",
4454            )
4455        })?;
4456        if transaction_v1_post_environment_matches(filesystem, step, &expected_identity)? {
4457            return Ok(());
4458        }
4459        return Err(FolderbaseError::MigrationSourceChanged(
4460            filesystem.display(path),
4461        ));
4462    }
4463
4464    for (operation_index, restored_identity) in inverse_records.into_iter().rev() {
4465        let step = transaction.program.step(operation_index)?;
4466        if transaction_v1_environment_path(step) != Some(path) {
4467            continue;
4468        }
4469        let restored_identity = restored_identity.ok_or_else(|| {
4470            invalid_journal(
4471                path,
4472                "environment rollback has no durable restored identity",
4473            )
4474        })?;
4475        if transaction_v1_pre_environment_matches(filesystem, step, &restored_identity)? {
4476            return Ok(());
4477        }
4478        return Err(FolderbaseError::MigrationSourceChanged(
4479            filesystem.display(path),
4480        ));
4481    }
4482
4483    transaction
4484        .program
4485        .validate_initial_environment_leaf(filesystem, path)
4486}
4487
4488fn require_environment_match(
4489    filesystem: &MigrationFilesystem,
4490    path: &Path,
4491    matches: bool,
4492) -> Result<()> {
4493    if matches {
4494        Ok(())
4495    } else {
4496        Err(FolderbaseError::MigrationSourceChanged(
4497            filesystem.display(path),
4498        ))
4499    }
4500}
4501
4502fn validate_transaction_v1_environment(
4503    filesystem: &MigrationFilesystem,
4504    transaction: &PreparedTransactionV1,
4505    current: &TransactionJournalGenerationV1,
4506) -> Result<()> {
4507    transaction.program.validate_root_and_state(filesystem)?;
4508    validate_transaction_v1_environment_leaf(
4509        filesystem,
4510        transaction,
4511        current,
4512        Path::new(".folderbase/manifest.json"),
4513    )?;
4514    validate_transaction_v1_environment_leaf(
4515        filesystem,
4516        transaction,
4517        current,
4518        Path::new(".folderbaseignore"),
4519    )
4520}
4521
4522fn apply_transaction_v1_step(
4523    filesystem: &MigrationFilesystem,
4524    transaction: &mut PreparedTransactionV1,
4525    operation_index: usize,
4526    checkpoint: &mut impl FnMut(TransactionV1Checkpoint),
4527) -> Result<Option<String>> {
4528    let current = transaction
4529        .generations
4530        .last()
4531        .ok_or_else(|| invalid_journal(Path::new("<transaction-v1>"), "journal is empty"))?
4532        .clone();
4533    validate_transaction_v1_environment(filesystem, transaction, &current)?;
4534    let retained_parents =
4535        transaction
4536            .program
4537            .retain_step_parents(filesystem, operation_index, &current)?;
4538    let validate_parents = |transaction: &PreparedTransactionV1| {
4539        let current = transaction
4540            .generations
4541            .last()
4542            .ok_or_else(|| invalid_journal(Path::new("<transaction-v1>"), "journal is empty"))?;
4543        validate_transaction_v1_environment(filesystem, transaction, current)?;
4544        transaction
4545            .program
4546            .validate_step_parents(filesystem, operation_index, current)
4547    };
4548    validate_parents(transaction)?;
4549    if let ProgramStepV1::CreateDirectory { target, fidelity } =
4550        transaction.program.step(operation_index)?
4551    {
4552        let claim_name = private_claim_name(operation_index, "publish");
4553        let receipt = match load_private_leaf_receipt(
4554            transaction,
4555            operation_index,
4556            PrivateReceiptDirectionV1::Apply,
4557        )? {
4558            Some(receipt) => receipt,
4559            None => {
4560                let claim = transaction.private.claims.prepare_directory_claim(
4561                    &claim_name,
4562                    fidelity.read_only,
4563                    fidelity.executable,
4564                )?;
4565                checkpoint(TransactionV1Checkpoint::ClaimComplete(operation_index));
4566                let receipt = PrivateLeafReceiptV1::new(
4567                    transaction,
4568                    operation_index,
4569                    PrivateReceiptDirectionV1::Apply,
4570                    None,
4571                    Some(claim.physical_identity_sha256),
4572                )?;
4573                persist_private_leaf_receipt(transaction, &receipt)?;
4574                receipt
4575            }
4576        };
4577        let expected_identity = receipt.after_identity_sha256.as_deref().ok_or_else(|| {
4578            invalid_journal(
4579                Path::new("<private-leaf-receipt-v1>"),
4580                "directory apply receipt has no published identity",
4581            )
4582        })?;
4583        let visible_matches = match filesystem.directory_fact(target.path) {
4584            Ok(fact) => fact.physical_identity_sha256 == expected_identity,
4585            Err(FolderbaseError::Io { source, .. })
4586                if source.kind() == std::io::ErrorKind::NotFound =>
4587            {
4588                false
4589            }
4590            Err(error) => return Err(error),
4591        };
4592        if !visible_matches {
4593            if filesystem.metadata(target.path)?.is_none() {
4594                require_program_absent(filesystem, target)?;
4595            }
4596            validate_parents(transaction)?;
4597            checkpoint(TransactionV1Checkpoint::ParentsRevalidatedBeforePublish(
4598                operation_index,
4599            ));
4600            let destination_name = target
4601                .path
4602                .file_name()
4603                .ok_or_else(|| invalid_journal(target.path, "program target has no leaf name"))?;
4604            filesystem.publish_private_directory_claim_new_through(
4605                &transaction.private.claims,
4606                OsStr::new(&claim_name),
4607                retained_parents.get(target.parent)?,
4608                destination_name,
4609                expected_identity,
4610            )?;
4611        }
4612        checkpoint(TransactionV1Checkpoint::VisiblePublishComplete(
4613            operation_index,
4614        ));
4615        validate_parents(transaction)?;
4616        let fact = filesystem.directory_fact(target.path)?;
4617        let read_only = fact.read_only;
4618        let executable = directory_fact_executable(&fact);
4619        if fact.physical_identity_sha256 != expected_identity
4620            || read_only != fidelity.read_only
4621            || executable != fidelity.executable
4622        {
4623            return Err(FolderbaseError::MigrationVerificationFailed(
4624                filesystem.display(target.path),
4625            ));
4626        }
4627        checkpoint(TransactionV1Checkpoint::PrivateApplyReceiptPersisted(
4628            operation_index,
4629        ));
4630        return Ok(receipt.after_identity_sha256);
4631    }
4632    if let Some(receipt) = load_private_leaf_receipt(
4633        transaction,
4634        operation_index,
4635        PrivateReceiptDirectionV1::Apply,
4636    )? {
4637        verify_apply_private_receipt(filesystem, transaction, operation_index, &receipt)?;
4638        return Ok(receipt.after_identity_sha256);
4639    }
4640    let (before_identity, after_identity) = match transaction.program.step(operation_index)? {
4641        ProgramStepV1::CreateDirectory { .. } => unreachable!("handled before regular leaves"),
4642        ProgramStepV1::CreateFile { target, image } => {
4643            let claim_name = private_claim_name(operation_index, "publish");
4644            let claim = prepare_journal_bound_private_publish_claim(
4645                filesystem,
4646                &transaction.program,
4647                &transaction.program_digest,
4648                &mut transaction.generations,
4649                &transaction.private,
4650                operation_index,
4651                TransactionDirectionV1::Apply,
4652                image,
4653                &claim_name,
4654                checkpoint,
4655            )?;
4656            checkpoint(TransactionV1Checkpoint::ClaimComplete(operation_index));
4657            if filesystem.metadata(target.path)?.is_none() {
4658                require_program_absent(filesystem, target)?;
4659            }
4660            validate_parents(transaction)?;
4661            checkpoint(TransactionV1Checkpoint::ParentsRevalidatedBeforePublish(
4662                operation_index,
4663            ));
4664            let destination_name = target
4665                .path
4666                .file_name()
4667                .ok_or_else(|| invalid_journal(target.path, "program target has no leaf name"))?;
4668            let published = filesystem.publish_private_claim_new_through(
4669                &transaction.private.claims,
4670                OsStr::new(&claim_name),
4671                retained_parents.get(target.parent)?,
4672                destination_name,
4673                &claim.physical_identity_sha256,
4674                image.sha256,
4675                image.bytes,
4676            )?;
4677            checkpoint(TransactionV1Checkpoint::VisiblePublishComplete(
4678                operation_index,
4679            ));
4680            validate_parents(transaction)?;
4681            (None, Some(published.physical_identity_sha256))
4682        }
4683        ProgramStepV1::ReplaceFile { target, image, .. } => {
4684            let publish_name = private_claim_name(operation_index, "publish");
4685            let publish_claim = prepare_journal_bound_private_publish_claim(
4686                filesystem,
4687                &transaction.program,
4688                &transaction.program_digest,
4689                &mut transaction.generations,
4690                &transaction.private,
4691                operation_index,
4692                TransactionDirectionV1::Apply,
4693                image,
4694                &publish_name,
4695                checkpoint,
4696            )?;
4697            checkpoint(TransactionV1Checkpoint::ReplacePublishClaimPrepared(
4698                operation_index,
4699            ));
4700            let source_name = private_claim_name(operation_index, "source");
4701            let source_leaf_name = target
4702                .path
4703                .file_name()
4704                .ok_or_else(|| invalid_journal(target.path, "program target has no leaf name"))?;
4705            let existing_source = if filesystem.metadata(target.path)?.is_some() {
4706                let published_link_count = target.link_count.checked_add(1).ok_or_else(|| {
4707                    FolderbaseError::MigrationSourceChanged(filesystem.display(target.path))
4708                })?;
4709                ExactExistingClaimSource::Regular(ExactRegularLeaf {
4710                    physical_identity_sha256: &publish_claim.physical_identity_sha256,
4711                    device_sha256: target.device_sha256,
4712                    bytes: image.bytes,
4713                    sha256: image.sha256,
4714                    read_only: image.fidelity.read_only,
4715                    executable: image.fidelity.executable,
4716                    link_count: published_link_count,
4717                })
4718            } else {
4719                ExactExistingClaimSource::Absent
4720            };
4721            validate_parents(transaction)?;
4722            let source_claim = match filesystem.claim_exact_leaf_through(ExactLeafClaimRequest {
4723                source_parent: retained_parents.get(target.parent)?,
4724                source_name: source_leaf_name,
4725                destination: &transaction.private.claims,
4726                destination_name: &source_name,
4727                expectation: ExactLeafClaimExpectation::Regular(ExactRegularLeaf {
4728                    physical_identity_sha256: target.physical_identity_sha256,
4729                    device_sha256: target.device_sha256,
4730                    bytes: target.bytes,
4731                    sha256: target.sha256,
4732                    read_only: target.fidelity.read_only,
4733                    executable: target.fidelity.executable,
4734                    link_count: target.link_count,
4735                }),
4736                existing_source,
4737            })? {
4738                ExactLeafClaimResult::Regular(fact) => fact,
4739                ExactLeafClaimResult::Directory(_) => {
4740                    return Err(FolderbaseError::MigrationVerificationFailed(
4741                        transaction
4742                            .private
4743                            .claims
4744                            .display_path(OsStr::new(&source_name)),
4745                    ));
4746                }
4747            };
4748            checkpoint(TransactionV1Checkpoint::ClaimComplete(operation_index));
4749            validate_parents(transaction)?;
4750            checkpoint(TransactionV1Checkpoint::ParentsRevalidatedBeforePublish(
4751                operation_index,
4752            ));
4753            let destination_name = target
4754                .path
4755                .file_name()
4756                .ok_or_else(|| invalid_journal(target.path, "program target has no leaf name"))?;
4757            let published = filesystem.publish_private_claim_new_through(
4758                &transaction.private.claims,
4759                OsStr::new(&publish_name),
4760                retained_parents.get(target.parent)?,
4761                destination_name,
4762                &publish_claim.physical_identity_sha256,
4763                image.sha256,
4764                image.bytes,
4765            )?;
4766            checkpoint(TransactionV1Checkpoint::VisiblePublishComplete(
4767                operation_index,
4768            ));
4769            validate_parents(transaction)?;
4770            (
4771                Some(source_claim.physical_identity_sha256),
4772                Some(published.physical_identity_sha256),
4773            )
4774        }
4775        ProgramStepV1::MoveFile {
4776            source,
4777            destination,
4778            ..
4779        } => {
4780            let source_name = private_claim_name(operation_index, "source");
4781            let source_leaf_name = source
4782                .path
4783                .file_name()
4784                .ok_or_else(|| invalid_journal(source.path, "program source has no leaf name"))?;
4785            let destination_is_published = regular_fact_matches_program(
4786                filesystem,
4787                destination.path,
4788                Some(source.physical_identity_sha256),
4789                source.bytes,
4790                source.sha256,
4791                source.fidelity.read_only,
4792                source.fidelity.executable,
4793            )?
4794            .is_some();
4795            let expected_claim_link_count = if destination_is_published {
4796                source.link_count.checked_add(1).ok_or_else(|| {
4797                    FolderbaseError::MigrationSourceChanged(filesystem.display(source.path))
4798                })?
4799            } else {
4800                source.link_count
4801            };
4802            if destination_is_published {
4803                transaction.private.claims.exact_regular_fact(
4804                    OsStr::new(&source_name),
4805                    ExactRegularLeaf {
4806                        physical_identity_sha256: source.physical_identity_sha256,
4807                        device_sha256: source.device_sha256,
4808                        bytes: source.bytes,
4809                        sha256: source.sha256,
4810                        read_only: source.fidelity.read_only,
4811                        executable: source.fidelity.executable,
4812                        link_count: expected_claim_link_count,
4813                    },
4814                )?;
4815            }
4816            validate_parents(transaction)?;
4817            let source_claim = match filesystem.claim_exact_leaf_through(ExactLeafClaimRequest {
4818                source_parent: retained_parents.get(source.parent)?,
4819                source_name: source_leaf_name,
4820                destination: &transaction.private.claims,
4821                destination_name: &source_name,
4822                expectation: ExactLeafClaimExpectation::Regular(ExactRegularLeaf {
4823                    physical_identity_sha256: source.physical_identity_sha256,
4824                    device_sha256: source.device_sha256,
4825                    bytes: source.bytes,
4826                    sha256: source.sha256,
4827                    read_only: source.fidelity.read_only,
4828                    executable: source.fidelity.executable,
4829                    link_count: expected_claim_link_count,
4830                }),
4831                existing_source: ExactExistingClaimSource::Absent,
4832            })? {
4833                ExactLeafClaimResult::Regular(fact) => fact,
4834                ExactLeafClaimResult::Directory(_) => {
4835                    return Err(FolderbaseError::MigrationVerificationFailed(
4836                        transaction
4837                            .private
4838                            .claims
4839                            .display_path(OsStr::new(&source_name)),
4840                    ));
4841                }
4842            };
4843            checkpoint(TransactionV1Checkpoint::ClaimComplete(operation_index));
4844            if filesystem.metadata(destination.path)?.is_none() {
4845                require_program_absent(filesystem, destination)?;
4846            }
4847            validate_parents(transaction)?;
4848            checkpoint(TransactionV1Checkpoint::ParentsRevalidatedBeforePublish(
4849                operation_index,
4850            ));
4851            let destination_name = destination.path.file_name().ok_or_else(|| {
4852                invalid_journal(destination.path, "program destination has no leaf name")
4853            })?;
4854            let published = filesystem.publish_private_claim_new_through(
4855                &transaction.private.claims,
4856                OsStr::new(&source_name),
4857                retained_parents.get(destination.parent)?,
4858                destination_name,
4859                &source_claim.physical_identity_sha256,
4860                source.sha256,
4861                source.bytes,
4862            )?;
4863            checkpoint(TransactionV1Checkpoint::VisiblePublishComplete(
4864                operation_index,
4865            ));
4866            validate_parents(transaction)?;
4867            (
4868                Some(source_claim.physical_identity_sha256),
4869                Some(published.physical_identity_sha256),
4870            )
4871        }
4872    };
4873    let receipt = PrivateLeafReceiptV1::new(
4874        transaction,
4875        operation_index,
4876        PrivateReceiptDirectionV1::Apply,
4877        before_identity,
4878        after_identity.clone(),
4879    )?;
4880    persist_private_leaf_receipt(transaction, &receipt)?;
4881    checkpoint(TransactionV1Checkpoint::PrivateApplyReceiptPersisted(
4882        operation_index,
4883    ));
4884    Ok(after_identity)
4885}
4886
4887fn verify_apply_private_receipt(
4888    filesystem: &MigrationFilesystem,
4889    transaction: &PreparedTransactionV1,
4890    operation_index: usize,
4891    receipt: &PrivateLeafReceiptV1,
4892) -> Result<()> {
4893    let expected_identity = receipt.after_identity_sha256.as_deref().ok_or_else(|| {
4894        invalid_journal(
4895            Path::new("<private-leaf-receipt-v1>"),
4896            "apply receipt has no published identity",
4897        )
4898    })?;
4899    match transaction.program.step(operation_index)? {
4900        ProgramStepV1::CreateDirectory { target, fidelity } => {
4901            filesystem.exact_directory_fact(
4902                target.path,
4903                ExactDirectoryLeaf {
4904                    physical_identity_sha256: expected_identity,
4905                    device_sha256: target.device_sha256,
4906                    read_only: fidelity.read_only,
4907                    executable: fidelity.executable,
4908                },
4909                false,
4910            )?;
4911        }
4912        ProgramStepV1::CreateFile { target, image } => {
4913            let expected = ExactRegularLeaf {
4914                physical_identity_sha256: expected_identity,
4915                device_sha256: target.device_sha256,
4916                bytes: image.bytes,
4917                sha256: image.sha256,
4918                read_only: image.fidelity.read_only,
4919                executable: image.fidelity.executable,
4920                link_count: 2,
4921            };
4922            filesystem.exact_regular_fact(target.path, expected)?;
4923            transaction.private.claims.exact_regular_fact(
4924                OsStr::new(&private_claim_name(operation_index, "publish")),
4925                expected,
4926            )?;
4927        }
4928        ProgramStepV1::ReplaceFile { target, image, .. } => {
4929            let published_link_count = target.link_count.checked_add(1).ok_or_else(|| {
4930                FolderbaseError::MigrationVerificationFailed(filesystem.display(target.path))
4931            })?;
4932            let published = ExactRegularLeaf {
4933                physical_identity_sha256: expected_identity,
4934                device_sha256: target.device_sha256,
4935                bytes: image.bytes,
4936                sha256: image.sha256,
4937                read_only: image.fidelity.read_only,
4938                executable: image.fidelity.executable,
4939                link_count: published_link_count,
4940            };
4941            filesystem.exact_regular_fact(target.path, published)?;
4942            transaction.private.claims.exact_regular_fact(
4943                OsStr::new(&private_claim_name(operation_index, "publish")),
4944                published,
4945            )?;
4946            transaction.private.claims.exact_regular_fact(
4947                OsStr::new(&private_claim_name(operation_index, "source")),
4948                ExactRegularLeaf {
4949                    physical_identity_sha256: target.physical_identity_sha256,
4950                    device_sha256: target.device_sha256,
4951                    bytes: target.bytes,
4952                    sha256: target.sha256,
4953                    read_only: target.fidelity.read_only,
4954                    executable: target.fidelity.executable,
4955                    link_count: target.link_count,
4956                },
4957            )?;
4958        }
4959        ProgramStepV1::MoveFile {
4960            source,
4961            destination,
4962            ..
4963        } => {
4964            if filesystem.metadata(source.path)?.is_some() {
4965                return Err(FolderbaseError::MigrationVerificationFailed(
4966                    filesystem.display(source.path),
4967                ));
4968            }
4969            let published_link_count = source.link_count.checked_add(1).ok_or_else(|| {
4970                FolderbaseError::MigrationVerificationFailed(filesystem.display(destination.path))
4971            })?;
4972            let published = ExactRegularLeaf {
4973                physical_identity_sha256: expected_identity,
4974                device_sha256: source.device_sha256,
4975                bytes: source.bytes,
4976                sha256: source.sha256,
4977                read_only: source.fidelity.read_only,
4978                executable: source.fidelity.executable,
4979                link_count: published_link_count,
4980            };
4981            filesystem.exact_regular_fact(destination.path, published)?;
4982            transaction.private.claims.exact_regular_fact(
4983                OsStr::new(&private_claim_name(operation_index, "source")),
4984                published,
4985            )?;
4986        }
4987    }
4988    Ok(())
4989}
4990
4991fn is_exact_create_directory_prepublication_receipt(
4992    transaction: &PreparedTransactionV1,
4993    operation_index: usize,
4994    receipt: &PrivateLeafReceiptV1,
4995) -> Result<bool> {
4996    let ProgramStepV1::CreateDirectory { target, fidelity } =
4997        transaction.program.step(operation_index)?
4998    else {
4999        return Ok(false);
5000    };
5001    let expected_identity = receipt.after_identity_sha256.as_deref().ok_or_else(|| {
5002        invalid_journal(
5003            Path::new("<private-leaf-receipt-v1>"),
5004            "directory apply receipt has no intended identity",
5005        )
5006    })?;
5007    if receipt.before_identity_sha256.is_some() {
5008        return Err(invalid_journal(
5009            Path::new("<private-leaf-receipt-v1>"),
5010            "directory apply receipt has an impossible source identity",
5011        ));
5012    }
5013    match transaction.private.claims.exact_empty_directory_fact(
5014        OsStr::new(&private_claim_name(operation_index, "publish")),
5015        ExactDirectoryLeaf {
5016            physical_identity_sha256: expected_identity,
5017            device_sha256: target.device_sha256,
5018            read_only: fidelity.read_only,
5019            executable: fidelity.executable,
5020        },
5021    ) {
5022        Ok(_) => Ok(true),
5023        Err(FolderbaseError::Io { source, .. })
5024            if source.kind() == std::io::ErrorKind::NotFound =>
5025        {
5026            Ok(false)
5027        }
5028        Err(error) => Err(error),
5029    }
5030}
5031
5032#[cfg(test)]
5033fn replace_abort_conflict_target_fact(
5034    filesystem: &MigrationFilesystem,
5035    target: transaction_v1::ProgramBoundRegularV1<'_>,
5036) -> Result<String> {
5037    filesystem
5038        .retained_nofollow_leaf_fingerprint(target.path)?
5039        .ok_or_else(|| FolderbaseError::MigrationSourceChanged(filesystem.display(target.path)))
5040}
5041
5042fn record_transaction_v1_conflict(
5043    filesystem: &MigrationFilesystem,
5044    transaction: &mut PreparedTransactionV1,
5045    operation_index: usize,
5046    error: &FolderbaseError,
5047) -> Result<()> {
5048    let mut affected_paths = match transaction.program.step(operation_index)? {
5049        ProgramStepV1::CreateDirectory { target, .. }
5050        | ProgramStepV1::CreateFile { target, .. } => vec![target.path.to_path_buf()],
5051        ProgramStepV1::ReplaceFile { target, .. } => vec![target.path.to_path_buf()],
5052        ProgramStepV1::MoveFile {
5053            source,
5054            destination,
5055            ..
5056        } => vec![source.path.to_path_buf(), destination.path.to_path_buf()],
5057    };
5058    let observed_path = match error {
5059        FolderbaseError::UnsafePath(path)
5060        | FolderbaseError::MigrationSourceChanged(path)
5061        | FolderbaseError::MigrationVerificationFailed(path)
5062        | FolderbaseError::WouldOverwrite(path)
5063        | FolderbaseError::RestoreNamespaceRepairRequired(path)
5064        | FolderbaseError::InvalidRecord { path, .. }
5065        | FolderbaseError::Io { path, .. }
5066        | FolderbaseError::Json { path, .. } => Some(path),
5067        _ => None,
5068    };
5069    if let Some(path) =
5070        observed_path.and_then(|path| program_relative_conflict_path(filesystem, path))
5071        && !affected_paths.iter().any(|affected| affected == &path)
5072    {
5073        affected_paths.push(path);
5074    }
5075    let step = transaction.program.step(operation_index)?;
5076    let ordinary_paths = match step {
5077        ProgramStepV1::CreateDirectory { target, .. }
5078        | ProgramStepV1::CreateFile { target, .. } => vec![target.path],
5079        ProgramStepV1::ReplaceFile { target, .. } => vec![target.path],
5080        ProgramStepV1::MoveFile {
5081            source,
5082            destination,
5083            ..
5084        } => vec![source.path, destination.path],
5085    };
5086    let mut ordinary_fingerprints = Vec::new();
5087    for path in ordinary_paths {
5088        if let Some(fingerprint) = filesystem.retained_nofollow_leaf_fingerprint(path)? {
5089            ordinary_fingerprints.push(format!("{}={fingerprint}", path.display()));
5090        }
5091    }
5092    let current = transaction
5093        .generations
5094        .last()
5095        .expect("transaction-v1 has a validated generation")
5096        .clone();
5097    let deduplicable = !ordinary_fingerprints.is_empty();
5098    let claim_entries = transaction.private.claims.closed_entries(
5099        transaction
5100            .program
5101            .operation_count()
5102            .saturating_mul(12)
5103            .saturating_add(1),
5104    )?;
5105    let preserved_artifact = match (current.direction(), step) {
5106        (
5107            TransactionDirectionV1::Rollback,
5108            ProgramStepV1::ReplaceFile {
5109                rollback_snapshot, ..
5110            },
5111        )
5112        | (
5113            TransactionDirectionV1::Rollback,
5114            ProgramStepV1::MoveFile {
5115                rollback_snapshot, ..
5116            },
5117        ) => Some(
5118            PathBuf::from(MIGRATIONS_DIR)
5119                .join(transaction.program.transaction_id())
5120                .join(TRANSACTION_DIRECTORY)
5121                .join(rollback_snapshot.directory)
5122                .join(rollback_snapshot.name),
5123        ),
5124        (_, ProgramStepV1::CreateDirectory { .. })
5125        | (_, ProgramStepV1::CreateFile { .. })
5126        | (_, ProgramStepV1::ReplaceFile { .. })
5127        | (_, ProgramStepV1::MoveFile { .. }) => ["rollback", "source", "publish", "restore"]
5128            .into_iter()
5129            .find_map(|kind| {
5130                let name = private_claim_name(operation_index, kind);
5131                claim_entries
5132                    .iter()
5133                    .find(|(entry, _)| entry == OsStr::new(&name))
5134                    .map(|(_, is_directory)| (name, *is_directory))
5135            })
5136            .map(|(name, is_directory)| {
5137                if is_directory {
5138                    let _ = transaction
5139                        .private
5140                        .claims
5141                        .relaxed_directory_fact(OsStr::new(&name))?;
5142                } else {
5143                    transaction
5144                        .private
5145                        .claims
5146                        .verify_relaxed_regular(OsStr::new(&name))?;
5147                }
5148                Ok::<_, FolderbaseError>(
5149                    PathBuf::from(MIGRATIONS_DIR)
5150                        .join(transaction.program.transaction_id())
5151                        .join(TRANSACTION_DIRECTORY)
5152                        .join("claims")
5153                        .join(name),
5154                )
5155            })
5156            .transpose()?,
5157    };
5158    let expected = "program-bound leaf state".to_owned();
5159    let observed = if ordinary_fingerprints.is_empty() {
5160        error.to_string()
5161    } else {
5162        format!(
5163            "{} [retained ordinary leaves: {}]",
5164            error,
5165            ordinary_fingerprints.join(", ")
5166        )
5167    };
5168    if deduplicable && current.phase() == TransactionPhaseV1::Conflicted {
5169        let duplicate = current.conflict_records().last().is_some_and(|conflict| {
5170            conflict.operation_index == Some(operation_index)
5171                && conflict.affected_paths == affected_paths
5172                && conflict.expected == expected
5173                && conflict.observed == observed
5174                && conflict.preserved_artifact == preserved_artifact
5175        });
5176        if duplicate {
5177            reconcile_plan_terminal(filesystem, &transaction.program, MigrationState::Conflicted);
5178            return Ok(());
5179        }
5180    }
5181    if current.conflict_records().len() >= transaction_v1::MAX_RETAINED_CONFLICTS {
5182        // Conflict evidence is deliberately bounded. Once the admitted budget
5183        // is full, preserve the last exact durable evidence and reserve the
5184        // remaining journal generations for a successful Apply and complete
5185        // Rollback.
5186        reconcile_plan_terminal(filesystem, &transaction.program, MigrationState::Conflicted);
5187        return Ok(());
5188    }
5189    let conflicted = current.next_conflicted(
5190        &transaction.program,
5191        Some(operation_index),
5192        affected_paths,
5193        expected,
5194        observed,
5195        preserved_artifact,
5196    )?;
5197    append_transaction_v1_generation(filesystem, transaction, conflicted)?;
5198    reconcile_plan_terminal(filesystem, &transaction.program, MigrationState::Conflicted);
5199    Ok(())
5200}
5201
5202fn program_relative_conflict_path(
5203    filesystem: &MigrationFilesystem,
5204    observed: &Path,
5205) -> Option<PathBuf> {
5206    let relative = if observed.is_absolute() {
5207        observed.strip_prefix(filesystem.display_root()).ok()?
5208    } else {
5209        observed
5210    };
5211    ensure_safe_relative(relative).ok()?;
5212    Some(relative.to_path_buf())
5213}
5214
5215fn is_private_transaction_integrity_error(error: &FolderbaseError) -> bool {
5216    let private_path = match error {
5217        FolderbaseError::UnsafePath(path)
5218        | FolderbaseError::MigrationSourceChanged(path)
5219        | FolderbaseError::MigrationVerificationFailed(path)
5220        | FolderbaseError::WouldOverwrite(path)
5221        | FolderbaseError::RestoreNamespaceRepairRequired(path)
5222        | FolderbaseError::InvalidRecord { path, .. }
5223        | FolderbaseError::Io { path, .. }
5224        | FolderbaseError::Json { path, .. } => Some(path),
5225        _ => None,
5226    };
5227    private_path.is_some_and(|path| {
5228        path.components()
5229            .any(|component| component.as_os_str() == OsStr::new(TRANSACTION_DIRECTORY))
5230            || path
5231                .to_string_lossy()
5232                .starts_with("<private-leaf-receipt-v1>")
5233            || path
5234                .to_string_lossy()
5235                .starts_with("<private-abort-work-receipt-v1>")
5236    })
5237}
5238
5239fn execute_transaction_v1_apply_with_hook(
5240    filesystem: &MigrationFilesystem,
5241    transaction: &mut PreparedTransactionV1,
5242    mut checkpoint: impl FnMut(TransactionV1Checkpoint),
5243) -> Result<MigrationResult> {
5244    filesystem.require_atomic_noreplace()?;
5245    loop {
5246        let current = transaction
5247            .generations
5248            .last()
5249            .expect("transaction-v1 has a validated generation")
5250            .clone();
5251        if finish_receipted_private_publication(filesystem, transaction, &mut checkpoint)? {
5252            continue;
5253        }
5254        if current.direction() == TransactionDirectionV1::Rollback {
5255            return Err(FolderbaseError::InvalidMigrationState {
5256                expected: MigrationState::Applying.as_str(),
5257                actual: "rolling_back".to_owned(),
5258            });
5259        }
5260        if current.phase() == TransactionPhaseV1::Applied {
5261            validate_transaction_v1_environment(filesystem, transaction, &current)?;
5262            for (index, _) in current.apply_receipt_records() {
5263                let receipt = load_private_leaf_receipt(
5264                    transaction,
5265                    index,
5266                    PrivateReceiptDirectionV1::Apply,
5267                )?
5268                .ok_or_else(|| {
5269                    let name = private_receipt_name(index, PrivateReceiptDirectionV1::Apply);
5270                    invalid_journal(
5271                        transaction.private.receipts.display_path(OsStr::new(&name)),
5272                        "completed apply operation has no private receipt",
5273                    )
5274                })?;
5275                if let Err(error) =
5276                    verify_apply_private_receipt(filesystem, transaction, index, &receipt)
5277                {
5278                    if is_private_transaction_integrity_error(&error) {
5279                        return Err(error);
5280                    }
5281                    record_transaction_v1_conflict(filesystem, transaction, index, &error)?;
5282                    checkpoint(TransactionV1Checkpoint::ConflictRecorded(index));
5283                    return Err(error);
5284                }
5285            }
5286            reconcile_plan_terminal(filesystem, &transaction.program, MigrationState::Verified);
5287            return Ok(transaction_v1_result(
5288                filesystem,
5289                transaction,
5290                MigrationState::Verified,
5291            ));
5292        }
5293        if let Some(index) = current.in_flight_operation() {
5294            let identity =
5295                match apply_transaction_v1_step(filesystem, transaction, index, &mut checkpoint) {
5296                    Ok(identity) => identity,
5297                    Err(error) => {
5298                        if is_private_transaction_integrity_error(&error) {
5299                            return Err(error);
5300                        }
5301                        record_transaction_v1_conflict(filesystem, transaction, index, &error)?;
5302                        checkpoint(TransactionV1Checkpoint::ConflictRecorded(index));
5303                        return Err(error);
5304                    }
5305                };
5306            let receipt_head = transaction
5307                .generations
5308                .last()
5309                .expect("step execution retains a validated journal head")
5310                .clone();
5311            let receipt = receipt_head.next_apply_receipt(&transaction.program, index, identity)?;
5312            append_transaction_v1_generation(filesystem, transaction, receipt)?;
5313            checkpoint(TransactionV1Checkpoint::JournalApplyReceiptPersisted(index));
5314            continue;
5315        }
5316        if current.operation_cursor() == transaction.program.operation_count() {
5317            let applied = current.next_applied(&transaction.program)?;
5318            append_transaction_v1_generation(filesystem, transaction, applied)?;
5319            continue;
5320        }
5321        if current.operation_cursor() == 0
5322            && let Err(error) = transaction
5323                .program
5324                .validate_prepared_environment(filesystem)
5325        {
5326            if is_private_transaction_integrity_error(&error) {
5327                return Err(error);
5328            }
5329            record_transaction_v1_conflict(
5330                filesystem,
5331                transaction,
5332                current.operation_cursor(),
5333                &error,
5334            )?;
5335            checkpoint(TransactionV1Checkpoint::ConflictRecorded(
5336                current.operation_cursor(),
5337            ));
5338            return Err(error);
5339        }
5340        let index = current.operation_cursor();
5341        let intent = current.next_apply_intent(&transaction.program, index)?;
5342        append_transaction_v1_generation(filesystem, transaction, intent)?;
5343        checkpoint(TransactionV1Checkpoint::ApplyIntentPersisted(index));
5344    }
5345}
5346
5347fn retains_preserved_aborted_create_descendant(
5348    filesystem: &MigrationFilesystem,
5349    transaction: &PreparedTransactionV1,
5350    directory: &Path,
5351) -> Result<bool> {
5352    let current = transaction
5353        .generations
5354        .last()
5355        .ok_or_else(|| invalid_journal(Path::new("<transaction-v1>"), "journal is empty"))?;
5356    for (operation_index, _) in current.abort_receipt_records() {
5357        let target = match transaction.program.step(operation_index)? {
5358            ProgramStepV1::CreateDirectory { target, .. }
5359            | ProgramStepV1::CreateFile { target, .. } => target.path,
5360            ProgramStepV1::ReplaceFile { .. } | ProgramStepV1::MoveFile { .. } => continue,
5361        };
5362        if target == directory || !target.starts_with(directory) {
5363            continue;
5364        }
5365        let receipt =
5366            load_private_abort_work_receipt(transaction, operation_index)?.ok_or_else(|| {
5367                invalid_journal(
5368                    Path::new("<private-abort-work-receipt-v1>"),
5369                    "journaled create abort has no private receipt",
5370                )
5371            })?;
5372        if receipt.visible_post_identity_sha256.is_none()
5373            && receipt.claims.is_empty()
5374            && filesystem.metadata(target)?.is_some()
5375        {
5376            return Ok(true);
5377        }
5378    }
5379    Ok(false)
5380}
5381
5382fn rollback_transaction_v1_step(
5383    filesystem: &MigrationFilesystem,
5384    transaction: &mut PreparedTransactionV1,
5385    operation_index: usize,
5386    published_identity: Option<&str>,
5387    checkpoint: &mut impl FnMut(TransactionV1Checkpoint),
5388) -> Result<(Vec<PathBuf>, Option<String>)> {
5389    let mut removed = Vec::new();
5390    let current = transaction
5391        .generations
5392        .last()
5393        .ok_or_else(|| invalid_journal(Path::new("<transaction-v1>"), "journal is empty"))?
5394        .clone();
5395    validate_transaction_v1_environment(filesystem, transaction, &current)?;
5396    let retained_parents =
5397        transaction
5398            .program
5399            .retain_step_parents(filesystem, operation_index, &current)?;
5400    let validate_authority = |transaction: &PreparedTransactionV1| {
5401        validate_transaction_v1_environment(filesystem, transaction, &current)?;
5402        transaction
5403            .program
5404            .validate_step_parents(filesystem, operation_index, &current)
5405    };
5406    if let Some(receipt) = load_private_leaf_receipt(
5407        transaction,
5408        operation_index,
5409        PrivateReceiptDirectionV1::Rollback,
5410    )? {
5411        verify_rollback_private_receipt(filesystem, transaction, operation_index, &receipt)?;
5412        return Ok((removed, receipt.after_identity_sha256));
5413    }
5414    let restored_identity = match transaction.program.step(operation_index)? {
5415        ProgramStepV1::CreateDirectory { target, fidelity } => {
5416            let expected_identity = published_identity.ok_or_else(|| {
5417                invalid_journal(
5418                    Path::new("<migration-journal-v1>"),
5419                    "created directory has no published identity",
5420                )
5421            })?;
5422            if retains_preserved_aborted_create_descendant(filesystem, transaction, target.path)? {
5423                validate_authority(transaction)?;
5424                filesystem.exact_directory_fact(
5425                    target.path,
5426                    ExactDirectoryLeaf {
5427                        physical_identity_sha256: expected_identity,
5428                        device_sha256: target.device_sha256,
5429                        read_only: fidelity.read_only,
5430                        executable: fidelity.executable,
5431                    },
5432                    false,
5433                )?;
5434                validate_authority(transaction)?;
5435                Some(expected_identity.to_owned())
5436            } else {
5437                let rollback_name = private_claim_name(operation_index, "rollback");
5438                let source_name = target.path.file_name().ok_or_else(|| {
5439                    invalid_journal(target.path, "program target has no leaf name")
5440                })?;
5441                validate_authority(transaction)?;
5442                let claim = match filesystem.claim_exact_leaf_through(ExactLeafClaimRequest {
5443                    source_parent: retained_parents.get(target.parent)?,
5444                    source_name,
5445                    destination: &transaction.private.claims,
5446                    destination_name: &rollback_name,
5447                    expectation: ExactLeafClaimExpectation::EmptyDirectory(ExactDirectoryLeaf {
5448                        physical_identity_sha256: expected_identity,
5449                        device_sha256: target.device_sha256,
5450                        read_only: fidelity.read_only,
5451                        executable: fidelity.executable,
5452                    }),
5453                    existing_source: ExactExistingClaimSource::Absent,
5454                })? {
5455                    ExactLeafClaimResult::Directory(fact) => fact,
5456                    ExactLeafClaimResult::Regular(_) => {
5457                        return Err(FolderbaseError::MigrationVerificationFailed(
5458                            transaction
5459                                .private
5460                                .claims
5461                                .display_path(OsStr::new(&rollback_name)),
5462                        ));
5463                    }
5464                };
5465                checkpoint(TransactionV1Checkpoint::InverseClaimComplete(
5466                    operation_index,
5467                ));
5468                validate_authority(transaction)?;
5469                if claim.physical_identity_sha256 != expected_identity {
5470                    return Err(FolderbaseError::MigrationVerificationFailed(
5471                        transaction
5472                            .private
5473                            .claims
5474                            .display_path(OsStr::new(&rollback_name)),
5475                    ));
5476                }
5477                removed.push(target.path.to_path_buf());
5478                None
5479            }
5480        }
5481        ProgramStepV1::CreateFile { target, image } => {
5482            let rollback_name = private_claim_name(operation_index, "rollback");
5483            let expected_identity = published_identity.ok_or_else(|| {
5484                invalid_journal(
5485                    Path::new("<migration-journal-v1>"),
5486                    "created file has no published identity",
5487                )
5488            })?;
5489            validate_authority(transaction)?;
5490            let claim = claim_transaction_v1_exact_rollback_output(
5491                filesystem,
5492                transaction,
5493                operation_index,
5494                target.path,
5495                retained_parents.get(target.parent)?,
5496                ExactRegularLeaf {
5497                    physical_identity_sha256: expected_identity,
5498                    device_sha256: target.device_sha256,
5499                    bytes: image.bytes,
5500                    sha256: image.sha256,
5501                    read_only: image.fidelity.read_only,
5502                    executable: image.fidelity.executable,
5503                    link_count: 2,
5504                },
5505                ExactExistingClaimSource::Absent,
5506            )?;
5507            checkpoint(TransactionV1Checkpoint::InverseClaimComplete(
5508                operation_index,
5509            ));
5510            validate_authority(transaction)?;
5511            if claim.physical_identity_sha256 != expected_identity {
5512                return Err(FolderbaseError::MigrationVerificationFailed(
5513                    transaction
5514                        .private
5515                        .claims
5516                        .display_path(OsStr::new(&rollback_name)),
5517                ));
5518            }
5519            removed.push(target.path.to_path_buf());
5520            None
5521        }
5522        ProgramStepV1::ReplaceFile {
5523            target,
5524            image,
5525            rollback_snapshot,
5526        } => {
5527            let rollback_name = private_claim_name(operation_index, "rollback");
5528            let expected_identity = published_identity.ok_or_else(|| {
5529                invalid_journal(
5530                    Path::new("<migration-journal-v1>"),
5531                    "replacement has no published identity",
5532                )
5533            })?;
5534            let applied_link_count = target.link_count.checked_add(1).ok_or_else(|| {
5535                FolderbaseError::MigrationSourceChanged(filesystem.display(target.path))
5536            })?;
5537            let applied = ExactRegularLeaf {
5538                physical_identity_sha256: expected_identity,
5539                device_sha256: target.device_sha256,
5540                bytes: image.bytes,
5541                sha256: image.sha256,
5542                read_only: image.fidelity.read_only,
5543                executable: image.fidelity.executable,
5544                link_count: applied_link_count,
5545            };
5546            let rollback_preexisted = match transaction
5547                .private
5548                .claims
5549                .exact_regular_fact(OsStr::new(&rollback_name), applied)
5550            {
5551                Ok(_) => true,
5552                Err(FolderbaseError::Io { source, .. })
5553                    if source.kind() == std::io::ErrorKind::NotFound =>
5554                {
5555                    false
5556                }
5557                Err(error) => return Err(error),
5558            };
5559            let restore_name = private_claim_name(operation_index, "restore");
5560            let existing_restore =
5561                if rollback_preexisted && filesystem.metadata(target.path)?.is_some() {
5562                    Some(
5563                        transaction
5564                            .private
5565                            .claims
5566                            .relaxed_regular_fact(OsStr::new(&restore_name), target.sha256)?,
5567                    )
5568                } else {
5569                    None
5570                };
5571            let existing_source = match existing_restore.as_ref() {
5572                Some(restore) => ExactExistingClaimSource::Regular(ExactRegularLeaf {
5573                    physical_identity_sha256: &restore.physical_identity_sha256,
5574                    device_sha256: target.device_sha256,
5575                    bytes: target.bytes,
5576                    sha256: target.sha256,
5577                    read_only: target.fidelity.read_only,
5578                    executable: target.fidelity.executable,
5579                    link_count: applied_link_count,
5580                }),
5581                None => ExactExistingClaimSource::Absent,
5582            };
5583            validate_authority(transaction)?;
5584            claim_transaction_v1_exact_rollback_output(
5585                filesystem,
5586                transaction,
5587                operation_index,
5588                target.path,
5589                retained_parents.get(target.parent)?,
5590                applied,
5591                existing_source,
5592            )?;
5593            checkpoint(TransactionV1Checkpoint::InverseClaimComplete(
5594                operation_index,
5595            ));
5596            validate_authority(transaction)?;
5597            if let Some(restore) = existing_restore {
5598                let restored = ExactRegularLeaf {
5599                    physical_identity_sha256: &restore.physical_identity_sha256,
5600                    device_sha256: target.device_sha256,
5601                    bytes: target.bytes,
5602                    sha256: target.sha256,
5603                    read_only: target.fidelity.read_only,
5604                    executable: target.fidelity.executable,
5605                    link_count: applied_link_count,
5606                };
5607                transaction
5608                    .private
5609                    .claims
5610                    .exact_regular_fact(OsStr::new(&restore_name), restored)?;
5611                filesystem.exact_regular_fact(target.path, restored)?;
5612                Some(restore.physical_identity_sha256)
5613            } else {
5614                let restore_claim = prepare_journal_bound_private_publish_claim(
5615                    filesystem,
5616                    &transaction.program,
5617                    &transaction.program_digest,
5618                    &mut transaction.generations,
5619                    &transaction.private,
5620                    operation_index,
5621                    TransactionDirectionV1::Rollback,
5622                    rollback_snapshot,
5623                    &restore_name,
5624                    checkpoint,
5625                )?;
5626                transaction.private.claims.exact_regular_fact(
5627                    OsStr::new(&restore_name),
5628                    ExactRegularLeaf {
5629                        physical_identity_sha256: &restore_claim.physical_identity_sha256,
5630                        device_sha256: target.device_sha256,
5631                        bytes: target.bytes,
5632                        sha256: target.sha256,
5633                        read_only: target.fidelity.read_only,
5634                        executable: target.fidelity.executable,
5635                        link_count: target.link_count,
5636                    },
5637                )?;
5638                validate_authority(transaction)?;
5639                let destination_name = target.path.file_name().ok_or_else(|| {
5640                    invalid_journal(target.path, "program target has no leaf name")
5641                })?;
5642                let restored = filesystem.publish_private_claim_new_through(
5643                    &transaction.private.claims,
5644                    OsStr::new(&restore_name),
5645                    retained_parents.get(target.parent)?,
5646                    destination_name,
5647                    &restore_claim.physical_identity_sha256,
5648                    target.sha256,
5649                    target.bytes,
5650                )?;
5651                validate_authority(transaction)?;
5652                let restored = ExactRegularLeaf {
5653                    physical_identity_sha256: &restored.physical_identity_sha256,
5654                    device_sha256: target.device_sha256,
5655                    bytes: target.bytes,
5656                    sha256: target.sha256,
5657                    read_only: target.fidelity.read_only,
5658                    executable: target.fidelity.executable,
5659                    link_count: applied_link_count,
5660                };
5661                transaction
5662                    .private
5663                    .claims
5664                    .exact_regular_fact(OsStr::new(&restore_name), restored)?;
5665                filesystem.exact_regular_fact(target.path, restored)?;
5666                Some(restored.physical_identity_sha256.to_owned())
5667            }
5668        }
5669        ProgramStepV1::MoveFile {
5670            source,
5671            destination,
5672            rollback_snapshot,
5673        } => {
5674            let rollback_name = private_claim_name(operation_index, "rollback");
5675            let expected_identity = published_identity.ok_or_else(|| {
5676                invalid_journal(
5677                    Path::new("<migration-journal-v1>"),
5678                    "move has no published identity",
5679                )
5680            })?;
5681            let applied_link_count = source.link_count.checked_add(1).ok_or_else(|| {
5682                FolderbaseError::MigrationSourceChanged(filesystem.display(destination.path))
5683            })?;
5684            let applied = ExactRegularLeaf {
5685                physical_identity_sha256: expected_identity,
5686                device_sha256: source.device_sha256,
5687                bytes: source.bytes,
5688                sha256: source.sha256,
5689                read_only: source.fidelity.read_only,
5690                executable: source.fidelity.executable,
5691                link_count: applied_link_count,
5692            };
5693            let rollback_preexisted = match transaction
5694                .private
5695                .claims
5696                .exact_regular_fact(OsStr::new(&rollback_name), applied)
5697            {
5698                Ok(_) => true,
5699                Err(FolderbaseError::Io { source, .. })
5700                    if source.kind() == std::io::ErrorKind::NotFound =>
5701                {
5702                    false
5703                }
5704                Err(error) => return Err(error),
5705            };
5706            if !rollback_preexisted && filesystem.metadata(source.path)?.is_some() {
5707                return Err(FolderbaseError::MigrationSourceChanged(
5708                    filesystem.display(source.path),
5709                ));
5710            }
5711            validate_authority(transaction)?;
5712            claim_transaction_v1_exact_rollback_output(
5713                filesystem,
5714                transaction,
5715                operation_index,
5716                destination.path,
5717                retained_parents.get(destination.parent)?,
5718                applied,
5719                ExactExistingClaimSource::Absent,
5720            )?;
5721            checkpoint(TransactionV1Checkpoint::InverseClaimComplete(
5722                operation_index,
5723            ));
5724            validate_authority(transaction)?;
5725
5726            let restore_name = private_claim_name(operation_index, "restore");
5727            let existing_restore =
5728                if rollback_preexisted && filesystem.metadata(source.path)?.is_some() {
5729                    Some(
5730                        transaction
5731                            .private
5732                            .claims
5733                            .relaxed_regular_fact(OsStr::new(&restore_name), source.sha256)?,
5734                    )
5735                } else {
5736                    None
5737                };
5738            if let Some(restore) = existing_restore {
5739                let restored = ExactRegularLeaf {
5740                    physical_identity_sha256: &restore.physical_identity_sha256,
5741                    device_sha256: source.device_sha256,
5742                    bytes: source.bytes,
5743                    sha256: source.sha256,
5744                    read_only: source.fidelity.read_only,
5745                    executable: source.fidelity.executable,
5746                    link_count: applied_link_count,
5747                };
5748                transaction
5749                    .private
5750                    .claims
5751                    .exact_regular_fact(OsStr::new(&restore_name), restored)?;
5752                filesystem.exact_regular_fact(source.path, restored)?;
5753                Some(restore.physical_identity_sha256)
5754            } else {
5755                let restore_claim = prepare_journal_bound_private_publish_claim(
5756                    filesystem,
5757                    &transaction.program,
5758                    &transaction.program_digest,
5759                    &mut transaction.generations,
5760                    &transaction.private,
5761                    operation_index,
5762                    TransactionDirectionV1::Rollback,
5763                    rollback_snapshot,
5764                    &restore_name,
5765                    checkpoint,
5766                )?;
5767                transaction.private.claims.exact_regular_fact(
5768                    OsStr::new(&restore_name),
5769                    ExactRegularLeaf {
5770                        physical_identity_sha256: &restore_claim.physical_identity_sha256,
5771                        device_sha256: source.device_sha256,
5772                        bytes: source.bytes,
5773                        sha256: source.sha256,
5774                        read_only: source.fidelity.read_only,
5775                        executable: source.fidelity.executable,
5776                        link_count: source.link_count,
5777                    },
5778                )?;
5779                validate_authority(transaction)?;
5780                let destination_name = source.path.file_name().ok_or_else(|| {
5781                    invalid_journal(source.path, "program source has no leaf name")
5782                })?;
5783                let restored = filesystem.publish_private_claim_new_through(
5784                    &transaction.private.claims,
5785                    OsStr::new(&restore_name),
5786                    retained_parents.get(source.parent)?,
5787                    destination_name,
5788                    &restore_claim.physical_identity_sha256,
5789                    source.sha256,
5790                    source.bytes,
5791                )?;
5792                validate_authority(transaction)?;
5793                let restored = ExactRegularLeaf {
5794                    physical_identity_sha256: &restored.physical_identity_sha256,
5795                    device_sha256: source.device_sha256,
5796                    bytes: source.bytes,
5797                    sha256: source.sha256,
5798                    read_only: source.fidelity.read_only,
5799                    executable: source.fidelity.executable,
5800                    link_count: applied_link_count,
5801                };
5802                transaction
5803                    .private
5804                    .claims
5805                    .exact_regular_fact(OsStr::new(&restore_name), restored)?;
5806                filesystem.exact_regular_fact(source.path, restored)?;
5807                removed.push(destination.path.to_path_buf());
5808                Some(restored.physical_identity_sha256.to_owned())
5809            }
5810        }
5811    };
5812    validate_authority(transaction)?;
5813    let receipt = PrivateLeafReceiptV1::new(
5814        transaction,
5815        operation_index,
5816        PrivateReceiptDirectionV1::Rollback,
5817        published_identity.map(str::to_owned),
5818        restored_identity.clone(),
5819    )?;
5820    persist_private_leaf_receipt(transaction, &receipt)?;
5821    checkpoint(TransactionV1Checkpoint::PrivateRollbackReceiptPersisted(
5822        operation_index,
5823    ));
5824    Ok((removed, restored_identity))
5825}
5826
5827fn verify_rollback_private_receipt(
5828    filesystem: &MigrationFilesystem,
5829    transaction: &PreparedTransactionV1,
5830    operation_index: usize,
5831    receipt: &PrivateLeafReceiptV1,
5832) -> Result<()> {
5833    let published_identity = receipt.before_identity_sha256.as_deref().ok_or_else(|| {
5834        invalid_journal(
5835            Path::new("<private-leaf-receipt-v1>"),
5836            "rollback receipt has no apply identity",
5837        )
5838    })?;
5839    let rollback_name = private_claim_name(operation_index, "rollback");
5840    match transaction.program.step(operation_index)? {
5841        ProgramStepV1::CreateDirectory { target, fidelity } => {
5842            if let Some(retained_identity) = receipt.after_identity_sha256.as_deref() {
5843                if retained_identity != published_identity {
5844                    return Err(FolderbaseError::MigrationVerificationFailed(
5845                        filesystem.display(target.path),
5846                    ));
5847                }
5848                filesystem.exact_directory_fact(
5849                    target.path,
5850                    ExactDirectoryLeaf {
5851                        physical_identity_sha256: retained_identity,
5852                        device_sha256: target.device_sha256,
5853                        read_only: fidelity.read_only,
5854                        executable: fidelity.executable,
5855                    },
5856                    false,
5857                )?;
5858                return Ok(());
5859            }
5860            if filesystem.metadata(target.path)?.is_some() {
5861                return Err(FolderbaseError::MigrationVerificationFailed(
5862                    filesystem.display(target.path),
5863                ));
5864            }
5865            verify_create_directory_rollback_claim(
5866                transaction,
5867                operation_index,
5868                published_identity,
5869                target.device_sha256,
5870                fidelity.read_only,
5871                fidelity.executable,
5872            )?;
5873        }
5874        ProgramStepV1::CreateFile { target, image } => {
5875            if receipt.after_identity_sha256.is_some()
5876                || filesystem.metadata(target.path)?.is_some()
5877            {
5878                return Err(FolderbaseError::MigrationVerificationFailed(
5879                    filesystem.display(target.path),
5880                ));
5881            }
5882            let rolled_back = ExactRegularLeaf {
5883                physical_identity_sha256: published_identity,
5884                device_sha256: target.device_sha256,
5885                bytes: image.bytes,
5886                sha256: image.sha256,
5887                read_only: image.fidelity.read_only,
5888                executable: image.fidelity.executable,
5889                link_count: 2,
5890            };
5891            transaction.private.claims.exact_regular_fact(
5892                OsStr::new(&private_claim_name(operation_index, "publish")),
5893                rolled_back,
5894            )?;
5895            transaction
5896                .private
5897                .claims
5898                .exact_regular_fact(OsStr::new(&rollback_name), rolled_back)?;
5899        }
5900        ProgramStepV1::ReplaceFile { target, image, .. } => {
5901            let restored_identity = receipt.after_identity_sha256.as_deref().ok_or_else(|| {
5902                invalid_journal(
5903                    Path::new("<private-leaf-receipt-v1>"),
5904                    "replacement rollback receipt has no restored identity",
5905                )
5906            })?;
5907            let link_count = target.link_count.checked_add(1).ok_or_else(|| {
5908                FolderbaseError::MigrationVerificationFailed(filesystem.display(target.path))
5909            })?;
5910            let rolled_back = ExactRegularLeaf {
5911                physical_identity_sha256: published_identity,
5912                device_sha256: target.device_sha256,
5913                bytes: image.bytes,
5914                sha256: image.sha256,
5915                read_only: image.fidelity.read_only,
5916                executable: image.fidelity.executable,
5917                link_count,
5918            };
5919            transaction.private.claims.exact_regular_fact(
5920                OsStr::new(&private_claim_name(operation_index, "publish")),
5921                rolled_back,
5922            )?;
5923            transaction
5924                .private
5925                .claims
5926                .exact_regular_fact(OsStr::new(&rollback_name), rolled_back)?;
5927            let restored = ExactRegularLeaf {
5928                physical_identity_sha256: restored_identity,
5929                device_sha256: target.device_sha256,
5930                bytes: target.bytes,
5931                sha256: target.sha256,
5932                read_only: target.fidelity.read_only,
5933                executable: target.fidelity.executable,
5934                link_count,
5935            };
5936            transaction.private.claims.exact_regular_fact(
5937                OsStr::new(&private_claim_name(operation_index, "restore")),
5938                restored,
5939            )?;
5940            filesystem.exact_regular_fact(target.path, restored)?;
5941        }
5942        ProgramStepV1::MoveFile {
5943            source,
5944            destination,
5945            ..
5946        } => {
5947            let restored_identity = receipt.after_identity_sha256.as_deref().ok_or_else(|| {
5948                invalid_journal(
5949                    Path::new("<private-leaf-receipt-v1>"),
5950                    "move rollback receipt has no restored identity",
5951                )
5952            })?;
5953            if filesystem.metadata(destination.path)?.is_some() {
5954                return Err(FolderbaseError::MigrationVerificationFailed(
5955                    filesystem.display(destination.path),
5956                ));
5957            }
5958            let link_count = source.link_count.checked_add(1).ok_or_else(|| {
5959                FolderbaseError::MigrationVerificationFailed(filesystem.display(source.path))
5960            })?;
5961            let rolled_back = ExactRegularLeaf {
5962                physical_identity_sha256: published_identity,
5963                device_sha256: source.device_sha256,
5964                bytes: source.bytes,
5965                sha256: source.sha256,
5966                read_only: source.fidelity.read_only,
5967                executable: source.fidelity.executable,
5968                link_count,
5969            };
5970            transaction.private.claims.exact_regular_fact(
5971                OsStr::new(&private_claim_name(operation_index, "source")),
5972                rolled_back,
5973            )?;
5974            transaction
5975                .private
5976                .claims
5977                .exact_regular_fact(OsStr::new(&rollback_name), rolled_back)?;
5978            let restored = ExactRegularLeaf {
5979                physical_identity_sha256: restored_identity,
5980                device_sha256: source.device_sha256,
5981                bytes: source.bytes,
5982                sha256: source.sha256,
5983                read_only: source.fidelity.read_only,
5984                executable: source.fidelity.executable,
5985                link_count,
5986            };
5987            transaction.private.claims.exact_regular_fact(
5988                OsStr::new(&private_claim_name(operation_index, "restore")),
5989                restored,
5990            )?;
5991            filesystem.exact_regular_fact(source.path, restored)?;
5992        }
5993    }
5994    Ok(())
5995}
5996
5997fn claim_transaction_v1_exact_rollback_output(
5998    filesystem: &MigrationFilesystem,
5999    transaction: &PreparedTransactionV1,
6000    operation_index: usize,
6001    visible_path: &Path,
6002    visible_parent: &VerifiedVisibleDirectory,
6003    expected: ExactRegularLeaf<'_>,
6004    existing_source: ExactExistingClaimSource<'_>,
6005) -> Result<MigrationRegularFact> {
6006    let rollback_name = private_claim_name(operation_index, "rollback");
6007    let visible_name = visible_path
6008        .file_name()
6009        .ok_or_else(|| invalid_journal(visible_path, "program path has no leaf name"))?;
6010    match filesystem.claim_exact_leaf_through(ExactLeafClaimRequest {
6011        source_parent: visible_parent,
6012        source_name: visible_name,
6013        destination: &transaction.private.claims,
6014        destination_name: &rollback_name,
6015        expectation: ExactLeafClaimExpectation::Regular(expected),
6016        existing_source,
6017    })? {
6018        ExactLeafClaimResult::Regular(fact) => Ok(fact),
6019        ExactLeafClaimResult::Directory(_) => Err(FolderbaseError::MigrationVerificationFailed(
6020            transaction
6021                .private
6022                .claims
6023                .display_path(OsStr::new(&rollback_name)),
6024        )),
6025    }
6026}
6027
6028fn private_regular_fact_if_present(
6029    directory: &VerifiedPrivateDirectory,
6030    name: &str,
6031    expected_sha256: &str,
6032) -> Result<Option<MigrationRegularFact>> {
6033    match directory.relaxed_regular_fact(OsStr::new(name), expected_sha256) {
6034        Ok(fact) => Ok(Some(fact)),
6035        Err(FolderbaseError::Io { source, .. })
6036            if source.kind() == std::io::ErrorKind::NotFound =>
6037        {
6038            Ok(None)
6039        }
6040        Err(error) => Err(error),
6041    }
6042}
6043
6044fn private_directory_fact_if_present(
6045    directory: &VerifiedPrivateDirectory,
6046    name: &str,
6047) -> Result<Option<crate::migration_filesystem::MigrationDirectoryFact>> {
6048    match directory.relaxed_directory_fact(OsStr::new(name)) {
6049        Ok(fact) => Ok(Some(fact)),
6050        Err(FolderbaseError::Io { source, .. })
6051            if source.kind() == std::io::ErrorKind::NotFound =>
6052        {
6053            Ok(None)
6054        }
6055        Err(error) => Err(error),
6056    }
6057}
6058
6059fn regular_fact_executable(fact: &MigrationRegularFact) -> bool {
6060    fact.unix_mode.is_some_and(|mode| mode & 0o111 != 0)
6061}
6062
6063fn directory_fact_executable(fact: &crate::migration_filesystem::MigrationDirectoryFact) -> bool {
6064    fact.unix_mode.is_none_or(|mode| mode & 0o111 != 0)
6065}
6066
6067fn require_move_abort_fact_shape(
6068    transaction: &PreparedTransactionV1,
6069    operation_index: usize,
6070    name: &str,
6071    fact: &MigrationRegularFact,
6072    source: transaction_v1::ProgramBoundRegularV1<'_>,
6073) -> Result<()> {
6074    let read_only = fact.read_only;
6075    let executable = regular_fact_executable(fact);
6076    if fact.physical_identity_sha256 != source.physical_identity_sha256
6077        || fact.device_sha256 != source.device_sha256
6078        || fact.bytes != source.bytes
6079        || read_only != source.fidelity.read_only
6080        || executable != source.fidelity.executable
6081    {
6082        return Err(FolderbaseError::MigrationVerificationFailed(
6083            transaction.private.claims.display_path(OsStr::new(name)),
6084        ));
6085    }
6086    if !matches!(
6087        name,
6088        value
6089            if value == private_claim_name(operation_index, "source")
6090                || value == private_claim_name(operation_index, "rollback")
6091    ) {
6092        return Err(invalid_journal(
6093            transaction.private.claims.display_path(OsStr::new(name)),
6094            "Move abort claim has an impossible name",
6095        ));
6096    }
6097    Ok(())
6098}
6099
6100fn verify_private_abort_work_receipt(
6101    filesystem: &MigrationFilesystem,
6102    transaction: &PreparedTransactionV1,
6103    operation_index: usize,
6104    receipt: &PrivateAbortWorkReceiptV1,
6105) -> Result<()> {
6106    let receipt_name = private_abort_receipt_name(operation_index);
6107    let receipt_path = transaction
6108        .private
6109        .receipts
6110        .display_path(OsStr::new(&receipt_name));
6111    if receipt.operation_index != operation_index {
6112        return Err(invalid_journal(
6113            &receipt_path,
6114            "private abort-work receipt index disagrees with its path",
6115        ));
6116    }
6117    let prefix = format!("{operation_index:08}.");
6118    let actual_claims = transaction
6119        .private
6120        .claims
6121        .closed_entries(
6122            transaction
6123                .program
6124                .operation_count()
6125                .saturating_mul(4)
6126                .saturating_add(1),
6127        )?
6128        .into_iter()
6129        .filter_map(|(name, is_directory)| {
6130            let name = name.to_string_lossy().into_owned();
6131            name.starts_with(&prefix).then_some((name, is_directory))
6132        })
6133        .collect::<BTreeMap<_, _>>();
6134    let expected_claims = receipt
6135        .claims
6136        .iter()
6137        .map(|claim| (claim.name().to_owned(), claim.is_directory()))
6138        .collect::<BTreeMap<_, _>>();
6139    if let Some((name, _)) = actual_claims
6140        .iter()
6141        .find(|(name, kind)| expected_claims.get(*name) != Some(*kind))
6142    {
6143        return Err(invalid_journal(
6144            transaction.private.claims.display_path(OsStr::new(name)),
6145            "private abort-work receipt omits or misclassifies an exact claim",
6146        ));
6147    }
6148    if let Some((name, _)) = expected_claims
6149        .iter()
6150        .find(|(name, kind)| actual_claims.get(*name) != Some(*kind))
6151    {
6152        return Err(invalid_journal(
6153            transaction.private.claims.display_path(OsStr::new(name)),
6154            "private abort-work receipt names a missing exact claim",
6155        ));
6156    }
6157
6158    match transaction.program.step(operation_index)? {
6159        ProgramStepV1::MoveFile { source, .. } => {
6160            if receipt.visible_post_identity_sha256.as_deref()
6161                != Some(source.physical_identity_sha256)
6162            {
6163                return Err(invalid_journal(
6164                    &receipt_path,
6165                    "Move abort receipt has the wrong visible post identity",
6166                ));
6167            }
6168            if !receipt.claims.is_empty() {
6169                return Err(invalid_journal(
6170                    &receipt_path,
6171                    "Move abort receipt retains live workspace authority",
6172                ));
6173            }
6174            let journaled = transaction.generations.last().is_some_and(|generation| {
6175                generation.abort_receipt_sha256(operation_index).is_some()
6176            });
6177            if !journaled {
6178                filesystem.exact_regular_fact(
6179                    source.path,
6180                    ExactRegularLeaf {
6181                        physical_identity_sha256: source.physical_identity_sha256,
6182                        device_sha256: source.device_sha256,
6183                        bytes: source.bytes,
6184                        sha256: source.sha256,
6185                        read_only: source.fidelity.read_only,
6186                        executable: source.fidelity.executable,
6187                        link_count: source.link_count,
6188                    },
6189                )?;
6190            }
6191            Ok(())
6192        }
6193        ProgramStepV1::CreateDirectory { target, fidelity } => {
6194            if receipt.visible_post_identity_sha256.is_some() {
6195                return Err(invalid_journal(
6196                    &receipt_path,
6197                    "CreateDirectory abort receipt has a visible post identity",
6198                ));
6199            }
6200            match receipt.claims.as_slice() {
6201                [] => Ok(()),
6202                [claim] if claim.name() == private_claim_name(operation_index, "publish") => {
6203                    let Some(exact) = claim.exact_directory() else {
6204                        return Err(invalid_journal(
6205                            &receipt_path,
6206                            "CreateDirectory abort receipt publish claim is not a directory",
6207                        ));
6208                    };
6209                    if exact.device_sha256 != target.device_sha256
6210                        || exact.read_only != fidelity.read_only
6211                        || exact.executable != fidelity.executable
6212                    {
6213                        return Err(invalid_journal(
6214                            &receipt_path,
6215                            "CreateDirectory abort receipt disagrees with the immutable program",
6216                        ));
6217                    }
6218                    transaction
6219                        .private
6220                        .claims
6221                        .exact_empty_directory_fact(OsStr::new(claim.name()), exact)?;
6222                    Ok(())
6223                }
6224                _ => Err(invalid_journal(
6225                    &receipt_path,
6226                    "CreateDirectory abort receipt has an impossible exact claim set",
6227                )),
6228            }
6229        }
6230        ProgramStepV1::CreateFile { target, image } => {
6231            if receipt.visible_post_identity_sha256.is_some() {
6232                return Err(invalid_journal(
6233                    &receipt_path,
6234                    "CreateFile abort receipt has a visible post identity",
6235                ));
6236            }
6237            match receipt.claims.as_slice() {
6238                [] => Ok(()),
6239                [publish, rollback]
6240                    if publish.name() == private_claim_name(operation_index, "publish")
6241                        && rollback.name() == private_claim_name(operation_index, "rollback") =>
6242                {
6243                    let (Some(rollback), Some(publish)) =
6244                        (rollback.exact_regular(), publish.exact_regular())
6245                    else {
6246                        return Err(invalid_journal(
6247                            &receipt_path,
6248                            "CreateFile abort receipt contains a directory claim",
6249                        ));
6250                    };
6251                    if rollback.physical_identity_sha256 != publish.physical_identity_sha256
6252                        || rollback.device_sha256 != publish.device_sha256
6253                        || rollback.bytes != publish.bytes
6254                        || rollback.sha256 != publish.sha256
6255                        || rollback.read_only != publish.read_only
6256                        || rollback.executable != publish.executable
6257                        || rollback.link_count != publish.link_count
6258                        || publish.device_sha256 != target.device_sha256
6259                        || publish.bytes != image.bytes
6260                        || publish.sha256 != image.sha256
6261                        || publish.read_only != image.fidelity.read_only
6262                        || publish.executable != image.fidelity.executable
6263                        || publish.link_count != 2
6264                    {
6265                        return Err(invalid_journal(
6266                            &receipt_path,
6267                            "CreateFile abort receipt disagrees with the immutable program",
6268                        ));
6269                    }
6270                    transaction.private.claims.exact_regular_fact(
6271                        OsStr::new(&private_claim_name(operation_index, "rollback")),
6272                        rollback,
6273                    )?;
6274                    transaction.private.claims.exact_regular_fact(
6275                        OsStr::new(&private_claim_name(operation_index, "publish")),
6276                        publish,
6277                    )?;
6278                    Ok(())
6279                }
6280                _ => Err(invalid_journal(
6281                    &receipt_path,
6282                    "CreateFile abort receipt has an impossible exact claim set",
6283                )),
6284            }
6285        }
6286        ProgramStepV1::ReplaceFile { target, image, .. } => {
6287            if receipt.visible_post_identity_sha256.as_deref()
6288                != Some(target.physical_identity_sha256)
6289            {
6290                return Err(invalid_journal(
6291                    &receipt_path,
6292                    "ReplaceFile abort receipt has the wrong visible post identity",
6293                ));
6294            }
6295            let rollback_name = private_claim_name(operation_index, "rollback");
6296            match receipt.claims.as_slice() {
6297                [] => {}
6298                [claim] if claim.name() == rollback_name => {
6299                    let Some(exact) = claim.exact_regular() else {
6300                        return Err(invalid_journal(
6301                            &receipt_path,
6302                            "ReplaceFile abort receipt contains a directory claim",
6303                        ));
6304                    };
6305                    if exact.device_sha256 != target.device_sha256
6306                        || exact.bytes != image.bytes
6307                        || exact.sha256 != image.sha256
6308                        || exact.read_only != image.fidelity.read_only
6309                        || exact.executable != image.fidelity.executable
6310                        || exact.link_count != 1
6311                    {
6312                        return Err(invalid_journal(
6313                            &receipt_path,
6314                            "ReplaceFile abort rollback claim disagrees with the immutable program",
6315                        ));
6316                    }
6317                    transaction
6318                        .private
6319                        .claims
6320                        .exact_regular_fact(OsStr::new(claim.name()), exact)?;
6321                }
6322                _ => {
6323                    return Err(invalid_journal(
6324                        &receipt_path,
6325                        "ReplaceFile abort receipt has an impossible exact claim set",
6326                    ));
6327                }
6328            }
6329            let journaled = transaction.generations.last().is_some_and(|generation| {
6330                generation.abort_receipt_sha256(operation_index).is_some()
6331            });
6332            if !journaled {
6333                filesystem.exact_regular_fact(
6334                    target.path,
6335                    ExactRegularLeaf {
6336                        physical_identity_sha256: target.physical_identity_sha256,
6337                        device_sha256: target.device_sha256,
6338                        bytes: target.bytes,
6339                        sha256: target.sha256,
6340                        read_only: target.fidelity.read_only,
6341                        executable: target.fidelity.executable,
6342                        link_count: target.link_count,
6343                    },
6344                )?;
6345            }
6346            Ok(())
6347        }
6348    }
6349}
6350
6351fn finish_private_abort_work_receipt(
6352    filesystem: &MigrationFilesystem,
6353    transaction: &PreparedTransactionV1,
6354    operation_index: usize,
6355    receipt: PrivateAbortWorkReceiptV1,
6356    checkpoint: &mut impl FnMut(TransactionV1Checkpoint),
6357    validate_retained_authority: &impl Fn() -> Result<()>,
6358) -> Result<String> {
6359    persist_private_abort_work_receipt(transaction, &receipt)?;
6360    let reopened =
6361        load_private_abort_work_receipt(transaction, operation_index)?.ok_or_else(|| {
6362            let name = private_abort_receipt_name(operation_index);
6363            invalid_journal(
6364                transaction.private.receipts.display_path(OsStr::new(&name)),
6365                "persisted abort-work receipt is missing",
6366            )
6367        })?;
6368    if reopened != receipt {
6369        let name = private_abort_receipt_name(operation_index);
6370        return Err(invalid_journal(
6371            transaction.private.receipts.display_path(OsStr::new(&name)),
6372            "persisted abort-work receipt changed during reverify",
6373        ));
6374    }
6375    verify_private_abort_work_receipt(filesystem, transaction, operation_index, &reopened)?;
6376    validate_retained_authority()?;
6377    let digest = reopened.encoded_sha256()?;
6378    checkpoint(TransactionV1Checkpoint::PrivateAbortReceiptPersisted(
6379        operation_index,
6380    ));
6381    Ok(digest)
6382}
6383
6384fn abort_transaction_v1_in_flight_apply(
6385    filesystem: &MigrationFilesystem,
6386    transaction: &PreparedTransactionV1,
6387    operation_index: usize,
6388    checkpoint: &mut impl FnMut(TransactionV1Checkpoint),
6389) -> Result<String> {
6390    let current = transaction
6391        .generations
6392        .last()
6393        .ok_or_else(|| invalid_journal(Path::new("<transaction-v1>"), "journal is empty"))?;
6394    validate_transaction_v1_environment(filesystem, transaction, current)?;
6395    let retained_parents =
6396        transaction
6397            .program
6398            .retain_step_parents(filesystem, operation_index, current)?;
6399    let validate_retained_authority = || -> Result<()> {
6400        validate_transaction_v1_environment(filesystem, transaction, current)?;
6401        transaction.program.validate_retained_step_parents(
6402            filesystem,
6403            operation_index,
6404            current,
6405            &retained_parents,
6406        )
6407    };
6408    validate_retained_authority()?;
6409    if let Some(receipt) = load_private_abort_work_receipt(transaction, operation_index)? {
6410        verify_private_abort_work_receipt(filesystem, transaction, operation_index, &receipt)?;
6411        validate_retained_authority()?;
6412        return receipt.encoded_sha256();
6413    }
6414
6415    let receipt = match transaction.program.step(operation_index)? {
6416        ProgramStepV1::MoveFile {
6417            source,
6418            destination,
6419            ..
6420        } => {
6421            let source_name = private_claim_name(operation_index, "source");
6422            let rollback_name = private_claim_name(operation_index, "rollback");
6423            let mut source_claim = private_regular_fact_if_present(
6424                &transaction.private.claims,
6425                &source_name,
6426                source.sha256,
6427            )?;
6428            if let Some(fact) = source_claim.as_ref() {
6429                require_move_abort_fact_shape(
6430                    transaction,
6431                    operation_index,
6432                    &source_name,
6433                    fact,
6434                    source,
6435                )?;
6436            }
6437            let mut rollback_claim = private_regular_fact_if_present(
6438                &transaction.private.claims,
6439                &rollback_name,
6440                source.sha256,
6441            )?;
6442            if let Some(fact) = rollback_claim.as_ref() {
6443                require_move_abort_fact_shape(
6444                    transaction,
6445                    operation_index,
6446                    &rollback_name,
6447                    fact,
6448                    source,
6449                )?;
6450            }
6451            let destination_is_published = regular_fact_matches_program(
6452                filesystem,
6453                destination.path,
6454                Some(source.physical_identity_sha256),
6455                source.bytes,
6456                source.sha256,
6457                source.fidelity.read_only,
6458                source.fidelity.executable,
6459            )?
6460            .is_some();
6461            if source_claim.is_none() {
6462                if rollback_claim.is_some() || destination_is_published {
6463                    return Err(FolderbaseError::MigrationVerificationFailed(
6464                        transaction
6465                            .private
6466                            .claims
6467                            .display_path(OsStr::new(&source_name)),
6468                    ));
6469                }
6470                filesystem.exact_regular_fact(
6471                    source.path,
6472                    ExactRegularLeaf {
6473                        physical_identity_sha256: source.physical_identity_sha256,
6474                        device_sha256: source.device_sha256,
6475                        bytes: source.bytes,
6476                        sha256: source.sha256,
6477                        read_only: source.fidelity.read_only,
6478                        executable: source.fidelity.executable,
6479                        link_count: source.link_count,
6480                    },
6481                )?;
6482                PrivateAbortWorkReceiptV1::new(
6483                    transaction,
6484                    operation_index,
6485                    Some(source.physical_identity_sha256.to_owned()),
6486                    Vec::new(),
6487                )?
6488            } else {
6489                if destination_is_published && rollback_claim.is_some() {
6490                    return Err(FolderbaseError::MigrationVerificationFailed(
6491                        filesystem.display(destination.path),
6492                    ));
6493                }
6494                if destination_is_published {
6495                    let source_claim_fact = source_claim.as_ref().expect("source claim exists");
6496                    let expected_claim_link_count =
6497                        source.link_count.checked_add(1).ok_or_else(|| {
6498                            FolderbaseError::MigrationSourceChanged(
6499                                filesystem.display(destination.path),
6500                            )
6501                        })?;
6502                    if source_claim_fact.link_count != expected_claim_link_count {
6503                        return Err(FolderbaseError::MigrationVerificationFailed(
6504                            transaction
6505                                .private
6506                                .claims
6507                                .display_path(OsStr::new(&source_name)),
6508                        ));
6509                    }
6510                    let destination_name = destination.path.file_name().ok_or_else(|| {
6511                        invalid_journal(destination.path, "program destination has no leaf name")
6512                    })?;
6513                    validate_retained_authority()?;
6514                    match filesystem.claim_exact_leaf_through(ExactLeafClaimRequest {
6515                        source_parent: retained_parents.get(destination.parent)?,
6516                        source_name: destination_name,
6517                        destination: &transaction.private.claims,
6518                        destination_name: &rollback_name,
6519                        expectation: ExactLeafClaimExpectation::Regular(ExactRegularLeaf {
6520                            physical_identity_sha256: source.physical_identity_sha256,
6521                            device_sha256: source.device_sha256,
6522                            bytes: source.bytes,
6523                            sha256: source.sha256,
6524                            read_only: source.fidelity.read_only,
6525                            executable: source.fidelity.executable,
6526                            link_count: expected_claim_link_count,
6527                        }),
6528                        existing_source: ExactExistingClaimSource::Absent,
6529                    })? {
6530                        ExactLeafClaimResult::Regular(_) => {}
6531                        ExactLeafClaimResult::Directory(_) => {
6532                            return Err(FolderbaseError::MigrationVerificationFailed(
6533                                transaction
6534                                    .private
6535                                    .claims
6536                                    .display_path(OsStr::new(&rollback_name)),
6537                            ));
6538                        }
6539                    }
6540                    validate_retained_authority()?;
6541                }
6542
6543                let source_is_restored = regular_fact_matches_program(
6544                    filesystem,
6545                    source.path,
6546                    Some(source.physical_identity_sha256),
6547                    source.bytes,
6548                    source.sha256,
6549                    source.fidelity.read_only,
6550                    source.fidelity.executable,
6551                )?
6552                .is_some();
6553                if !source_is_restored && filesystem.metadata(source.path)?.is_some() {
6554                    return Err(FolderbaseError::WouldOverwrite(
6555                        filesystem.display(source.path),
6556                    ));
6557                }
6558                if !source_is_restored {
6559                    let destination_name = source.path.file_name().ok_or_else(|| {
6560                        invalid_journal(source.path, "program source has no leaf name")
6561                    })?;
6562                    validate_retained_authority()?;
6563                    filesystem.publish_private_claim_new_through(
6564                        &transaction.private.claims,
6565                        OsStr::new(&source_name),
6566                        retained_parents.get(source.parent)?,
6567                        destination_name,
6568                        source.physical_identity_sha256,
6569                        source.sha256,
6570                        source.bytes,
6571                    )?;
6572                    validate_retained_authority()?;
6573                }
6574
6575                source_claim = private_regular_fact_if_present(
6576                    &transaction.private.claims,
6577                    &source_name,
6578                    source.sha256,
6579                )?;
6580                let source_claim = source_claim.ok_or_else(|| {
6581                    FolderbaseError::MigrationVerificationFailed(
6582                        transaction
6583                            .private
6584                            .claims
6585                            .display_path(OsStr::new(&source_name)),
6586                    )
6587                })?;
6588                rollback_claim = private_regular_fact_if_present(
6589                    &transaction.private.claims,
6590                    &rollback_name,
6591                    source.sha256,
6592                )?;
6593                let final_link_count = source
6594                    .link_count
6595                    .checked_add(1 + usize::from(rollback_claim.is_some()) as u64)
6596                    .ok_or_else(|| {
6597                        FolderbaseError::MigrationSourceChanged(filesystem.display(source.path))
6598                    })?;
6599                let restored = ExactRegularLeaf {
6600                    physical_identity_sha256: source.physical_identity_sha256,
6601                    device_sha256: source.device_sha256,
6602                    bytes: source.bytes,
6603                    sha256: source.sha256,
6604                    read_only: source.fidelity.read_only,
6605                    executable: source.fidelity.executable,
6606                    link_count: final_link_count,
6607                };
6608                transaction
6609                    .private
6610                    .claims
6611                    .exact_regular_fact(OsStr::new(&source_name), restored)?;
6612                if let Some(rollback_claim) = rollback_claim.as_ref() {
6613                    require_move_abort_fact_shape(
6614                        transaction,
6615                        operation_index,
6616                        &rollback_name,
6617                        rollback_claim,
6618                        source,
6619                    )?;
6620                    transaction
6621                        .private
6622                        .claims
6623                        .exact_regular_fact(OsStr::new(&rollback_name), restored)?;
6624                }
6625                if source_claim.link_count != final_link_count {
6626                    return Err(FolderbaseError::MigrationVerificationFailed(
6627                        transaction
6628                            .private
6629                            .claims
6630                            .display_path(OsStr::new(&source_name)),
6631                    ));
6632                }
6633                filesystem.exact_regular_fact(source.path, restored)?;
6634                validate_retained_authority()?;
6635
6636                if rollback_claim.is_some() {
6637                    transaction.private.claims.remove_exact_owned_regular(
6638                        OsStr::new(&rollback_name),
6639                        ExactRegularLeaf {
6640                            physical_identity_sha256: source.physical_identity_sha256,
6641                            device_sha256: source.device_sha256,
6642                            bytes: source.bytes,
6643                            sha256: source.sha256,
6644                            read_only: source.fidelity.read_only,
6645                            executable: source.fidelity.executable,
6646                            link_count: final_link_count,
6647                        },
6648                    )?;
6649                    validate_retained_authority()?;
6650                    checkpoint(TransactionV1Checkpoint::MoveAbortRollbackClaimRetired(
6651                        operation_index,
6652                    ));
6653                }
6654
6655                let source_claim_link_count =
6656                    source.link_count.checked_add(1).ok_or_else(|| {
6657                        FolderbaseError::MigrationSourceChanged(filesystem.display(source.path))
6658                    })?;
6659                transaction.private.claims.remove_exact_owned_regular(
6660                    OsStr::new(&source_name),
6661                    ExactRegularLeaf {
6662                        physical_identity_sha256: source.physical_identity_sha256,
6663                        device_sha256: source.device_sha256,
6664                        bytes: source.bytes,
6665                        sha256: source.sha256,
6666                        read_only: source.fidelity.read_only,
6667                        executable: source.fidelity.executable,
6668                        link_count: source_claim_link_count,
6669                    },
6670                )?;
6671                validate_retained_authority()?;
6672                checkpoint(TransactionV1Checkpoint::MoveAbortSourceClaimRetired(
6673                    operation_index,
6674                ));
6675                filesystem.exact_regular_fact(
6676                    source.path,
6677                    ExactRegularLeaf {
6678                        physical_identity_sha256: source.physical_identity_sha256,
6679                        device_sha256: source.device_sha256,
6680                        bytes: source.bytes,
6681                        sha256: source.sha256,
6682                        read_only: source.fidelity.read_only,
6683                        executable: source.fidelity.executable,
6684                        link_count: source.link_count,
6685                    },
6686                )?;
6687                validate_retained_authority()?;
6688                PrivateAbortWorkReceiptV1::new(
6689                    transaction,
6690                    operation_index,
6691                    Some(source.physical_identity_sha256.to_owned()),
6692                    Vec::new(),
6693                )?
6694            }
6695        }
6696        ProgramStepV1::CreateDirectory { target, fidelity } => {
6697            let publish_name = private_claim_name(operation_index, "publish");
6698            let claim =
6699                private_directory_fact_if_present(&transaction.private.claims, &publish_name)?;
6700            let claims = if let Some(claim) = claim {
6701                let exact = ExactDirectoryLeaf {
6702                    physical_identity_sha256: &claim.physical_identity_sha256,
6703                    device_sha256: &claim.device_sha256,
6704                    read_only: claim.read_only,
6705                    executable: directory_fact_executable(&claim),
6706                };
6707                if exact.device_sha256 != target.device_sha256
6708                    || exact.read_only != fidelity.read_only
6709                    || exact.executable != fidelity.executable
6710                {
6711                    return Err(FolderbaseError::MigrationVerificationFailed(
6712                        transaction
6713                            .private
6714                            .claims
6715                            .display_path(OsStr::new(&publish_name)),
6716                    ));
6717                }
6718                transaction
6719                    .private
6720                    .claims
6721                    .exact_empty_directory_fact(OsStr::new(&publish_name), exact)?;
6722                if filesystem.metadata(target.path)?.is_some() {
6723                    validate_retained_authority()?;
6724                    transaction
6725                        .private
6726                        .claims
6727                        .remove_exact_empty_directory(OsStr::new(&publish_name), exact)?;
6728                    validate_retained_authority()?;
6729                    Vec::new()
6730                } else {
6731                    vec![PrivateAbortClaimV1::Directory {
6732                        name: publish_name,
6733                        physical_identity_sha256: claim.physical_identity_sha256.clone(),
6734                        device_sha256: claim.device_sha256.clone(),
6735                        read_only: exact.read_only,
6736                        executable: exact.executable,
6737                        empty: true,
6738                    }]
6739                }
6740            } else {
6741                Vec::new()
6742            };
6743            validate_retained_authority()?;
6744            PrivateAbortWorkReceiptV1::new(transaction, operation_index, None, claims)?
6745        }
6746        ProgramStepV1::CreateFile { target, image } => {
6747            let publish_name = private_claim_name(operation_index, "publish");
6748            let rollback_name = private_claim_name(operation_index, "rollback");
6749            let Some(mut publish) = private_regular_fact_if_present(
6750                &transaction.private.claims,
6751                &publish_name,
6752                image.sha256,
6753            )?
6754            else {
6755                validate_retained_authority()?;
6756                return finish_private_abort_work_receipt(
6757                    filesystem,
6758                    transaction,
6759                    operation_index,
6760                    PrivateAbortWorkReceiptV1::new(transaction, operation_index, None, Vec::new())?,
6761                    checkpoint,
6762                    &validate_retained_authority,
6763                );
6764            };
6765            let require_publish_shape = |fact: &MigrationRegularFact, link_count: u64| {
6766                if fact.device_sha256 != target.device_sha256
6767                    || fact.bytes != image.bytes
6768                    || fact.read_only != image.fidelity.read_only
6769                    || regular_fact_executable(fact) != image.fidelity.executable
6770                    || fact.link_count != link_count
6771                {
6772                    return Err(FolderbaseError::MigrationVerificationFailed(
6773                        transaction
6774                            .private
6775                            .claims
6776                            .display_path(OsStr::new(&publish_name)),
6777                    ));
6778                }
6779                Ok(())
6780            };
6781            let mut rollback = private_regular_fact_if_present(
6782                &transaction.private.claims,
6783                &rollback_name,
6784                image.sha256,
6785            )?;
6786            if rollback.is_none() {
6787                let visible_is_exact = regular_fact_matches_program(
6788                    filesystem,
6789                    target.path,
6790                    Some(&publish.physical_identity_sha256),
6791                    image.bytes,
6792                    image.sha256,
6793                    image.fidelity.read_only,
6794                    image.fidelity.executable,
6795                )?
6796                .is_some();
6797                if visible_is_exact {
6798                    require_publish_shape(&publish, 2)?;
6799                    let expected = ExactRegularLeaf {
6800                        physical_identity_sha256: &publish.physical_identity_sha256,
6801                        device_sha256: target.device_sha256,
6802                        bytes: image.bytes,
6803                        sha256: image.sha256,
6804                        read_only: image.fidelity.read_only,
6805                        executable: image.fidelity.executable,
6806                        link_count: 2,
6807                    };
6808                    filesystem.exact_regular_fact(target.path, expected)?;
6809                    let target_name = target.path.file_name().ok_or_else(|| {
6810                        invalid_journal(target.path, "program target has no leaf name")
6811                    })?;
6812                    validate_retained_authority()?;
6813                    match filesystem.claim_exact_leaf_through(ExactLeafClaimRequest {
6814                        source_parent: retained_parents.get(target.parent)?,
6815                        source_name: target_name,
6816                        destination: &transaction.private.claims,
6817                        destination_name: &rollback_name,
6818                        expectation: ExactLeafClaimExpectation::Regular(expected),
6819                        existing_source: ExactExistingClaimSource::Absent,
6820                    })? {
6821                        ExactLeafClaimResult::Regular(_) => {}
6822                        ExactLeafClaimResult::Directory(_) => {
6823                            return Err(FolderbaseError::MigrationVerificationFailed(
6824                                transaction
6825                                    .private
6826                                    .claims
6827                                    .display_path(OsStr::new(&rollback_name)),
6828                            ));
6829                        }
6830                    }
6831                    validate_retained_authority()?;
6832                    rollback = private_regular_fact_if_present(
6833                        &transaction.private.claims,
6834                        &rollback_name,
6835                        image.sha256,
6836                    )?;
6837                } else {
6838                    require_publish_shape(&publish, 1)?;
6839                    let expected = ExactRegularLeaf {
6840                        physical_identity_sha256: &publish.physical_identity_sha256,
6841                        device_sha256: target.device_sha256,
6842                        bytes: image.bytes,
6843                        sha256: image.sha256,
6844                        read_only: image.fidelity.read_only,
6845                        executable: image.fidelity.executable,
6846                        link_count: 1,
6847                    };
6848                    validate_retained_authority()?;
6849                    transaction
6850                        .private
6851                        .claims
6852                        .remove_exact_owned_regular(OsStr::new(&publish_name), expected)?;
6853                    validate_retained_authority()?;
6854                    return finish_private_abort_work_receipt(
6855                        filesystem,
6856                        transaction,
6857                        operation_index,
6858                        PrivateAbortWorkReceiptV1::new(
6859                            transaction,
6860                            operation_index,
6861                            None,
6862                            Vec::new(),
6863                        )?,
6864                        checkpoint,
6865                        &validate_retained_authority,
6866                    );
6867                }
6868            }
6869            let rollback = rollback.ok_or_else(|| {
6870                FolderbaseError::MigrationVerificationFailed(
6871                    transaction
6872                        .private
6873                        .claims
6874                        .display_path(OsStr::new(&rollback_name)),
6875                )
6876            })?;
6877            publish = private_regular_fact_if_present(
6878                &transaction.private.claims,
6879                &publish_name,
6880                image.sha256,
6881            )?
6882            .ok_or_else(|| {
6883                FolderbaseError::MigrationVerificationFailed(
6884                    transaction
6885                        .private
6886                        .claims
6887                        .display_path(OsStr::new(&publish_name)),
6888                )
6889            })?;
6890            require_publish_shape(&publish, 2)?;
6891            if rollback.physical_identity_sha256 != publish.physical_identity_sha256
6892                || rollback.device_sha256 != publish.device_sha256
6893                || rollback.bytes != publish.bytes
6894                || rollback.unix_mode != publish.unix_mode
6895                || rollback.link_count != 2
6896            {
6897                return Err(FolderbaseError::MigrationVerificationFailed(
6898                    transaction
6899                        .private
6900                        .claims
6901                        .display_path(OsStr::new(&rollback_name)),
6902                ));
6903            }
6904            let claims = [&publish_name, &rollback_name]
6905                .into_iter()
6906                .map(|name| PrivateAbortClaimV1::Regular {
6907                    name: name.to_owned(),
6908                    physical_identity_sha256: publish.physical_identity_sha256.clone(),
6909                    device_sha256: publish.device_sha256.clone(),
6910                    bytes: image.bytes,
6911                    sha256: image.sha256.to_owned(),
6912                    read_only: image.fidelity.read_only,
6913                    executable: image.fidelity.executable,
6914                    link_count: 2,
6915                })
6916                .collect();
6917            validate_retained_authority()?;
6918            PrivateAbortWorkReceiptV1::new(transaction, operation_index, None, claims)?
6919        }
6920        ProgramStepV1::ReplaceFile { target, image, .. } => {
6921            let source_name = private_claim_name(operation_index, "source");
6922            let publish_name = private_claim_name(operation_index, "publish");
6923            let rollback_name = private_claim_name(operation_index, "rollback");
6924            let mut source = private_regular_fact_if_present(
6925                &transaction.private.claims,
6926                &source_name,
6927                target.sha256,
6928            )?;
6929            let publish = private_regular_fact_if_present(
6930                &transaction.private.claims,
6931                &publish_name,
6932                image.sha256,
6933            )?;
6934            let mut rollback = private_regular_fact_if_present(
6935                &transaction.private.claims,
6936                &rollback_name,
6937                image.sha256,
6938            )?;
6939
6940            if source.is_none() {
6941                filesystem.exact_regular_fact(
6942                    target.path,
6943                    ExactRegularLeaf {
6944                        physical_identity_sha256: target.physical_identity_sha256,
6945                        device_sha256: target.device_sha256,
6946                        bytes: target.bytes,
6947                        sha256: target.sha256,
6948                        read_only: target.fidelity.read_only,
6949                        executable: target.fidelity.executable,
6950                        link_count: target.link_count,
6951                    },
6952                )?;
6953                if let Some(rollback_fact) = rollback.as_ref() {
6954                    let exact = ExactRegularLeaf {
6955                        physical_identity_sha256: &rollback_fact.physical_identity_sha256,
6956                        device_sha256: target.device_sha256,
6957                        bytes: image.bytes,
6958                        sha256: image.sha256,
6959                        read_only: image.fidelity.read_only,
6960                        executable: image.fidelity.executable,
6961                        link_count: 1 + u64::from(publish.is_some()),
6962                    };
6963                    transaction
6964                        .private
6965                        .claims
6966                        .exact_regular_fact(OsStr::new(&rollback_name), exact)?;
6967                }
6968                if let Some(publish_fact) = publish.as_ref() {
6969                    if rollback.as_ref().is_some_and(|rollback| {
6970                        rollback.physical_identity_sha256 != publish_fact.physical_identity_sha256
6971                    }) {
6972                        return Err(FolderbaseError::MigrationVerificationFailed(
6973                            transaction
6974                                .private
6975                                .claims
6976                                .display_path(OsStr::new(&rollback_name)),
6977                        ));
6978                    }
6979                    validate_retained_authority()?;
6980                    transaction.private.claims.remove_exact_owned_regular(
6981                        OsStr::new(&publish_name),
6982                        ExactRegularLeaf {
6983                            physical_identity_sha256: &publish_fact.physical_identity_sha256,
6984                            device_sha256: target.device_sha256,
6985                            bytes: image.bytes,
6986                            sha256: image.sha256,
6987                            read_only: image.fidelity.read_only,
6988                            executable: image.fidelity.executable,
6989                            link_count: 1 + u64::from(rollback.is_some()),
6990                        },
6991                    )?;
6992                    validate_retained_authority()?;
6993                }
6994                let claims = if let Some(rollback_fact) = rollback.take() {
6995                    let exact = ExactRegularLeaf {
6996                        physical_identity_sha256: &rollback_fact.physical_identity_sha256,
6997                        device_sha256: target.device_sha256,
6998                        bytes: image.bytes,
6999                        sha256: image.sha256,
7000                        read_only: image.fidelity.read_only,
7001                        executable: image.fidelity.executable,
7002                        link_count: 1,
7003                    };
7004                    transaction
7005                        .private
7006                        .claims
7007                        .exact_regular_fact(OsStr::new(&rollback_name), exact)?;
7008                    vec![PrivateAbortClaimV1::Regular {
7009                        name: rollback_name,
7010                        physical_identity_sha256: rollback_fact.physical_identity_sha256,
7011                        device_sha256: target.device_sha256.to_owned(),
7012                        bytes: image.bytes,
7013                        sha256: image.sha256.to_owned(),
7014                        read_only: image.fidelity.read_only,
7015                        executable: image.fidelity.executable,
7016                        link_count: 1,
7017                    }]
7018                } else {
7019                    Vec::new()
7020                };
7021                PrivateAbortWorkReceiptV1::new(
7022                    transaction,
7023                    operation_index,
7024                    Some(target.physical_identity_sha256.to_owned()),
7025                    claims,
7026                )?
7027            } else {
7028                let visible_original = regular_fact_matches_program(
7029                    filesystem,
7030                    target.path,
7031                    Some(target.physical_identity_sha256),
7032                    target.bytes,
7033                    target.sha256,
7034                    target.fidelity.read_only,
7035                    target.fidelity.executable,
7036                )?
7037                .is_some();
7038                let visible_publish_identity = publish
7039                    .as_ref()
7040                    .map(|fact| fact.physical_identity_sha256.as_str());
7041                let visible_replacement = visible_publish_identity.is_some()
7042                    && regular_fact_matches_program(
7043                        filesystem,
7044                        target.path,
7045                        visible_publish_identity,
7046                        image.bytes,
7047                        image.sha256,
7048                        image.fidelity.read_only,
7049                        image.fidelity.executable,
7050                    )?
7051                    .is_some();
7052                if !visible_original
7053                    && !visible_replacement
7054                    && filesystem.metadata(target.path)?.is_some()
7055                {
7056                    return Err(FolderbaseError::WouldOverwrite(
7057                        filesystem.display(target.path),
7058                    ));
7059                }
7060                if visible_replacement && rollback.is_some() {
7061                    return Err(FolderbaseError::MigrationVerificationFailed(
7062                        transaction
7063                            .private
7064                            .claims
7065                            .display_path(OsStr::new(&rollback_name)),
7066                    ));
7067                }
7068
7069                let original_link_count = target
7070                    .link_count
7071                    .checked_add(u64::from(visible_original))
7072                    .ok_or_else(|| {
7073                        FolderbaseError::MigrationSourceChanged(filesystem.display(target.path))
7074                    })?;
7075                let original = ExactRegularLeaf {
7076                    physical_identity_sha256: target.physical_identity_sha256,
7077                    device_sha256: target.device_sha256,
7078                    bytes: target.bytes,
7079                    sha256: target.sha256,
7080                    read_only: target.fidelity.read_only,
7081                    executable: target.fidelity.executable,
7082                    link_count: original_link_count,
7083                };
7084                transaction
7085                    .private
7086                    .claims
7087                    .exact_regular_fact(OsStr::new(&source_name), original)?;
7088                if visible_original {
7089                    filesystem.exact_regular_fact(target.path, original)?;
7090                }
7091
7092                if let Some(publish_fact) = publish.as_ref() {
7093                    let expected_link_count =
7094                        1 + u64::from(visible_replacement || rollback.is_some());
7095                    let exact = ExactRegularLeaf {
7096                        physical_identity_sha256: &publish_fact.physical_identity_sha256,
7097                        device_sha256: target.device_sha256,
7098                        bytes: image.bytes,
7099                        sha256: image.sha256,
7100                        read_only: image.fidelity.read_only,
7101                        executable: image.fidelity.executable,
7102                        link_count: expected_link_count,
7103                    };
7104                    transaction
7105                        .private
7106                        .claims
7107                        .exact_regular_fact(OsStr::new(&publish_name), exact)?;
7108                    if visible_replacement {
7109                        filesystem.exact_regular_fact(target.path, exact)?;
7110                    }
7111                } else if visible_replacement {
7112                    return Err(FolderbaseError::MigrationVerificationFailed(
7113                        transaction
7114                            .private
7115                            .claims
7116                            .display_path(OsStr::new(&publish_name)),
7117                    ));
7118                }
7119                if let Some(rollback_fact) = rollback.as_ref() {
7120                    let expected_link_count = 1 + u64::from(publish.is_some());
7121                    let exact = ExactRegularLeaf {
7122                        physical_identity_sha256: &rollback_fact.physical_identity_sha256,
7123                        device_sha256: target.device_sha256,
7124                        bytes: image.bytes,
7125                        sha256: image.sha256,
7126                        read_only: image.fidelity.read_only,
7127                        executable: image.fidelity.executable,
7128                        link_count: expected_link_count,
7129                    };
7130                    transaction
7131                        .private
7132                        .claims
7133                        .exact_regular_fact(OsStr::new(&rollback_name), exact)?;
7134                    if publish.as_ref().is_some_and(|publish| {
7135                        publish.physical_identity_sha256 != rollback_fact.physical_identity_sha256
7136                    }) {
7137                        return Err(FolderbaseError::MigrationVerificationFailed(
7138                            transaction
7139                                .private
7140                                .claims
7141                                .display_path(OsStr::new(&rollback_name)),
7142                        ));
7143                    }
7144                }
7145
7146                if visible_replacement {
7147                    let publish_fact = publish.as_ref().ok_or_else(|| {
7148                        FolderbaseError::MigrationVerificationFailed(
7149                            transaction
7150                                .private
7151                                .claims
7152                                .display_path(OsStr::new(&publish_name)),
7153                        )
7154                    })?;
7155                    let target_name = target.path.file_name().ok_or_else(|| {
7156                        invalid_journal(target.path, "program target has no leaf name")
7157                    })?;
7158                    let expected = ExactRegularLeaf {
7159                        physical_identity_sha256: &publish_fact.physical_identity_sha256,
7160                        device_sha256: target.device_sha256,
7161                        bytes: image.bytes,
7162                        sha256: image.sha256,
7163                        read_only: image.fidelity.read_only,
7164                        executable: image.fidelity.executable,
7165                        link_count: 2,
7166                    };
7167                    validate_retained_authority()?;
7168                    match filesystem.claim_exact_leaf_through(ExactLeafClaimRequest {
7169                        source_parent: retained_parents.get(target.parent)?,
7170                        source_name: target_name,
7171                        destination: &transaction.private.claims,
7172                        destination_name: &rollback_name,
7173                        expectation: ExactLeafClaimExpectation::Regular(expected),
7174                        existing_source: ExactExistingClaimSource::Absent,
7175                    })? {
7176                        ExactLeafClaimResult::Regular(_) => {}
7177                        ExactLeafClaimResult::Directory(_) => {
7178                            return Err(FolderbaseError::MigrationVerificationFailed(
7179                                transaction
7180                                    .private
7181                                    .claims
7182                                    .display_path(OsStr::new(&rollback_name)),
7183                            ));
7184                        }
7185                    }
7186                    validate_retained_authority()?;
7187                    rollback = private_regular_fact_if_present(
7188                        &transaction.private.claims,
7189                        &rollback_name,
7190                        image.sha256,
7191                    )?;
7192                }
7193
7194                if let Some(publish_fact) = publish.as_ref() {
7195                    let expected_link_count = 1 + u64::from(rollback.is_some());
7196                    let expected = ExactRegularLeaf {
7197                        physical_identity_sha256: &publish_fact.physical_identity_sha256,
7198                        device_sha256: target.device_sha256,
7199                        bytes: image.bytes,
7200                        sha256: image.sha256,
7201                        read_only: image.fidelity.read_only,
7202                        executable: image.fidelity.executable,
7203                        link_count: expected_link_count,
7204                    };
7205                    if rollback.as_ref().is_some_and(|rollback| {
7206                        rollback.physical_identity_sha256 != publish_fact.physical_identity_sha256
7207                    }) {
7208                        return Err(FolderbaseError::MigrationVerificationFailed(
7209                            transaction
7210                                .private
7211                                .claims
7212                                .display_path(OsStr::new(&rollback_name)),
7213                        ));
7214                    }
7215                    validate_retained_authority()?;
7216                    transaction
7217                        .private
7218                        .claims
7219                        .remove_exact_owned_regular(OsStr::new(&publish_name), expected)?;
7220                    validate_retained_authority()?;
7221                }
7222
7223                if filesystem.metadata(target.path)?.is_none() {
7224                    let target_name = target.path.file_name().ok_or_else(|| {
7225                        invalid_journal(target.path, "program target has no leaf name")
7226                    })?;
7227                    validate_retained_authority()?;
7228                    transaction.private.claims.restore_exact_regular_through(
7229                        OsStr::new(&source_name),
7230                        retained_parents.get(target.parent)?,
7231                        target_name,
7232                        ExactRegularLeaf {
7233                            physical_identity_sha256: target.physical_identity_sha256,
7234                            device_sha256: target.device_sha256,
7235                            bytes: target.bytes,
7236                            sha256: target.sha256,
7237                            read_only: target.fidelity.read_only,
7238                            executable: target.fidelity.executable,
7239                            link_count: target.link_count,
7240                        },
7241                    )?;
7242                    validate_retained_authority()?;
7243                } else {
7244                    validate_retained_authority()?;
7245                    transaction.private.claims.remove_exact_owned_regular(
7246                        OsStr::new(&source_name),
7247                        ExactRegularLeaf {
7248                            physical_identity_sha256: target.physical_identity_sha256,
7249                            device_sha256: target.device_sha256,
7250                            bytes: target.bytes,
7251                            sha256: target.sha256,
7252                            read_only: target.fidelity.read_only,
7253                            executable: target.fidelity.executable,
7254                            link_count: target.link_count.checked_add(1).ok_or_else(|| {
7255                                FolderbaseError::MigrationSourceChanged(
7256                                    filesystem.display(target.path),
7257                                )
7258                            })?,
7259                        },
7260                    )?;
7261                    validate_retained_authority()?;
7262                }
7263
7264                let final_original = ExactRegularLeaf {
7265                    physical_identity_sha256: target.physical_identity_sha256,
7266                    device_sha256: target.device_sha256,
7267                    bytes: target.bytes,
7268                    sha256: target.sha256,
7269                    read_only: target.fidelity.read_only,
7270                    executable: target.fidelity.executable,
7271                    link_count: target.link_count,
7272                };
7273                filesystem.exact_regular_fact(target.path, final_original)?;
7274                source = private_regular_fact_if_present(
7275                    &transaction.private.claims,
7276                    &source_name,
7277                    target.sha256,
7278                )?;
7279                if source.is_some() {
7280                    return Err(FolderbaseError::MigrationVerificationFailed(
7281                        transaction
7282                            .private
7283                            .claims
7284                            .display_path(OsStr::new(&source_name)),
7285                    ));
7286                }
7287
7288                let mut claims = Vec::new();
7289                if let Some(rollback) = rollback {
7290                    let exact = ExactRegularLeaf {
7291                        physical_identity_sha256: &rollback.physical_identity_sha256,
7292                        device_sha256: target.device_sha256,
7293                        bytes: image.bytes,
7294                        sha256: image.sha256,
7295                        read_only: image.fidelity.read_only,
7296                        executable: image.fidelity.executable,
7297                        link_count: 1,
7298                    };
7299                    transaction
7300                        .private
7301                        .claims
7302                        .exact_regular_fact(OsStr::new(&rollback_name), exact)?;
7303                    claims.push(PrivateAbortClaimV1::Regular {
7304                        name: rollback_name,
7305                        physical_identity_sha256: rollback.physical_identity_sha256,
7306                        device_sha256: target.device_sha256.to_owned(),
7307                        bytes: image.bytes,
7308                        sha256: image.sha256.to_owned(),
7309                        read_only: image.fidelity.read_only,
7310                        executable: image.fidelity.executable,
7311                        link_count: 1,
7312                    });
7313                }
7314                validate_retained_authority()?;
7315                PrivateAbortWorkReceiptV1::new(
7316                    transaction,
7317                    operation_index,
7318                    Some(target.physical_identity_sha256.to_owned()),
7319                    claims,
7320                )?
7321            }
7322        }
7323    };
7324    finish_private_abort_work_receipt(
7325        filesystem,
7326        transaction,
7327        operation_index,
7328        receipt,
7329        checkpoint,
7330        &validate_retained_authority,
7331    )
7332}
7333
7334fn preflight_transaction_v1_rollback_scope(
7335    filesystem: &MigrationFilesystem,
7336    transaction: &PreparedTransactionV1,
7337    current: &TransactionJournalGenerationV1,
7338) -> std::result::Result<(), (usize, FolderbaseError)> {
7339    let mut upper_bound = current.operation_cursor();
7340    if let Some(in_flight) = current.in_flight_operation() {
7341        upper_bound = upper_bound.max(in_flight.saturating_add(1));
7342    }
7343    for operation_index in (0..upper_bound).rev() {
7344        if let Err(error) =
7345            transaction
7346                .program
7347                .retain_step_parents(filesystem, operation_index, current)
7348        {
7349            return Err((operation_index, error));
7350        }
7351    }
7352    Ok(())
7353}
7354
7355fn execute_transaction_v1_rollback_with_hook(
7356    filesystem: &MigrationFilesystem,
7357    transaction: &mut PreparedTransactionV1,
7358    mut checkpoint: impl FnMut(TransactionV1Checkpoint),
7359) -> Result<RollbackResult> {
7360    filesystem.require_atomic_noreplace()?;
7361    let mut removed_paths = Vec::new();
7362    loop {
7363        let current = transaction
7364            .generations
7365            .last()
7366            .expect("transaction-v1 has a validated generation")
7367            .clone();
7368        if finish_receipted_private_publication(filesystem, transaction, &mut checkpoint)? {
7369            continue;
7370        }
7371        if current.phase() == TransactionPhaseV1::RolledBack {
7372            validate_transaction_v1_environment(filesystem, transaction, &current)?;
7373            reconcile_plan_terminal(filesystem, &transaction.program, MigrationState::RolledBack);
7374            return Ok(RollbackResult {
7375                migration_id: transaction.program.transaction_id().to_owned(),
7376                removed_paths,
7377                state: MigrationState::RolledBack,
7378            });
7379        }
7380        if current.direction() == TransactionDirectionV1::Apply {
7381            if let Some(index) = current.in_flight_operation()
7382                && let Some(receipt) =
7383                    load_private_leaf_receipt(transaction, index, PrivateReceiptDirectionV1::Apply)?
7384                && !is_exact_create_directory_prepublication_receipt(transaction, index, &receipt)?
7385            {
7386                if let Err(error) =
7387                    verify_apply_private_receipt(filesystem, transaction, index, &receipt)
7388                {
7389                    if is_private_transaction_integrity_error(&error) {
7390                        return Err(error);
7391                    }
7392                    record_transaction_v1_conflict(filesystem, transaction, index, &error)?;
7393                    checkpoint(TransactionV1Checkpoint::ConflictRecorded(index));
7394                    return Err(error);
7395                }
7396                let journal_receipt = current.next_apply_receipt(
7397                    &transaction.program,
7398                    index,
7399                    receipt.after_identity_sha256,
7400                )?;
7401                append_transaction_v1_generation(filesystem, transaction, journal_receipt)?;
7402                checkpoint(TransactionV1Checkpoint::JournalApplyReceiptPersisted(index));
7403                continue;
7404            }
7405            let requested = current.next_rollback_requested(&transaction.program)?;
7406            append_transaction_v1_generation(filesystem, transaction, requested)?;
7407            checkpoint(TransactionV1Checkpoint::RollbackRequested);
7408            continue;
7409        }
7410        if let Err((operation_index, error)) =
7411            preflight_transaction_v1_rollback_scope(filesystem, transaction, &current)
7412        {
7413            if is_private_transaction_integrity_error(&error) {
7414                return Err(error);
7415            }
7416            record_transaction_v1_conflict(filesystem, transaction, operation_index, &error)?;
7417            checkpoint(TransactionV1Checkpoint::ConflictRecorded(operation_index));
7418            return Err(error);
7419        }
7420        if let Some(index) = current.in_flight_operation() {
7421            if current.receipt_identity(index).is_none() {
7422                let private_receipt_sha256 = match abort_transaction_v1_in_flight_apply(
7423                    filesystem,
7424                    transaction,
7425                    index,
7426                    &mut checkpoint,
7427                ) {
7428                    Ok(digest) => digest,
7429                    Err(error) => {
7430                        if is_private_transaction_integrity_error(&error) {
7431                            return Err(error);
7432                        }
7433                        record_transaction_v1_conflict(filesystem, transaction, index, &error)?;
7434                        checkpoint(TransactionV1Checkpoint::ConflictRecorded(index));
7435                        return Err(error);
7436                    }
7437                };
7438                let aborted =
7439                    current.next_aborted_apply(&transaction.program, private_receipt_sha256)?;
7440                append_transaction_v1_generation(filesystem, transaction, aborted)?;
7441                checkpoint(TransactionV1Checkpoint::JournalAbortReceiptPersisted(index));
7442                continue;
7443            }
7444            let (removed, restored_identity) = match rollback_transaction_v1_step(
7445                filesystem,
7446                transaction,
7447                index,
7448                current.receipt_identity(index),
7449                &mut checkpoint,
7450            ) {
7451                Ok(outcome) => outcome,
7452                Err(error) => {
7453                    if is_private_transaction_integrity_error(&error) {
7454                        return Err(error);
7455                    }
7456                    record_transaction_v1_conflict(filesystem, transaction, index, &error)?;
7457                    checkpoint(TransactionV1Checkpoint::ConflictRecorded(index));
7458                    return Err(error);
7459                }
7460            };
7461            removed_paths.extend(removed);
7462            let receipt_head = transaction
7463                .generations
7464                .last()
7465                .expect("inverse execution retains a validated journal head")
7466                .clone();
7467            let receipt = receipt_head.next_rollback_receipt(
7468                &transaction.program,
7469                index,
7470                restored_identity,
7471            )?;
7472            append_transaction_v1_generation(filesystem, transaction, receipt)?;
7473            checkpoint(TransactionV1Checkpoint::JournalRollbackReceiptPersisted(
7474                index,
7475            ));
7476            continue;
7477        }
7478        if current.operation_cursor() == 0 {
7479            let rolled_back = current.next_rolled_back(&transaction.program)?;
7480            append_transaction_v1_generation(filesystem, transaction, rolled_back)?;
7481            continue;
7482        }
7483        let index = current.operation_cursor() - 1;
7484        let intent = current.next_rollback_intent(&transaction.program, index)?;
7485        append_transaction_v1_generation(filesystem, transaction, intent)?;
7486    }
7487}
7488
7489fn reconcile_plan_terminal(
7490    filesystem: &MigrationFilesystem,
7491    program: &MutationProgramV1,
7492    state: MigrationState,
7493) {
7494    let migration_id = program.transaction_id();
7495    let plan_relative = migration_plan_relative(migration_id);
7496    let Ok(bytes) = filesystem.read_regular_bounded(&plan_relative, MAX_MIGRATION_PLAN_BYTES)
7497    else {
7498        return;
7499    };
7500    let Ok(mut plan) = serde_json::from_slice::<MigrationPlan>(&bytes) else {
7501        return;
7502    };
7503    if plan.protocol_version != "0.2.0"
7504        || plan.id != migration_id
7505        || plan.root != filesystem.display_root()
7506        || plan.approval_digest.as_deref() != Some(program.approval_digest())
7507        || plan_digest(&plan).ok().as_deref() != Some(program.approval_digest())
7508    {
7509        return;
7510    }
7511    plan.state = state;
7512    let Ok(mut content) = serde_json::to_vec_pretty(&plan) else {
7513        return;
7514    };
7515    content.push(b'\n');
7516    let _ = filesystem.replace(&plan_relative, &content);
7517}
7518
7519fn is_provable_prepared_transaction_v1_prefix(
7520    filesystem: &MigrationFilesystem,
7521    transaction_root: &Path,
7522) -> Result<bool> {
7523    let transaction = filesystem.open_private_directory(transaction_root)?;
7524    let entries = transaction.closed_entries(8)?;
7525    let directory_names = BTreeSet::from([
7526        OsString::from("journal"),
7527        OsString::from("stages"),
7528        OsString::from("claims"),
7529        OsString::from("snapshots"),
7530        OsString::from("receipts"),
7531    ]);
7532    for (name, is_directory) in &entries {
7533        let admitted = if directory_names.contains(name) {
7534            *is_directory
7535        } else {
7536            !*is_directory
7537                && matches!(
7538                    name.to_str(),
7539                    Some("program.json" | ".program.json.preparing")
7540                )
7541        };
7542        if !admitted {
7543            return Err(FolderbaseError::InvalidRecord {
7544                path: filesystem.display(&transaction_root.join(name)),
7545                message: "transaction-v1 contains an ambiguous pre-Prepared artifact".to_owned(),
7546            });
7547        }
7548    }
7549
7550    if entries
7551        .iter()
7552        .any(|(name, _)| name == OsStr::new("journal"))
7553    {
7554        let journal = transaction.open_directory("journal")?;
7555        let journal_root = transaction_root.join("journal");
7556        let journal_entries =
7557            journal.closed_entries(maximum_journal_directory_entries(MAX_JOURNAL_GENERATIONS))?;
7558        let classified = classify_journal_entries(
7559            filesystem,
7560            &journal,
7561            &journal_root,
7562            &journal_entries,
7563            MAX_JOURNAL_GENERATIONS,
7564        )?;
7565        if !classified.generation_names.is_empty() {
7566            return Ok(false);
7567        }
7568    }
7569    for directory_name in ["claims", "receipts"] {
7570        if entries
7571            .iter()
7572            .any(|(name, _)| name == OsStr::new(directory_name))
7573        {
7574            let directory = transaction.open_directory(directory_name)?;
7575            if !directory.closed_entries(1)?.is_empty() {
7576                return Err(FolderbaseError::InvalidRecord {
7577                    path: filesystem.display(&transaction_root.join(directory_name)),
7578                    message: "pre-Prepared transaction contains execution evidence".to_owned(),
7579                });
7580            }
7581        }
7582    }
7583    Ok(true)
7584}
7585
7586fn prepare_transaction_v1(
7587    filesystem: &MigrationFilesystem,
7588    plan: &MigrationPlan,
7589    approval_digest: &str,
7590    root_identity_sha256: String,
7591) -> Result<PreparedTransactionV1> {
7592    let migration_root = PathBuf::from(MIGRATIONS_DIR).join(&plan.id);
7593    let snapshots = migration_root.join("snapshots");
7594    filesystem.ensure_directory(Path::new(STATE_DIR))?;
7595    filesystem.ensure_directory(Path::new(MIGRATIONS_DIR))?;
7596    filesystem.ensure_directory(&migration_root)?;
7597    if filesystem.metadata(&snapshots)?.is_some() {
7598        filesystem.ensure_directory(&snapshots)?;
7599        let _ = filesystem
7600            .closed_regular_file_names(&snapshots, plan.operations.len().saturating_add(1))?;
7601    }
7602    let transaction_root = migration_root.join(TRANSACTION_DIRECTORY);
7603    let program_path = transaction_root.join("program.json");
7604    let journal_root = transaction_root.join("journal");
7605    let transaction_exists = filesystem.metadata(&transaction_root)?.is_some();
7606    if transaction_exists {
7607        match reopen_transaction_v1(filesystem, &migration_root, None) {
7608            Ok(reopened) => {
7609                if !reopened.program.matches_approval(
7610                    &plan.id,
7611                    approval_digest,
7612                    &root_identity_sha256,
7613                ) {
7614                    return Err(FolderbaseError::MigrationApprovalMismatch);
7615                }
7616                return Ok(reopened);
7617            }
7618            Err(reopen_error) => {
7619                if !is_provable_prepared_transaction_v1_prefix(filesystem, &transaction_root)? {
7620                    return Err(reopen_error);
7621                }
7622            }
7623        }
7624    }
7625    let materialization = compile_program_materialization(filesystem, plan)?;
7626
7627    for directory in [
7628        transaction_root.clone(),
7629        journal_root.clone(),
7630        transaction_root.join("stages"),
7631        transaction_root.join("claims"),
7632        transaction_root.join("snapshots"),
7633        transaction_root.join("receipts"),
7634    ] {
7635        filesystem.ensure_private_directory(&directory)?;
7636    }
7637    let private = filesystem.open_private_directory(&transaction_root)?;
7638    let private_journal = private.open_directory("journal")?;
7639    let private_stages = private.open_directory("stages")?;
7640    let private_snapshots = private.open_directory("snapshots")?;
7641    let program = MutationProgramV1::compile(
7642        plan,
7643        approval_digest,
7644        root_identity_sha256,
7645        filesystem,
7646        &private_stages,
7647        &private_snapshots,
7648        materialization,
7649        |operation, current| {
7650            structural_result_bytes_from(
7651                &filesystem.display(
7652                    operation
7653                        .structural_source_path()
7654                        .unwrap_or_else(|| Path::new("<mutation-program-v1>")),
7655                ),
7656                current,
7657                operation,
7658            )
7659        },
7660    )?;
7661    let program_bytes = program.encode(&filesystem.display(&program_path))?;
7662    private.publish_recoverable_new("program.json", ".program.json.preparing", &program_bytes)?;
7663    let reopened_bytes =
7664        private.read_regular_bounded(OsStr::new("program.json"), MAX_PROGRAM_BYTES)?;
7665    let reopened = MutationProgramV1::decode(&filesystem.display(&program_path), &reopened_bytes)?;
7666    if reopened != program {
7667        return Err(FolderbaseError::MigrationVerificationFailed(
7668            filesystem.display(&program_path),
7669        ));
7670    }
7671    let program_digest = reopened.digest(&filesystem.display(&program_path))?;
7672    let initial = TransactionJournalGenerationV1::prepared(&reopened, program_digest.clone())?;
7673    let initial_path = journal_root.join(initial.file_name());
7674    let initial_bytes = initial.encode(&filesystem.display(&initial_path))?;
7675    private_journal.publish_recoverable_new_via_uncommitted_write(
7676        &initial.file_name(),
7677        JOURNAL_GENERATION_STAGING_NAME,
7678        JOURNAL_GENERATION_WRITE_NAME,
7679        &journal_generation_quarantine_name(0),
7680        &initial_bytes,
7681    )?;
7682    let prepared = reopen_transaction_v1(filesystem, &migration_root, Some(&reopened))?;
7683    prepared.program.validate_prepared_environment(filesystem)?;
7684    Ok(prepared)
7685}
7686
7687fn validate_private_claim_set(
7688    filesystem: &MigrationFilesystem,
7689    transaction_root: &Path,
7690    transaction: &PreparedTransactionV1,
7691    observed_entries: &[(OsString, bool)],
7692) -> Result<()> {
7693    let current = transaction
7694        .generations
7695        .last()
7696        .ok_or_else(|| invalid_journal(Path::new("<transaction-v1>"), "journal is empty"))?;
7697    let apply_receipts = current
7698        .apply_receipt_records()
7699        .into_iter()
7700        .map(|(index, _)| index)
7701        .collect::<BTreeSet<_>>();
7702    let inverse_receipts = current
7703        .inverse_receipt_records()
7704        .into_iter()
7705        .map(|(index, _)| index)
7706        .collect::<BTreeSet<_>>();
7707    let mut allowed = BTreeMap::<OsString, bool>::new();
7708    let mut required = BTreeSet::<OsString>::new();
7709    let mut admit = |index: usize, kind: &str, is_directory: bool, must_exist: bool| {
7710        let name = OsString::from(private_claim_name(index, kind));
7711        allowed.insert(name.clone(), is_directory);
7712        if !is_directory {
7713            allowed.insert(
7714                OsString::from(format!(".{}.preparing", name.to_string_lossy())),
7715                false,
7716            );
7717            let ownership = OsString::from(format!(".{}.ownership.json", name.to_string_lossy()));
7718            allowed.insert(ownership.clone(), false);
7719            allowed.insert(
7720                OsString::from(format!(".{}.preparing", ownership.to_string_lossy())),
7721                false,
7722            );
7723        }
7724        if must_exist {
7725            required.insert(name);
7726        }
7727    };
7728
7729    for index in 0..transaction.program.operation_count() {
7730        let apply_complete = apply_receipts.contains(&index);
7731        let apply_in_flight = !apply_complete && current.in_flight_operation() == Some(index);
7732        let apply_private_receipt =
7733            load_private_leaf_receipt(transaction, index, PrivateReceiptDirectionV1::Apply)?
7734                .is_some();
7735        let abort_private_receipt = load_private_abort_work_receipt(transaction, index)?;
7736        match transaction.program.step(index)? {
7737            ProgramStepV1::CreateDirectory { .. } => {
7738                if apply_in_flight {
7739                    admit(index, "publish", true, false);
7740                }
7741            }
7742            ProgramStepV1::CreateFile { .. } => {
7743                if apply_complete || apply_in_flight {
7744                    admit(
7745                        index,
7746                        "publish",
7747                        false,
7748                        apply_complete || apply_private_receipt,
7749                    );
7750                }
7751            }
7752            ProgramStepV1::ReplaceFile { .. } => {
7753                if apply_complete || apply_in_flight {
7754                    let must_exist = apply_complete || apply_private_receipt;
7755                    admit(index, "publish", false, must_exist);
7756                    admit(index, "source", false, must_exist);
7757                }
7758            }
7759            ProgramStepV1::MoveFile { .. } => {
7760                if apply_complete || apply_in_flight {
7761                    admit(
7762                        index,
7763                        "source",
7764                        false,
7765                        apply_complete || apply_private_receipt,
7766                    );
7767                }
7768            }
7769        }
7770
7771        let rollback_complete = inverse_receipts.contains(&index);
7772        let rollback_in_flight = current.direction() == TransactionDirectionV1::Rollback
7773            && current.in_flight_operation() == Some(index)
7774            && apply_complete;
7775        let abort_in_flight = current.direction() == TransactionDirectionV1::Rollback
7776            && current.in_flight_operation() == Some(index)
7777            && !apply_complete;
7778        let rollback_private_receipt =
7779            load_private_leaf_receipt(transaction, index, PrivateReceiptDirectionV1::Rollback)?;
7780        let inverse_must_exist = rollback_complete || rollback_private_receipt.is_some();
7781        let unreceipted_abort_transition = abort_in_flight && abort_private_receipt.is_none();
7782        match transaction.program.step(index)? {
7783            ProgramStepV1::CreateDirectory { .. } => {
7784                if rollback_complete || rollback_in_flight || unreceipted_abort_transition {
7785                    let retained = rollback_private_receipt
7786                        .as_ref()
7787                        .is_some_and(|receipt| receipt.after_identity_sha256.is_some());
7788                    if !retained {
7789                        admit(index, "rollback", true, inverse_must_exist);
7790                    }
7791                }
7792            }
7793            ProgramStepV1::CreateFile { .. } => {
7794                if rollback_complete || rollback_in_flight || unreceipted_abort_transition {
7795                    admit(index, "rollback", false, inverse_must_exist);
7796                }
7797            }
7798            ProgramStepV1::ReplaceFile { .. } | ProgramStepV1::MoveFile { .. } => {
7799                if rollback_complete || rollback_in_flight || unreceipted_abort_transition {
7800                    admit(index, "rollback", false, inverse_must_exist);
7801                    admit(index, "restore", false, inverse_must_exist);
7802                }
7803            }
7804        }
7805        if let Some(receipt) = abort_private_receipt {
7806            for claim in receipt.claims {
7807                let kind = if claim.name() == private_claim_name(index, "source") {
7808                    "source"
7809                } else if claim.name() == private_claim_name(index, "publish") {
7810                    "publish"
7811                } else if claim.name() == private_claim_name(index, "rollback") {
7812                    "rollback"
7813                } else {
7814                    return Err(invalid_journal(
7815                        transaction
7816                            .private
7817                            .claims
7818                            .display_path(OsStr::new(claim.name())),
7819                        "abort receipt contains an impossible claim name",
7820                    ));
7821                };
7822                admit(index, kind, claim.is_directory(), true);
7823            }
7824        }
7825    }
7826
7827    if let Some(binding) = current.active_publication() {
7828        let claim = OsString::from(binding.claim_name());
7829        allowed.insert(claim.clone(), false);
7830        allowed.insert(
7831            OsString::from(format!(".{}.preparing", claim.to_string_lossy())),
7832            false,
7833        );
7834        let ownership = OsString::from(format!(".{}.ownership.json", claim.to_string_lossy()));
7835        allowed.insert(ownership.clone(), false);
7836        allowed.insert(
7837            OsString::from(format!(".{}.preparing", ownership.to_string_lossy())),
7838            false,
7839        );
7840    }
7841
7842    let claims_root = transaction_root.join("claims");
7843    let observed = observed_entries
7844        .iter()
7845        .map(|(name, is_directory)| (name.clone(), *is_directory))
7846        .collect::<BTreeMap<_, _>>();
7847    for (name, is_directory) in observed_entries {
7848        match allowed.get(name) {
7849            Some(expected_directory) if expected_directory == is_directory => {}
7850            Some(_) => {
7851                return Err(FolderbaseError::InvalidRecord {
7852                    path: filesystem.display(&claims_root.join(name)),
7853                    message: "private claim has the wrong artifact kind for this step".to_owned(),
7854                });
7855            }
7856            None => {
7857                return Err(FolderbaseError::InvalidRecord {
7858                    path: filesystem.display(&claims_root.join(name)),
7859                    message: "private claim is impossible in the durable transaction state"
7860                        .to_owned(),
7861                });
7862            }
7863        }
7864    }
7865    for name in required {
7866        if !observed.contains_key(&name) {
7867            return Err(FolderbaseError::InvalidRecord {
7868                path: filesystem.display(&claims_root.join(&name)),
7869                message: "durable transaction state is missing its exact private claim".to_owned(),
7870            });
7871        }
7872    }
7873    Ok(())
7874}
7875
7876fn private_publication_is_receipted(
7877    current: &TransactionJournalGenerationV1,
7878    binding: &PrivatePublicationBindingV1,
7879) -> bool {
7880    let operation_index = binding.operation_index();
7881    match binding.direction() {
7882        TransactionDirectionV1::Apply => {
7883            current
7884                .apply_receipt_records()
7885                .iter()
7886                .any(|(index, _)| *index == operation_index)
7887                || current.abort_receipt_sha256(operation_index).is_some()
7888        }
7889        TransactionDirectionV1::Rollback => current
7890            .inverse_receipt_records()
7891            .iter()
7892            .any(|(index, _)| *index == operation_index),
7893    }
7894}
7895
7896fn private_publication_has_durable_leaf_receipt(
7897    transaction: &PreparedTransactionV1,
7898    binding: &PrivatePublicationBindingV1,
7899) -> Result<bool> {
7900    let operation_index = binding.operation_index();
7901    match binding.direction() {
7902        TransactionDirectionV1::Apply => Ok(load_private_leaf_receipt(
7903            transaction,
7904            operation_index,
7905            PrivateReceiptDirectionV1::Apply,
7906        )?
7907        .is_some()),
7908        TransactionDirectionV1::Rollback => Ok(load_private_leaf_receipt(
7909            transaction,
7910            operation_index,
7911            PrivateReceiptDirectionV1::Rollback,
7912        )?
7913        .is_some()),
7914    }
7915}
7916
7917fn private_publication_has_durable_abort_receipt(
7918    transaction: &PreparedTransactionV1,
7919    binding: &PrivatePublicationBindingV1,
7920) -> Result<bool> {
7921    if binding.direction() != TransactionDirectionV1::Apply {
7922        return Ok(false);
7923    }
7924    Ok(load_private_abort_work_receipt(transaction, binding.operation_index())?.is_some())
7925}
7926
7927fn validate_active_private_publication(
7928    filesystem: &MigrationFilesystem,
7929    transaction: &PreparedTransactionV1,
7930    observed_entries: &[(OsString, bool)],
7931) -> Result<()> {
7932    let current = transaction
7933        .generations
7934        .last()
7935        .ok_or_else(|| invalid_journal(Path::new("<transaction-v1>"), "journal is empty"))?;
7936    let active = current.active_publication();
7937    let active_names = active.map(|binding| {
7938        let claim = binding.claim_name();
7939        BTreeSet::from([
7940            OsString::from(claim),
7941            OsString::from(format!(".{claim}.preparing")),
7942            OsString::from(format!(".{claim}.ownership.json")),
7943            OsString::from(format!("..{claim}.ownership.json.preparing")),
7944        ])
7945    });
7946    let publication_artifacts = observed_entries
7947        .iter()
7948        .filter(|(name, is_directory)| {
7949            !*is_directory
7950                && name.to_str().is_some_and(|name| {
7951                    name.ends_with(".ownership.json")
7952                        || name.ends_with(".ownership.json.preparing")
7953                        || (name.starts_with('.') && name.ends_with(".claim.preparing"))
7954                })
7955        })
7956        .map(|(name, _)| name.clone())
7957        .collect::<BTreeSet<_>>();
7958    if publication_artifacts.iter().any(|name| {
7959        active_names
7960            .as_ref()
7961            .is_none_or(|active| !active.contains(name))
7962    }) {
7963        let name = publication_artifacts
7964            .iter()
7965            .find(|name| {
7966                active_names
7967                    .as_ref()
7968                    .is_none_or(|active| !active.contains(*name))
7969            })
7970            .expect("the predicate established one unbound artifact");
7971        return Err(FolderbaseError::InvalidRecord {
7972            path: transaction.private.claims.display_path(name),
7973            message: "unbound private publication artifact is retained for review".to_owned(),
7974        });
7975    }
7976    let Some(binding) = active else {
7977        return Ok(());
7978    };
7979    let ownership_name = OsString::from(format!(".{}.ownership.json", binding.claim_name()));
7980    let ownership_staging_name = OsString::from(format!(
7981        "..{}.ownership.json.preparing",
7982        binding.claim_name()
7983    ));
7984    let ownership_exists = publication_artifacts.contains(&ownership_name)
7985        || publication_artifacts.contains(&ownership_staging_name);
7986    if ownership_exists {
7987        let durable_abort = private_publication_has_durable_abort_receipt(transaction, binding)?;
7988        if durable_abort {
7989            filesystem.validate_private_publication_ownership_binding(
7990                &transaction.private.claims,
7991                binding.claim_name(),
7992                binding.stage().exact(1),
7993                binding.ownership_record().exact(1),
7994            )?;
7995        } else if private_publication_is_receipted(current, binding)
7996            || private_publication_has_durable_leaf_receipt(transaction, binding)?
7997        {
7998            filesystem.validate_receipted_private_publish_claim(
7999                &transaction.private.claims,
8000                binding.claim_name(),
8001                binding.stage().exact(1),
8002                binding.ownership_record().exact(1),
8003            )?;
8004        } else {
8005            filesystem.reconcile_private_publish_claim(
8006                &transaction.private.claims,
8007                binding.claim_name(),
8008                binding.stage().exact(1),
8009                binding.ownership_record().exact(1),
8010            )?;
8011        }
8012        return Ok(());
8013    }
8014    if private_publication_is_receipted(current, binding) {
8015        return Ok(());
8016    }
8017    Err(FolderbaseError::InvalidRecord {
8018        path: transaction
8019            .private
8020            .claims
8021            .display_path(OsStr::new(binding.claim_name())),
8022        message: "active private publication is missing its bound ownership proof".to_owned(),
8023    })
8024}
8025
8026fn verify_create_directory_rollback_claim(
8027    transaction: &PreparedTransactionV1,
8028    operation_index: usize,
8029    published_identity: &str,
8030    device_sha256: &str,
8031    read_only: bool,
8032    executable: bool,
8033) -> Result<()> {
8034    transaction.private.claims.exact_empty_directory_fact(
8035        OsStr::new(&private_claim_name(operation_index, "rollback")),
8036        ExactDirectoryLeaf {
8037            physical_identity_sha256: published_identity,
8038            device_sha256,
8039            read_only,
8040            executable,
8041        },
8042    )?;
8043    Ok(())
8044}
8045
8046fn validate_create_directory_rollback_dispositions(
8047    filesystem: &MigrationFilesystem,
8048    transaction: &PreparedTransactionV1,
8049) -> Result<()> {
8050    let current = transaction
8051        .generations
8052        .last()
8053        .ok_or_else(|| invalid_journal(Path::new("<transaction-v1>"), "journal is empty"))?;
8054    let terminal = current.phase() == TransactionPhaseV1::RolledBack;
8055    let mut operation_indices = current
8056        .inverse_receipt_records()
8057        .into_iter()
8058        .map(|(operation_index, _)| operation_index)
8059        .collect::<BTreeSet<_>>();
8060    if current.direction() == TransactionDirectionV1::Rollback
8061        && let Some(operation_index) = current.in_flight_operation()
8062        && load_private_leaf_receipt(
8063            transaction,
8064            operation_index,
8065            PrivateReceiptDirectionV1::Rollback,
8066        )?
8067        .is_some()
8068    {
8069        operation_indices.insert(operation_index);
8070    }
8071    for operation_index in operation_indices {
8072        let ProgramStepV1::CreateDirectory { target, fidelity } =
8073            transaction.program.step(operation_index)?
8074        else {
8075            continue;
8076        };
8077        let receipt = load_private_leaf_receipt(
8078            transaction,
8079            operation_index,
8080            PrivateReceiptDirectionV1::Rollback,
8081        )?
8082        .ok_or_else(|| {
8083            invalid_journal(
8084                Path::new("<private-leaf-receipt-v1>"),
8085                "durable directory inverse has no private receipt",
8086            )
8087        })?;
8088        if terminal {
8089            // Terminal history releases the ordinary pathname, so the user may
8090            // recreate it. Removed transaction-owned directories remain exact
8091            // immutable private evidence, however.
8092            if receipt.after_identity_sha256.is_none() {
8093                let published_identity =
8094                    receipt.before_identity_sha256.as_deref().ok_or_else(|| {
8095                        invalid_journal(
8096                            Path::new("<private-leaf-receipt-v1>"),
8097                            "rollback receipt has no apply identity",
8098                        )
8099                    })?;
8100                verify_create_directory_rollback_claim(
8101                    transaction,
8102                    operation_index,
8103                    published_identity,
8104                    target.device_sha256,
8105                    fidelity.read_only,
8106                    fidelity.executable,
8107                )?;
8108            }
8109            continue;
8110        }
8111        verify_rollback_private_receipt(filesystem, transaction, operation_index, &receipt)?;
8112    }
8113    Ok(())
8114}
8115
8116fn reopen_transaction_v1(
8117    filesystem: &MigrationFilesystem,
8118    migration_root: &Path,
8119    expected_program: Option<&MutationProgramV1>,
8120) -> Result<PreparedTransactionV1> {
8121    let transaction_root = migration_root.join(TRANSACTION_DIRECTORY);
8122    let program_path = transaction_root.join("program.json");
8123    let transaction = filesystem.open_private_directory(&transaction_root)?;
8124    let journal = transaction.open_directory("journal")?;
8125    let stages = transaction.open_directory("stages")?;
8126    let claims = transaction.open_directory("claims")?;
8127    let snapshots = transaction.open_directory("snapshots")?;
8128    let receipts = transaction.open_directory("receipts")?;
8129    let expected_root_entries = BTreeSet::from([
8130        (OsString::from("claims"), true),
8131        (OsString::from("journal"), true),
8132        (OsString::from("program.json"), false),
8133        (OsString::from("receipts"), true),
8134        (OsString::from("snapshots"), true),
8135        (OsString::from("stages"), true),
8136    ]);
8137    let actual_root_entries = transaction
8138        .closed_entries(expected_root_entries.len())?
8139        .into_iter()
8140        .collect::<BTreeSet<_>>();
8141    if actual_root_entries != expected_root_entries {
8142        return Err(FolderbaseError::InvalidRecord {
8143            path: filesystem.display(&transaction_root),
8144            message: "transaction-v1 root contains missing or unknown entries".to_owned(),
8145        });
8146    }
8147    let (program_fact, _) =
8148        transaction.relaxed_regular_fact_observed(OsStr::new("program.json"))?;
8149    let program_bytes =
8150        transaction.read_relaxed_regular_bounded(OsStr::new("program.json"), MAX_PROGRAM_BYTES)?;
8151    let program = MutationProgramV1::decode(&filesystem.display(&program_path), &program_bytes)?;
8152    if expected_program.is_some_and(|expected| expected != &program) {
8153        return Err(FolderbaseError::MigrationApprovalMismatch);
8154    }
8155    let program_digest = program.digest(&filesystem.display(&program_path))?;
8156    let mut observed_claim_entries = Vec::new();
8157    for (directory, private_directory) in [
8158        ("stages", &stages),
8159        ("claims", &claims),
8160        ("snapshots", &snapshots),
8161        ("receipts", &receipts),
8162    ] {
8163        let relative = transaction_root.join(directory);
8164        let maximum_entries = match directory {
8165            "claims" => program
8166                .operation_count()
8167                .saturating_mul(12)
8168                .saturating_add(1),
8169            "receipts" => program
8170                .operation_count()
8171                .saturating_mul(6)
8172                .saturating_add(1),
8173            _ => program.operation_count().saturating_add(1),
8174        };
8175        let allowed = program.allowed_private_file_names(directory);
8176        let entries = private_directory.closed_entries(maximum_entries)?;
8177        if directory == "claims" {
8178            observed_claim_entries = entries.clone();
8179        }
8180        let names = entries
8181            .iter()
8182            .map(|(name, _)| name.clone())
8183            .collect::<BTreeSet<_>>();
8184        if matches!(directory, "stages" | "snapshots") && names != allowed {
8185            return Err(FolderbaseError::InvalidRecord {
8186                path: filesystem.display(&relative),
8187                message: "transaction-v1 contains missing or unknown immutable blobs".to_owned(),
8188            });
8189        }
8190        for (name, is_directory) in &entries {
8191            let receipt_staging_is_allowed = directory == "receipts"
8192                && recoverable_receipt_final_name(name)
8193                    .is_some_and(|final_name| allowed.contains(OsStr::new(&final_name)));
8194            if !allowed.contains(name) && !receipt_staging_is_allowed {
8195                return Err(FolderbaseError::InvalidRecord {
8196                    path: filesystem.display(&relative.join(name)),
8197                    message: "transaction-v1 contains an unknown private artifact".to_owned(),
8198                });
8199            }
8200            if *is_directory {
8201                let admitted_directory_claim = directory == "claims"
8202                    && (0..program.operation_count()).any(|index| {
8203                        (name == OsStr::new(&private_claim_name(index, "publish"))
8204                            || name == OsStr::new(&private_claim_name(index, "rollback")))
8205                            && matches!(
8206                                program.step(index),
8207                                Ok(ProgramStepV1::CreateDirectory { .. })
8208                            )
8209                    });
8210                if !admitted_directory_claim {
8211                    return Err(FolderbaseError::InvalidRecord {
8212                        path: filesystem.display(&relative.join(name)),
8213                        message: "transaction-v1 contains an unknown private directory artifact"
8214                            .to_owned(),
8215                    });
8216                }
8217                let _ = private_directory.relaxed_directory_fact(name)?;
8218            } else if directory == "claims" {
8219                let (fact, _) = private_directory.relaxed_regular_fact_observed(name)?;
8220                if fact.physical_identity_sha256 == program_fact.physical_identity_sha256 {
8221                    return Err(FolderbaseError::InvalidRecord {
8222                        path: filesystem.display(&relative.join(name)),
8223                        message: "private claim aliases the immutable program".to_owned(),
8224                    });
8225                }
8226            } else if directory == "receipts" {
8227                let fact = private_directory.relaxed_regular_fact_observed(name)?.0;
8228                if fact.physical_identity_sha256 == program_fact.physical_identity_sha256 {
8229                    return Err(FolderbaseError::InvalidRecord {
8230                        path: filesystem.display(&relative.join(name)),
8231                        message: "private receipt aliases the immutable program".to_owned(),
8232                    });
8233                }
8234                private_directory.verify_relaxed_regular(name)?;
8235            } else {
8236                private_directory.verify_regular(name)?;
8237            }
8238        }
8239    }
8240    if program_fact.link_count != 1 {
8241        return Err(FolderbaseError::InvalidRecord {
8242            path: filesystem.display(&program_path),
8243            message: "immutable program has a hard-link alias".to_owned(),
8244        });
8245    }
8246    transaction.verify_regular(OsStr::new("program.json"))?;
8247    program.validate_private_blobs(&stages, &snapshots)?;
8248    let journal_root = transaction_root.join("journal");
8249    repair_recoverable_journal_staging(
8250        filesystem,
8251        &journal,
8252        &journal_root,
8253        &program,
8254        &program_digest,
8255    )?;
8256    let journal_entries = journal.closed_entries(maximum_journal_directory_entries(
8257        program.maximum_journal_generations(),
8258    ))?;
8259    let classified = classify_journal_entries(
8260        filesystem,
8261        &journal,
8262        &journal_root,
8263        &journal_entries,
8264        program.maximum_journal_generations(),
8265    )?;
8266    if classified.staging_present || classified.writing_present {
8267        return Err(FolderbaseError::InvalidRecord {
8268            path: filesystem.display(&journal_root),
8269            message: "recoverable journal publication remains unresolved".to_owned(),
8270        });
8271    }
8272    let generation_names = classified.generation_names;
8273    let mut generations = Vec::with_capacity(generation_names.len());
8274    for (index, name) in generation_names.into_iter().enumerate() {
8275        let expected_name = format!("{index:020}.json");
8276        if name != OsStr::new(&expected_name) {
8277            return Err(FolderbaseError::InvalidRecord {
8278                path: filesystem.display(&journal_root.join(name)),
8279                message: "transaction journal contains an unknown or gapped generation".to_owned(),
8280            });
8281        }
8282        let path = journal_root.join(&expected_name);
8283        let bytes = journal
8284            .read_regular_bounded(OsStr::new(&expected_name), MAX_JOURNAL_GENERATION_BYTES)?;
8285        generations.push(TransactionJournalGenerationV1::decode(
8286            &filesystem.display(&path),
8287            &bytes,
8288        )?);
8289    }
8290    validate_chain(&program, &program_digest, &generations)?;
8291    let prepared = PreparedTransactionV1 {
8292        program,
8293        program_digest,
8294        generations,
8295        private: PrivateTransactionV1 {
8296            _transaction: transaction,
8297            journal,
8298            stages,
8299            claims,
8300            snapshots,
8301            receipts,
8302        },
8303    };
8304    repair_recoverable_private_receipt_staging(filesystem, &prepared)?;
8305    validate_active_private_publication(filesystem, &prepared, &observed_claim_entries)?;
8306    validate_private_leaf_receipt_set(&prepared)?;
8307    validate_private_claim_set(
8308        filesystem,
8309        &transaction_root,
8310        &prepared,
8311        &observed_claim_entries,
8312    )?;
8313    validate_create_directory_rollback_dispositions(filesystem, &prepared)?;
8314    validate_private_abort_work_receipts(filesystem, &prepared)?;
8315    Ok(prepared)
8316}
8317
8318fn repair_recoverable_journal_staging(
8319    filesystem: &MigrationFilesystem,
8320    journal: &VerifiedPrivateDirectory,
8321    journal_root: &Path,
8322    program: &MutationProgramV1,
8323    program_digest: &str,
8324) -> Result<()> {
8325    repair_recoverable_journal_staging_with_hooks(
8326        filesystem,
8327        journal,
8328        journal_root,
8329        program,
8330        program_digest,
8331        || {},
8332        || {},
8333        || {},
8334    )
8335}
8336
8337#[allow(clippy::too_many_arguments)]
8338fn repair_recoverable_journal_staging_with_hooks(
8339    filesystem: &MigrationFilesystem,
8340    journal: &VerifiedPrivateDirectory,
8341    journal_root: &Path,
8342    program: &MutationProgramV1,
8343    program_digest: &str,
8344    before_stage_content_read: impl FnOnce(),
8345    before_final_content_read: impl FnOnce(),
8346    before_pair_retirement: impl FnOnce(),
8347) -> Result<()> {
8348    let staging_name = OsStr::new(JOURNAL_GENERATION_STAGING_NAME);
8349    let maximum_generations = program.maximum_journal_generations();
8350    let maximum_entries = maximum_journal_directory_entries(maximum_generations);
8351    let mut entries = journal.closed_entries(maximum_entries)?;
8352    let mut classified = classify_journal_entries(
8353        filesystem,
8354        journal,
8355        journal_root,
8356        &entries,
8357        maximum_generations,
8358    )?;
8359    let writing_name = OsStr::new(JOURNAL_GENERATION_WRITE_NAME);
8360    if classified.writing_present {
8361        let quarantine_name = journal_generation_quarantine_name(classified.generation_names.len());
8362        journal.quarantine_uncommitted_regular_write_if_present(
8363            writing_name,
8364            OsStr::new(&quarantine_name),
8365            MAX_JOURNAL_GENERATION_BYTES,
8366        )?;
8367        entries = journal.closed_entries(maximum_entries)?;
8368        classified = classify_journal_entries(
8369            filesystem,
8370            journal,
8371            journal_root,
8372            &entries,
8373            maximum_generations,
8374        )?;
8375    }
8376    if !classified.staging_present {
8377        return Ok(());
8378    }
8379
8380    let staged_observation = journal.observe_relaxed_regular_bounded_with_hook(
8381        staging_name,
8382        MAX_JOURNAL_GENERATION_BYTES,
8383        before_stage_content_read,
8384    )?;
8385    let staged_fact = &staged_observation.fact;
8386    let staged_sha256 = &staged_observation.sha256;
8387    let staged_bytes = &staged_observation.bytes;
8388    let staging_path = journal_root.join(staging_name);
8389    let staged =
8390        TransactionJournalGenerationV1::decode(&filesystem.display(&staging_path), staged_bytes)?;
8391    let destination_name = staged.file_name();
8392    let destination_name_os = OsStr::new(&destination_name);
8393    let final_exists = classified
8394        .generation_names
8395        .iter()
8396        .any(|name| name == destination_name_os);
8397    let mut generation_names = classified
8398        .generation_names
8399        .into_iter()
8400        .filter(|name| !(final_exists && name == destination_name_os))
8401        .collect::<Vec<_>>();
8402    generation_names.sort();
8403    let mut generations = Vec::with_capacity(generation_names.len());
8404    for (index, name) in generation_names.into_iter().enumerate() {
8405        let expected_name = format!("{index:020}.json");
8406        if name != OsStr::new(&expected_name) {
8407            return Err(FolderbaseError::InvalidRecord {
8408                path: filesystem.display(&journal_root.join(name)),
8409                message: "transaction journal contains an unknown or gapped generation".to_owned(),
8410            });
8411        }
8412        let path = journal_root.join(&expected_name);
8413        let bytes = journal
8414            .read_regular_bounded(OsStr::new(&expected_name), MAX_JOURNAL_GENERATION_BYTES)?;
8415        generations.push(TransactionJournalGenerationV1::decode(
8416            &filesystem.display(&path),
8417            &bytes,
8418        )?);
8419    }
8420    let staged_is_valid = if generations.is_empty() {
8421        validate_chain(program, program_digest, std::slice::from_ref(&staged)).is_ok()
8422    } else {
8423        validate_chain(program, program_digest, &generations)?;
8424        validate_append(program, program_digest, &generations, &staged).is_ok()
8425    };
8426    if !staged_is_valid {
8427        return Err(FolderbaseError::InvalidRecord {
8428            path: filesystem.display(&staging_path),
8429            message: "recoverable journal staging is not the next admitted generation".to_owned(),
8430        });
8431    }
8432
8433    if final_exists {
8434        let final_observation = journal.observe_relaxed_regular_bounded_with_hook(
8435            destination_name_os,
8436            MAX_JOURNAL_GENERATION_BYTES,
8437            before_final_content_read,
8438        )?;
8439        if staged_fact.physical_identity_sha256 != final_observation.fact.physical_identity_sha256
8440            || staged_fact.device_sha256 != final_observation.fact.device_sha256
8441            || staged_fact.bytes != final_observation.fact.bytes
8442            || staged_fact.bytes != staged_bytes.len() as u64
8443            || staged_fact.link_count != 2
8444            || final_observation.fact.link_count != 2
8445            || staged_sha256 != &final_observation.sha256
8446        {
8447            return Err(FolderbaseError::InvalidRecord {
8448                path: filesystem.display(&journal_root.join(destination_name_os)),
8449                message: "journal final and recoverable staging are not one exact publication"
8450                    .to_owned(),
8451            });
8452        }
8453        before_pair_retirement();
8454        return Err(FolderbaseError::InvalidRecord {
8455            path: filesystem.display(&staging_path),
8456            message: "legacy final-plus-staging journal checkpoint requires manual review"
8457                .to_owned(),
8458        });
8459    }
8460    if staged_fact.link_count != 1 || staged_fact.bytes != staged_bytes.len() as u64 {
8461        return Err(FolderbaseError::InvalidRecord {
8462            path: filesystem.display(&staging_path),
8463            message: "journal generation staging has an unexpected alias topology".to_owned(),
8464        });
8465    }
8466    journal.install_recoverable_regular(
8467        staging_name,
8468        destination_name_os,
8469        staged_sha256,
8470        staged_bytes.len() as u64,
8471    )
8472}
8473
8474fn migration_command_id(command: MigrationCommand<'_>) -> &str {
8475    match command {
8476        MigrationCommand::Apply { migration_id, .. }
8477        | MigrationCommand::Recover { migration_id }
8478        | MigrationCommand::Rollback { migration_id } => migration_id,
8479    }
8480}
8481
8482fn classify_execution_format(
8483    filesystem: &MigrationFilesystem,
8484    migration_id: &str,
8485) -> Result<ExecutionFormat> {
8486    let migration_root = PathBuf::from(MIGRATIONS_DIR).join(migration_id);
8487    let transaction_present = filesystem
8488        .metadata(&migration_root.join(TRANSACTION_DIRECTORY))?
8489        .is_some();
8490    let legacy_present = filesystem
8491        .metadata(&migration_root.join("result.json"))?
8492        .is_some();
8493    match (transaction_present, legacy_present) {
8494        (false, false) => Ok(ExecutionFormat::None),
8495        (true, false) => {
8496            let transaction_root = migration_root.join(TRANSACTION_DIRECTORY);
8497            if !is_provable_prepared_transaction_v1_prefix(filesystem, &transaction_root)? {
8498                return Ok(ExecutionFormat::TransactionV1);
8499            }
8500            match reopen_transaction_v1(filesystem, &migration_root, None) {
8501                Ok(_) => Ok(ExecutionFormat::TransactionV1),
8502                Err(_) => Ok(ExecutionFormat::PrePreparedTransactionV1),
8503            }
8504        }
8505        (false, true) => Ok(ExecutionFormat::LegacyResult),
8506        (true, true) => Err(FolderbaseError::InvalidRecord {
8507            path: filesystem.display(&migration_root),
8508            message:
8509                "migration contains both transaction-v1 and legacy result.json execution state"
8510                    .to_owned(),
8511        }),
8512    }
8513}
8514
8515fn map_durable_transaction_v1_conflict(
8516    filesystem: &MigrationFilesystem,
8517    migration_root: &Path,
8518    migration_id: &str,
8519    result: Result<MigrationOutcome>,
8520    conflict_is_causal: bool,
8521) -> Result<MigrationOutcome> {
8522    let Err(error) = result else {
8523        return result;
8524    };
8525    if !conflict_is_causal {
8526        return Err(error);
8527    }
8528    if let Ok(transaction) = reopen_transaction_v1(filesystem, migration_root, None)
8529        && let Some(current) = transaction.generations.last()
8530        && current.phase() == TransactionPhaseV1::Conflicted
8531    {
8532        let direction = match current.direction() {
8533            TransactionDirectionV1::Apply => MigrationConflictDirection::Apply,
8534            TransactionDirectionV1::Rollback => MigrationConflictDirection::Rollback,
8535        };
8536        let conflicts = current
8537            .conflict_records()
8538            .into_iter()
8539            .map(|conflict| MigrationConflict {
8540                operation_index: conflict.operation_index,
8541                affected_paths: conflict.affected_paths,
8542                expected: conflict.expected,
8543                observed: conflict.observed,
8544                phase: "conflicted".to_owned(),
8545                direction,
8546                preserved_artifact: conflict.preserved_artifact,
8547            })
8548            .collect();
8549        return Ok(MigrationOutcome::Conflicted {
8550            migration_id: migration_id.to_owned(),
8551            conflicts,
8552        });
8553    }
8554    Err(error)
8555}
8556
8557fn run_transaction_v1_in(
8558    filesystem: &MigrationFilesystem,
8559    command: MigrationCommand<'_>,
8560    checkpoint: impl FnMut(TransactionV1Checkpoint),
8561) -> Result<MigrationOutcome> {
8562    let migration_id = migration_command_id(command);
8563    let migration_root = PathBuf::from(MIGRATIONS_DIR).join(migration_id);
8564    let mut transaction = reopen_transaction_v1(filesystem, &migration_root, None)?;
8565    if let MigrationCommand::Apply {
8566        approval_digest, ..
8567    } = command
8568    {
8569        let root_identity_sha256 = filesystem
8570            .directory_fact(Path::new(""))?
8571            .physical_identity_sha256;
8572        if !transaction.program.matches_approval(
8573            migration_id,
8574            approval_digest,
8575            &root_identity_sha256,
8576        ) {
8577            return Err(FolderbaseError::MigrationApprovalMismatch);
8578        }
8579    }
8580    let conflict_recorded = Cell::new(false);
8581    let mut checkpoint = checkpoint;
8582    let mut tracked_checkpoint = |transaction_checkpoint| {
8583        if matches!(
8584            transaction_checkpoint,
8585            TransactionV1Checkpoint::ConflictRecorded(_)
8586        ) {
8587            conflict_recorded.set(true);
8588        }
8589        checkpoint(transaction_checkpoint);
8590    };
8591    let result = match command {
8592        MigrationCommand::Apply { .. } | MigrationCommand::Recover { .. }
8593            if transaction.generations.last().is_some_and(|generation| {
8594                generation.direction() == TransactionDirectionV1::Apply
8595            }) =>
8596        {
8597            execute_transaction_v1_apply_with_hook(
8598                filesystem,
8599                &mut transaction,
8600                &mut tracked_checkpoint,
8601            )
8602            .map(MigrationOutcome::Applied)
8603        }
8604        MigrationCommand::Recover { .. } | MigrationCommand::Rollback { .. } => {
8605            execute_transaction_v1_rollback_with_hook(
8606                filesystem,
8607                &mut transaction,
8608                &mut tracked_checkpoint,
8609            )
8610            .map(MigrationOutcome::RolledBack)
8611        }
8612        MigrationCommand::Apply { .. } => Err(FolderbaseError::InvalidMigrationState {
8613            expected: MigrationState::Applying.as_str(),
8614            actual: "rolling_back".to_owned(),
8615        }),
8616    };
8617    map_durable_transaction_v1_conflict(
8618        filesystem,
8619        &migration_root,
8620        migration_id,
8621        result,
8622        conflict_recorded.get(),
8623    )
8624}
8625
8626fn run_current_transaction_v1_apply_with_hooks(
8627    display_root: &Path,
8628    migration_id: &str,
8629    approval_digest: &str,
8630    after_transaction_coordinator: impl FnOnce(),
8631    mut checkpoint: impl FnMut(ApplyCheckpoint),
8632    transaction_checkpoint: impl FnMut(TransactionV1Checkpoint),
8633) -> Result<MigrationOutcome> {
8634    let (root, root_identity) = canonical_root_with_identity(display_root)?;
8635    let coordinator = acquire_existing_folderbase_transaction_lock_with_hook(
8636        &root,
8637        root_identity.identity(),
8638        || checkpoint(ApplyCheckpoint::ExistingFolderbaseDetected),
8639    )?;
8640    require_no_pending_work_except(&coordinator.state, migration_id)?;
8641    let filesystem = coordinator.migration_filesystem(&root)?;
8642    let execution_format = classify_execution_format(&filesystem, migration_id)?;
8643    after_transaction_coordinator();
8644    match execution_format {
8645        ExecutionFormat::TransactionV1 => run_transaction_v1_in(
8646            &filesystem,
8647            MigrationCommand::Apply {
8648                migration_id,
8649                approval_digest,
8650            },
8651            transaction_checkpoint,
8652        ),
8653        ExecutionFormat::None | ExecutionFormat::PrePreparedTransactionV1 => {
8654            apply_transaction_v1_migration_in_with_hooks(
8655                &filesystem,
8656                migration_id,
8657                approval_digest,
8658                root_identity.identity().stable_sha256(),
8659                execution_format,
8660                checkpoint,
8661                transaction_checkpoint,
8662            )
8663        }
8664        ExecutionFormat::LegacyResult => Err(FolderbaseError::InvalidMigrationState {
8665            expected: MigrationState::Approved.as_str(),
8666            actual: "legacy_result".to_owned(),
8667        }),
8668    }
8669}
8670
8671#[cfg(test)]
8672fn run_existing_transaction_v1_apply_with_root_hook(
8673    display_root: &Path,
8674    migration_id: &str,
8675    approval_digest: &str,
8676    after_initial_root_open: impl FnOnce(),
8677    transaction_checkpoint: impl FnMut(TransactionV1Checkpoint),
8678) -> Result<Option<MigrationOutcome>> {
8679    let (root, root_identity) =
8680        canonical_root_with_identity_with_hook(display_root, after_initial_root_open)?;
8681    let coordinator =
8682        acquire_existing_folderbase_transaction_lock(&root, root_identity.identity())?;
8683    require_no_pending_work_except(&coordinator.state, migration_id)?;
8684    let filesystem = coordinator.migration_filesystem(&root)?;
8685    match classify_execution_format(&filesystem, migration_id)? {
8686        ExecutionFormat::TransactionV1 => run_transaction_v1_in(
8687            &filesystem,
8688            MigrationCommand::Apply {
8689                migration_id,
8690                approval_digest,
8691            },
8692            transaction_checkpoint,
8693        )
8694        .map(Some),
8695        ExecutionFormat::None | ExecutionFormat::PrePreparedTransactionV1 => Ok(None),
8696        ExecutionFormat::LegacyResult => Err(FolderbaseError::InvalidMigrationState {
8697            expected: MigrationState::Approved.as_str(),
8698            actual: "legacy_result".to_owned(),
8699        }),
8700    }
8701}
8702
8703fn run_current_migration_command_with_hooks(
8704    display_root: &Path,
8705    command: MigrationCommand<'_>,
8706    after_transaction_coordinator: impl FnOnce(),
8707    transaction_checkpoint: impl FnMut(TransactionV1Checkpoint),
8708) -> Result<MigrationOutcome> {
8709    run_current_migration_command_with_root_hook(
8710        display_root,
8711        command,
8712        || {},
8713        after_transaction_coordinator,
8714        transaction_checkpoint,
8715    )
8716}
8717
8718fn run_current_migration_command_with_root_hook(
8719    display_root: &Path,
8720    command: MigrationCommand<'_>,
8721    after_initial_root_open: impl FnOnce(),
8722    after_transaction_coordinator: impl FnOnce(),
8723    transaction_checkpoint: impl FnMut(TransactionV1Checkpoint),
8724) -> Result<MigrationOutcome> {
8725    let (root, root_identity) =
8726        canonical_root_with_identity_with_hook(display_root, after_initial_root_open)?;
8727    let coordinator =
8728        acquire_existing_folderbase_transaction_lock(&root, root_identity.identity())?;
8729    let migration_id = migration_command_id(command);
8730    require_no_pending_work_except(&coordinator.state, migration_id)?;
8731    let filesystem = coordinator.migration_filesystem(&root)?;
8732    let format = classify_execution_format(&filesystem, migration_id)?;
8733    after_transaction_coordinator();
8734    match format {
8735        ExecutionFormat::TransactionV1 => {
8736            run_transaction_v1_in(&filesystem, command, transaction_checkpoint)
8737        }
8738        ExecutionFormat::None | ExecutionFormat::PrePreparedTransactionV1 => {
8739            Err(FolderbaseError::InvalidMigrationState {
8740                expected: MigrationState::Approved.as_str(),
8741                actual: "missing_execution_state".to_owned(),
8742            })
8743        }
8744        ExecutionFormat::LegacyResult => match command {
8745            MigrationCommand::Recover { .. } => {
8746                let result = legacy_recover_migration_in(&root, &filesystem, migration_id)?;
8747                legacy_recovery_outcome(result)
8748            }
8749            MigrationCommand::Rollback { .. } => {
8750                legacy_rollback_migration_by_id_in(&filesystem, migration_id)
8751                    .map(MigrationOutcome::RolledBack)
8752            }
8753            MigrationCommand::Apply { .. } => Err(FolderbaseError::InvalidMigrationState {
8754                expected: MigrationState::Approved.as_str(),
8755                actual: "missing_transaction_v1".to_owned(),
8756            }),
8757        },
8758    }
8759}
8760
8761fn legacy_recovery_outcome(result: MigrationResult) -> Result<MigrationOutcome> {
8762    match result.state {
8763        MigrationState::Verified => Ok(MigrationOutcome::Applied(result)),
8764        MigrationState::RolledBack => Ok(MigrationOutcome::RolledBack(RollbackResult {
8765            migration_id: result.migration_id,
8766            removed_paths: Vec::new(),
8767            state: result.state,
8768        })),
8769        MigrationState::Conflicted => Ok(MigrationOutcome::Conflicted {
8770            migration_id: result.migration_id,
8771            conflicts: vec![MigrationConflict {
8772                operation_index: None,
8773                affected_paths: result.created_paths,
8774                expected: "released migration recovery to be resolved".to_owned(),
8775                observed: "released result.json remains conflicted".to_owned(),
8776                phase: "legacy_conflicted".to_owned(),
8777                direction: MigrationConflictDirection::LegacyUnknown,
8778                preserved_artifact: Some(result.journal_path),
8779            }],
8780        }),
8781        state => Err(invalid_journal(
8782            &result.journal_path,
8783            format!(
8784                "released migration recovery ended in unsupported execution state {}",
8785                state.as_str()
8786            ),
8787        )),
8788    }
8789}
8790
8791#[cfg(test)]
8792fn run_transaction_v1_with_hook(
8793    display_root: &Path,
8794    command: MigrationCommand<'_>,
8795    checkpoint: impl FnMut(TransactionV1Checkpoint),
8796) -> Result<MigrationOutcome> {
8797    run_current_migration_command_with_hooks(display_root, command, || {}, checkpoint)
8798}
8799
8800struct ExistingFolderbaseTransactionCoordinator {
8801    state: FolderbaseState,
8802    _lock: StoreTransactionLock,
8803}
8804
8805impl ExistingFolderbaseTransactionCoordinator {
8806    fn migration_filesystem(&self, display_root: &Path) -> Result<MigrationFilesystem> {
8807        MigrationFilesystem::from_state(&self.state, display_root)
8808    }
8809}
8810
8811fn acquire_existing_folderbase_transaction_lock(
8812    root: &Path,
8813    expected_root_identity: PhysicalIdentity,
8814) -> Result<ExistingFolderbaseTransactionCoordinator> {
8815    acquire_existing_folderbase_transaction_lock_with_hook(root, expected_root_identity, || {})
8816}
8817
8818fn acquire_existing_folderbase_transaction_lock_with_hook(
8819    root: &Path,
8820    expected_root_identity: PhysicalIdentity,
8821    after_marker_probe: impl FnOnce(),
8822) -> Result<ExistingFolderbaseTransactionCoordinator> {
8823    let state = FolderbaseState::open_existing(root)?;
8824    state.verify_root_identity(&expected_root_identity)?;
8825    match state.classify_attached_root_boundary()? {
8826        NestedFolderbaseBoundaryKind::None | NestedFolderbaseBoundaryKind::ExactBoundary => {}
8827        NestedFolderbaseBoundaryKind::UnsafeAliasShape => {
8828            return Err(FolderbaseError::UnsafePath(root.to_path_buf()));
8829        }
8830    }
8831    after_marker_probe();
8832    state.verify_root_identity(&expected_root_identity)?;
8833    let lock = LocalVersionStore::acquire_transaction_lock_for_state(root, &state)?;
8834    state.verify_still_attached()?;
8835    Ok(ExistingFolderbaseTransactionCoordinator { state, _lock: lock })
8836}
8837
8838fn require_no_pending_work_except(state: &FolderbaseState, migration_id: &str) -> Result<()> {
8839    match scan_pending_work(state, Some(migration_id)) {
8840        Ok(None) => Ok(()),
8841        Ok(Some(work)) => Err(FolderbaseError::RecoveryRequired {
8842            work: work.description(),
8843        }),
8844        Err(_) => Err(FolderbaseError::RecoveryRequired {
8845            work: "unreadable or unsafe transaction state".to_owned(),
8846        }),
8847    }
8848}
8849
8850pub(crate) fn durable_migration_execution_is_terminal(
8851    state: &FolderbaseState,
8852    migration_id: &str,
8853) -> Result<Option<bool>> {
8854    let filesystem = MigrationFilesystem::from_state(state, state.display_root())?;
8855    match classify_execution_format(&filesystem, migration_id)? {
8856        ExecutionFormat::None => Ok(None),
8857        ExecutionFormat::PrePreparedTransactionV1 => Ok(Some(false)),
8858        ExecutionFormat::TransactionV1 => {
8859            let migration_root = PathBuf::from(MIGRATIONS_DIR).join(migration_id);
8860            let transaction = reopen_transaction_v1(&filesystem, &migration_root, None)?;
8861            let current = transaction.generations.last().ok_or_else(|| {
8862                invalid_journal(
8863                    Path::new("<transaction-v1>"),
8864                    "transaction journal has no generation",
8865                )
8866            })?;
8867            Ok(Some(matches!(
8868                current.phase(),
8869                TransactionPhaseV1::Applied | TransactionPhaseV1::RolledBack
8870            )))
8871        }
8872        ExecutionFormat::LegacyResult => {
8873            let (_, journal) = load_journal_from(&filesystem, migration_id)?;
8874            Ok(Some(matches!(
8875                journal.state,
8876                MigrationState::Verified | MigrationState::RolledBack
8877            )))
8878        }
8879    }
8880}
8881
8882fn structural_visible_result_path(operation: &MigrationOperation) -> &Path {
8883    operation
8884        .structural_destination_path()
8885        .or_else(|| operation.structural_source_path())
8886        .expect("structural operation has one visible result path")
8887}
8888
8889#[cfg(test)]
8890fn structural_result_bytes(source: &Path, operation: &MigrationOperation) -> Result<Vec<u8>> {
8891    let current = read_bounded_regular(source, MAX_MIGRATION_PLAN_BYTES)?;
8892    structural_result_bytes_from(source, &current, operation)
8893}
8894
8895fn structural_result_bytes_from(
8896    source: &Path,
8897    current: &[u8],
8898    operation: &MigrationOperation,
8899) -> Result<Vec<u8>> {
8900    match operation {
8901        MigrationOperation::UpdateAdapter { managed_block, .. } => {
8902            let current =
8903                std::str::from_utf8(current).map_err(|_| FolderbaseError::InvalidRecord {
8904                    path: source.to_path_buf(),
8905                    message: "agent adapter must be UTF-8 text".to_owned(),
8906                })?;
8907            Ok(merge_managed_block(current, managed_block, source)?.into_bytes())
8908        }
8909        MigrationOperation::UpdateIgnorePolicy { content, .. } => Ok(content.as_bytes().to_vec()),
8910        MigrationOperation::UpdatePolicy { policy, value, .. } => {
8911            let mut document = parse_structural_json(source, current)?;
8912            let policies = document
8913                .get_mut("policies")
8914                .and_then(serde_json::Value::as_object_mut)
8915                .ok_or_else(|| FolderbaseError::InvalidRecord {
8916                    path: source.to_path_buf(),
8917                    message: "manifest is missing its policies object".to_owned(),
8918                })?;
8919            policies.insert(policy.clone(), value.clone());
8920            pretty_json_bytes(source, &document)
8921        }
8922        MigrationOperation::ChangeKind { new_kind, .. } => {
8923            let mut document = parse_structural_json(source, current)?;
8924            let folderbase = document
8925                .get_mut("folderbase")
8926                .and_then(serde_json::Value::as_object_mut)
8927                .ok_or_else(|| FolderbaseError::InvalidRecord {
8928                    path: source.to_path_buf(),
8929                    message: "manifest is missing its folderbase object".to_owned(),
8930                })?;
8931            folderbase.insert(
8932                "kind".to_owned(),
8933                serde_json::Value::String(structural_folderbase_kind_name(*new_kind).to_owned()),
8934            );
8935            pretty_json_bytes(source, &document)
8936        }
8937        MigrationOperation::MarkCanonical { .. } => {
8938            let mut document = parse_structural_json(source, current)?;
8939            set_object_lifecycle(source, &mut document, "canonical", None)?;
8940            pretty_json_bytes(source, &document)
8941        }
8942        MigrationOperation::MarkSuperseded { superseded_by, .. } => {
8943            let mut document = parse_structural_json(source, current)?;
8944            set_object_lifecycle(source, &mut document, "superseded", Some(superseded_by))?;
8945            pretty_json_bytes(source, &document)
8946        }
8947        MigrationOperation::ArchiveObject { .. } => {
8948            let mut document = parse_structural_json(source, current)?;
8949            set_object_lifecycle(source, &mut document, "archived", None)?;
8950            validate_archive_lifecycle(source, &document)?;
8951            pretty_json_bytes(source, &document)
8952        }
8953        MigrationOperation::AddRelationship {
8954            relationship_type,
8955            target_object_id,
8956            ..
8957        } => {
8958            let mut document = parse_structural_json(source, current)?;
8959            let object =
8960                document
8961                    .as_object_mut()
8962                    .ok_or_else(|| FolderbaseError::InvalidRecord {
8963                        path: source.to_path_buf(),
8964                        message: "object record must be a JSON object".to_owned(),
8965                    })?;
8966            let relationships = object
8967                .entry("relationships")
8968                .or_insert_with(|| serde_json::Value::Array(Vec::new()))
8969                .as_array_mut()
8970                .ok_or_else(|| FolderbaseError::InvalidRecord {
8971                    path: source.to_path_buf(),
8972                    message: "object relationships must be an array".to_owned(),
8973                })?;
8974            let relationship = serde_json::json!({
8975                "type": relationship_type,
8976                "target": target_object_id,
8977            });
8978            if !relationships.contains(&relationship) {
8979                relationships.push(relationship);
8980            }
8981            pretty_json_bytes(source, &document)
8982        }
8983        MigrationOperation::MoveObject { .. }
8984        | MigrationOperation::CreateFolder { .. }
8985        | MigrationOperation::CopyFile { .. } => Err(invalid_journal(
8986            source,
8987            "operation does not produce replacement bytes",
8988        )),
8989    }
8990}
8991
8992fn replace_file_atomically_in(
8993    filesystem: &MigrationFilesystem,
8994    path: &Path,
8995    expected_sha256: &str,
8996    content: &[u8],
8997) -> Result<()> {
8998    if filesystem.sha256_regular(path)? != expected_sha256 {
8999        return Err(FolderbaseError::MigrationSourceChanged(
9000            filesystem.display(path),
9001        ));
9002    }
9003    filesystem.replace(path, content)?;
9004    if filesystem.sha256_regular(path)? != sha256_bytes(content) {
9005        return Err(FolderbaseError::MigrationVerificationFailed(
9006            filesystem.display(path),
9007        ));
9008    }
9009    Ok(())
9010}
9011
9012#[cfg(test)]
9013#[allow(dead_code)]
9014fn replace_file_atomically(path: &Path, expected_sha256: &str, content: &[u8]) -> Result<()> {
9015    if sha256_path(path)? != expected_sha256 {
9016        return Err(FolderbaseError::MigrationSourceChanged(path.to_path_buf()));
9017    }
9018    let metadata =
9019        fs::symlink_metadata(path).map_err(|source| FolderbaseError::io(path, source))?;
9020    if !metadata.is_file() || metadata.file_type().is_symlink() {
9021        return Err(FolderbaseError::MigrationSourceChanged(path.to_path_buf()));
9022    }
9023    let parent = path
9024        .parent()
9025        .ok_or_else(|| FolderbaseError::UnsafePath(path.to_path_buf()))?;
9026    let temporary = parent.join(format!(".folderbase-structural-{}.tmp", Uuid::now_v7()));
9027    let result = (|| -> Result<()> {
9028        let mut file = fs::OpenOptions::new()
9029            .write(true)
9030            .create_new(true)
9031            .open(&temporary)
9032            .map_err(|source| FolderbaseError::io(&temporary, source))?;
9033        file.set_permissions(metadata.permissions())
9034            .map_err(|source| FolderbaseError::io(&temporary, source))?;
9035        file.write_all(content)
9036            .and_then(|()| file.sync_all())
9037            .map_err(|source| FolderbaseError::io(&temporary, source))?;
9038        if sha256_path(path)? != expected_sha256 {
9039            return Err(FolderbaseError::MigrationSourceChanged(path.to_path_buf()));
9040        }
9041        fs::rename(&temporary, path).map_err(|source| FolderbaseError::io(path, source))?;
9042        sync_directory(parent)
9043    })();
9044    if result.is_err() {
9045        let _ = fs::remove_file(&temporary);
9046    }
9047    result
9048}
9049
9050#[cfg(test)]
9051#[allow(dead_code)]
9052fn move_file_no_replace(source: &Path, destination: &Path, expected_sha256: &str) -> Result<()> {
9053    if destination.exists() {
9054        return Err(FolderbaseError::WouldOverwrite(destination.to_path_buf()));
9055    }
9056    if sha256_path(source)? != expected_sha256 {
9057        return Err(FolderbaseError::MigrationSourceChanged(
9058            source.to_path_buf(),
9059        ));
9060    }
9061    fs::hard_link(source, destination).map_err(|error| {
9062        if error.kind() == std::io::ErrorKind::AlreadyExists {
9063            FolderbaseError::WouldOverwrite(destination.to_path_buf())
9064        } else {
9065            FolderbaseError::io(destination, error)
9066        }
9067    })?;
9068    let linked = (|| -> Result<()> {
9069        if sha256_path(destination)? != expected_sha256 || sha256_path(source)? != expected_sha256 {
9070            return Err(FolderbaseError::MigrationSourceChanged(
9071                source.to_path_buf(),
9072            ));
9073        }
9074        sync_parent(destination)?;
9075        fs::remove_file(source).map_err(|error| FolderbaseError::io(source, error))?;
9076        sync_parent(source)?;
9077        if sha256_path(destination)? != expected_sha256 {
9078            return Err(FolderbaseError::MigrationVerificationFailed(
9079                destination.to_path_buf(),
9080            ));
9081        }
9082        Ok(())
9083    })();
9084    if linked.is_err() && source.exists() {
9085        let _ = fs::remove_file(destination);
9086        let _ = sync_parent(destination);
9087    }
9088    linked
9089}
9090
9091fn move_file_no_replace_in(
9092    filesystem: &MigrationFilesystem,
9093    source: &Path,
9094    destination: &Path,
9095    expected_sha256: &str,
9096) -> Result<()> {
9097    if filesystem.metadata(destination)?.is_some() {
9098        return Err(FolderbaseError::WouldOverwrite(
9099            filesystem.display(destination),
9100        ));
9101    }
9102    if filesystem.sha256_regular(source)? != expected_sha256 {
9103        return Err(FolderbaseError::MigrationSourceChanged(
9104            filesystem.display(source),
9105        ));
9106    }
9107    filesystem.hard_link(source, destination)?;
9108    let linked = (|| -> Result<()> {
9109        if filesystem.sha256_regular(destination)? != expected_sha256
9110            || filesystem.sha256_regular(source)? != expected_sha256
9111        {
9112            return Err(FolderbaseError::MigrationSourceChanged(
9113                filesystem.display(source),
9114            ));
9115        }
9116        filesystem.remove_file(source)?;
9117        if filesystem.sha256_regular(destination)? != expected_sha256 {
9118            return Err(FolderbaseError::MigrationVerificationFailed(
9119                filesystem.display(destination),
9120            ));
9121        }
9122        Ok(())
9123    })();
9124    if linked.is_err()
9125        && filesystem
9126            .metadata(source)
9127            .is_ok_and(|value| value.is_some())
9128    {
9129        let _ = filesystem.remove_file_if_present(destination);
9130    }
9131    linked
9132}
9133
9134fn is_sha256(value: &str) -> bool {
9135    value.len() == 64
9136        && value
9137            .bytes()
9138            .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
9139}
9140
9141fn compile_program_materialization(
9142    filesystem: &MigrationFilesystem,
9143    plan: &MigrationPlan,
9144) -> Result<ProgramMaterializationV1> {
9145    const TEMPLATE_ID: &str = "folderbase.project";
9146    const TEMPLATE_VERSION: &str = "0.2.2";
9147    const TEMPLATE_REFERENCE: &str = "folderbase.project@0.2.2";
9148
9149    if is_structural_plan(plan) {
9150        return Ok(ProgramMaterializationV1 {
9151            directories: Vec::new(),
9152            files: Vec::new(),
9153            template_packages_sha256: sha256_bytes(b"folderbase-template-packages-v1\0"),
9154        });
9155    }
9156    if !plan
9157        .template_references
9158        .iter()
9159        .any(|reference| reference == TEMPLATE_REFERENCE)
9160    {
9161        return Err(invalid_journal(
9162            filesystem.display_root(),
9163            "migration plan does not bind the required folderbase template",
9164        ));
9165    }
9166    let (workspace_path, materializations) = approved_materialization_specs(
9167        &plan.answers,
9168        &plan.targets,
9169        &plan.operations,
9170        filesystem.display_root(),
9171    )?;
9172    let package = load_builtin_template(TEMPLATE_ID, TEMPLATE_VERSION)?;
9173    let package_digest = template_package_sha256(&package)?;
9174    let template_packages_sha256 = sha256_bytes(
9175        format!("folderbase-template-packages-v1\0{TEMPLATE_REFERENCE}\0{package_digest}")
9176            .as_bytes(),
9177    );
9178    let planned_directories = plan
9179        .operations
9180        .iter()
9181        .filter_map(|operation| match operation {
9182            MigrationOperation::CreateFolder { path } => Some(path.clone()),
9183            _ => None,
9184        })
9185        .collect::<BTreeSet<_>>();
9186    let planned_files = plan
9187        .operations
9188        .iter()
9189        .filter_map(|operation| match operation {
9190            MigrationOperation::CopyFile {
9191                destination_path, ..
9192            } => Some(destination_path.clone()),
9193            _ => None,
9194        })
9195        .collect::<BTreeSet<_>>();
9196    let mut directories = BTreeSet::new();
9197    let mut files = Vec::new();
9198    let mut materialized = Vec::new();
9199
9200    for materialization in materializations {
9201        let path = materialization.path;
9202        let mut answers = BTreeMap::from([
9203            (
9204                "purpose".to_owned(),
9205                TemplateAnswerValue::Text(format!(
9206                    "Preserve and organize approved content for {}.",
9207                    materialization.name
9208                )),
9209            ),
9210            (
9211                "current_state".to_owned(),
9212                TemplateAnswerValue::Text(format!(
9213                    "Materialized from approved migration {} while preserving the source folder.",
9214                    plan.id
9215                )),
9216            ),
9217            (
9218                "next_action".to_owned(),
9219                TemplateAnswerValue::Text(
9220                    "Review the migrated files and refine this folderbase's executive summary."
9221                        .to_owned(),
9222                ),
9223            ),
9224        ]);
9225        answers.insert(
9226            "folderbase_name".to_owned(),
9227            TemplateAnswerValue::Text(materialization.name.clone()),
9228        );
9229        let rendered = render_template_for_capability_destination(
9230            &package,
9231            &filesystem.display(&path),
9232            &answers,
9233        )?;
9234        let mut preserved = BTreeSet::new();
9235        for artifact in &package.artifacts {
9236            let relative = path.join(&artifact.target);
9237            if planned_directories.contains(&relative) || planned_files.contains(&relative) {
9238                let compatible = match artifact.kind {
9239                    TemplateArtifactKind::Directory => planned_directories.contains(&relative),
9240                    TemplateArtifactKind::Text => planned_files.contains(&relative),
9241                };
9242                if !compatible {
9243                    return Err(FolderbaseError::InvalidRecord {
9244                        path: filesystem.display(&relative),
9245                        message:
9246                            "approved destination kind is incompatible with its template artifact"
9247                                .to_owned(),
9248                    });
9249                }
9250                preserved.insert(relative);
9251                continue;
9252            }
9253            let Some(metadata) = filesystem.metadata(&relative)? else {
9254                continue;
9255            };
9256            let compatible = match artifact.kind {
9257                TemplateArtifactKind::Directory => {
9258                    metadata.is_dir() && !metadata.file_type().is_symlink()
9259                }
9260                TemplateArtifactKind::Text => {
9261                    metadata.is_file() && !metadata.file_type().is_symlink()
9262                }
9263            };
9264            if !compatible {
9265                return Err(FolderbaseError::InvalidRecord {
9266                    path: filesystem.display(&relative),
9267                    message: "template target exists with an incompatible filesystem kind"
9268                        .to_owned(),
9269                });
9270            }
9271            preserved.insert(relative);
9272        }
9273        for adapter_path in ["AGENTS.md", "CLAUDE.md"] {
9274            let relative = path.join(adapter_path);
9275            if planned_files.contains(&relative) {
9276                preserved.insert(relative);
9277                continue;
9278            }
9279            let Some(metadata) = filesystem.metadata(&relative)? else {
9280                continue;
9281            };
9282            if !metadata.is_file() || metadata.file_type().is_symlink() {
9283                return Err(FolderbaseError::InvalidRecord {
9284                    path: filesystem.display(&relative),
9285                    message: "agent adapter exists with an incompatible filesystem kind".to_owned(),
9286                });
9287            }
9288            preserved.insert(relative);
9289        }
9290
9291        let identity_seed = serde_json::to_vec(&(plan.id.as_str(), &path))
9292            .map_err(|source| FolderbaseError::json(filesystem.display(&path), source))?;
9293        let identity_digest = Sha256::digest(&identity_seed);
9294        let mut identity_bytes = [0_u8; 16];
9295        identity_bytes.copy_from_slice(&identity_digest[..16]);
9296        identity_bytes[6] = (identity_bytes[6] & 0x0f) | 0x70;
9297        identity_bytes[8] = (identity_bytes[8] & 0x3f) | 0x80;
9298        let folderbase_id = format!("folderbase_{}", Uuid::from_bytes(identity_bytes));
9299        let migration_uuid = Uuid::parse_str(
9300            plan.id
9301                .strip_prefix("migration_")
9302                .ok_or_else(|| invalid_journal(&path, "migration ID has no UUID payload"))?,
9303        )
9304        .map_err(|_| invalid_journal(&path, "migration ID has an invalid UUID payload"))?;
9305        let timestamp = migration_uuid
9306            .get_timestamp()
9307            .ok_or_else(|| invalid_journal(&path, "migration ID has no timestamp"))?;
9308        let (seconds, nanos) = timestamp.to_unix();
9309        let created_at = DateTime::<Utc>::from_timestamp(seconds as i64, nanos)
9310            .ok_or_else(|| invalid_journal(&path, "migration timestamp is out of range"))?
9311            .to_rfc3339();
9312        let manifest_path = path.join(".folderbase/manifest.json");
9313        if planned_files.contains(&manifest_path) {
9314            return Err(invalid_journal(
9315                &manifest_path,
9316                "a materialized manifest must be compiler-generated",
9317            ));
9318        }
9319        let manifest = serde_json::json!({
9320            "$schema": "https://folderbase.ai/protocol/0.5/folderbase.schema.json",
9321            "protocol_version": "0.5.0",
9322            "folderbase": {
9323                "id": folderbase_id.clone(),
9324                "name": materialization.name.clone(),
9325                "kind": "project",
9326                "status": "active",
9327                "created_at": created_at.clone(),
9328                "template_provenance": {
9329                    "id": TEMPLATE_ID,
9330                    "version": TEMPLATE_VERSION,
9331                    "applied_at": created_at,
9332                    "package_digest": {
9333                        "algorithm": "sha256",
9334                        "digest": package_digest.clone()
9335                    }
9336                }
9337            },
9338            "adapters": [
9339                { "agent": "codex", "path": "AGENTS.md" },
9340                { "agent": "claude", "path": "CLAUDE.md" }
9341            ],
9342            "policies": {
9343                "availability": "keep_local",
9344                "structural_changes": "approve",
9345                "archive": "approve",
9346                "cloud_sync": "disabled",
9347                "capture_ignore": {
9348                    "format": "folderbase-capture-ignore-v1",
9349                    "rules": DEFAULT_V05_CAPTURE_IGNORE_RULES
9350                }
9351            }
9352        });
9353        let mut manifest_bytes = serde_json::to_vec_pretty(&manifest)
9354            .map_err(|source| FolderbaseError::json(&manifest_path, source))?;
9355        manifest_bytes.push(b'\n');
9356
9357        for addition in rendered.additions {
9358            let relative = path.join(&addition.path);
9359            if preserved.contains(&relative) {
9360                continue;
9361            }
9362            match addition.kind {
9363                TemplateArtifactKind::Directory => {
9364                    directories.insert(relative);
9365                }
9366                TemplateArtifactKind::Text => files.push(ProgramGeneratedFileV1 {
9367                    role: if addition.path == Path::new("FOLDERBASE.md") {
9368                        ProgramGeneratedRoleV1::OrdinaryNarrative
9369                    } else {
9370                        ProgramGeneratedRoleV1::GeneratedGuidance
9371                    },
9372                    path: relative,
9373                    bytes: addition.content.unwrap_or_default().into_bytes(),
9374                }),
9375            }
9376        }
9377        directories.insert(path.join(".folderbase"));
9378        files.push(ProgramGeneratedFileV1 {
9379            path: manifest_path,
9380            bytes: manifest_bytes,
9381            role: ProgramGeneratedRoleV1::FolderbaseManifest,
9382        });
9383        let adapter = migration_agent_adapter().into_bytes();
9384        for adapter_path in ["AGENTS.md", "CLAUDE.md"] {
9385            let relative = path.join(adapter_path);
9386            if !preserved.contains(&relative) && !files.iter().any(|file| file.path == relative) {
9387                files.push(ProgramGeneratedFileV1 {
9388                    path: relative,
9389                    bytes: adapter.clone(),
9390                    role: ProgramGeneratedRoleV1::AgentAdapter,
9391                });
9392            }
9393        }
9394        materialized.push((path, folderbase_id, materialization.name));
9395    }
9396
9397    if materialized.len() > 1 {
9398        let workspace_id = format!("workspace_{}", Uuid::now_v7());
9399        let name = materialized_workspace_name(&workspace_path);
9400        let links = materialized
9401            .iter()
9402            .map(|(path, folderbase_id, label)| {
9403                let relative = path.strip_prefix(&workspace_path).map_err(|_| {
9404                    invalid_journal(
9405                        filesystem.display_root(),
9406                        "materialized folderbase is outside its approved workspace",
9407                    )
9408                })?;
9409                ensure_safe_relative(relative)?;
9410                Ok((relative.to_path_buf(), folderbase_id.clone(), label.clone()))
9411            })
9412            .collect::<Result<Vec<_>>>()?;
9413        let descriptor = serde_json::json!({
9414            "$schema": "https://folderbase.ai/protocol/0.1/workspace.schema.json",
9415            "protocol_version": "0.1.0",
9416            "id": workspace_id,
9417            "name": name,
9418            "folderbases": links.iter().map(|(path, folderbase_id, label)| {
9419                serde_json::json!({
9420                    "folderbase_id": folderbase_id,
9421                    "label": label,
9422                    "path": path,
9423                })
9424            }).collect::<Vec<_>>(),
9425        });
9426        let descriptor_path = workspace_path.join(".folderbase-workspace.json");
9427        let mut descriptor_bytes = serde_json::to_vec_pretty(&descriptor)
9428            .map_err(|source| FolderbaseError::json(&descriptor_path, source))?;
9429        descriptor_bytes.push(b'\n');
9430        files.push(ProgramGeneratedFileV1 {
9431            path: descriptor_path,
9432            bytes: descriptor_bytes,
9433            role: ProgramGeneratedRoleV1::WorkspaceDescriptor,
9434        });
9435
9436        let mut guidance = format!(
9437            "# {name}\n\nThis workspace is navigation only. It does not grant access to any folderbase.\n\n## Folderbases\n"
9438        );
9439        for (path, _, label) in &links {
9440            guidance.push_str(&format!(
9441                "- [{label}]({}/.folderbase/manifest.json)\n",
9442                path.display()
9443            ));
9444        }
9445        files.push(ProgramGeneratedFileV1 {
9446            path: workspace_path.join("WORKSPACE.md"),
9447            bytes: guidance.into_bytes(),
9448            role: ProgramGeneratedRoleV1::GeneratedGuidance,
9449        });
9450    }
9451
9452    for operation in &plan.operations {
9453        let destination = match operation {
9454            MigrationOperation::CreateFolder { path } => path,
9455            MigrationOperation::CopyFile {
9456                destination_path, ..
9457            } => destination_path,
9458            _ => continue,
9459        };
9460        compile_missing_directory_parents(
9461            filesystem,
9462            destination,
9463            &planned_directories,
9464            &planned_files,
9465            &mut directories,
9466        )?;
9467    }
9468    for file in &files {
9469        compile_missing_directory_parents(
9470            filesystem,
9471            &file.path,
9472            &planned_directories,
9473            &planned_files,
9474            &mut directories,
9475        )?;
9476    }
9477    for planned in &planned_directories {
9478        directories.remove(planned);
9479    }
9480    validate_program_materialization_namespace(
9481        filesystem,
9482        &planned_directories,
9483        &planned_files,
9484        &directories,
9485        &files,
9486    )?;
9487    let mut directories = directories.into_iter().collect::<Vec<_>>();
9488    directories.sort_by(|left, right| {
9489        left.components()
9490            .count()
9491            .cmp(&right.components().count())
9492            .then_with(|| left.cmp(right))
9493    });
9494    files.sort_by(|left, right| left.path.cmp(&right.path));
9495    Ok(ProgramMaterializationV1 {
9496        directories,
9497        files,
9498        template_packages_sha256,
9499    })
9500}
9501
9502fn compile_missing_directory_parents(
9503    filesystem: &MigrationFilesystem,
9504    leaf: &Path,
9505    planned_directories: &BTreeSet<PathBuf>,
9506    planned_files: &BTreeSet<PathBuf>,
9507    generated_directories: &mut BTreeSet<PathBuf>,
9508) -> Result<()> {
9509    ensure_safe_relative(leaf)?;
9510    let mut parent = leaf.parent();
9511    while let Some(path) = parent {
9512        if path.as_os_str().is_empty() {
9513            break;
9514        }
9515        ensure_safe_relative(path)?;
9516        let parent_key = portable_path_key(path);
9517        if planned_files
9518            .iter()
9519            .any(|planned| portable_path_key(planned) == parent_key)
9520        {
9521            return Err(invalid_journal(
9522                filesystem.display(path),
9523                "a required parent directory collides with an approved file destination",
9524            ));
9525        }
9526        if !planned_directories.contains(path) {
9527            match filesystem.metadata(path)? {
9528                Some(metadata) if !metadata.is_dir() || metadata.file_type().is_symlink() => {
9529                    return Err(FolderbaseError::InvalidRecord {
9530                        path: filesystem.display(path),
9531                        message: "a required materialization parent is not a regular directory"
9532                            .to_owned(),
9533                    });
9534                }
9535                Some(_) => {}
9536                None => {
9537                    generated_directories.insert(path.to_path_buf());
9538                }
9539            }
9540        }
9541        parent = path.parent();
9542    }
9543    Ok(())
9544}
9545
9546fn validate_program_materialization_namespace(
9547    filesystem: &MigrationFilesystem,
9548    planned_directories: &BTreeSet<PathBuf>,
9549    planned_files: &BTreeSet<PathBuf>,
9550    generated_directories: &BTreeSet<PathBuf>,
9551    generated_files: &[ProgramGeneratedFileV1],
9552) -> Result<()> {
9553    let mut namespace = BTreeMap::<PathBuf, (&'static str, PathBuf)>::new();
9554    let mut insert = |path: &Path,
9555                      kind: &'static str,
9556                      allow_exact_directory_duplicate: bool|
9557     -> Result<()> {
9558        ensure_safe_relative(path)?;
9559        let key = portable_path_key(path);
9560        if let Some((existing_kind, existing_path)) = namespace.get(&key) {
9561            if allow_exact_directory_duplicate
9562                && kind == "directory"
9563                && *existing_kind == "directory"
9564                && existing_path == path
9565            {
9566                return Ok(());
9567            }
9568            return Err(invalid_journal(
9569                filesystem.display(path),
9570                format!(
9571                    "materialization namespace collision between {existing_kind} {} and {kind} {}",
9572                    existing_path.display(),
9573                    path.display()
9574                ),
9575            ));
9576        }
9577        namespace.insert(key, (kind, path.to_path_buf()));
9578        Ok(())
9579    };
9580
9581    for path in planned_directories {
9582        insert(path, "directory", true)?;
9583    }
9584    for path in generated_directories {
9585        insert(path, "directory", true)?;
9586    }
9587    for path in planned_files {
9588        insert(path, "file", false)?;
9589    }
9590    for file in generated_files {
9591        insert(&file.path, "file", false)?;
9592    }
9593
9594    for (_, (_, path)) in namespace.iter() {
9595        let mut parent = path.parent();
9596        while let Some(candidate) = parent {
9597            if candidate.as_os_str().is_empty() {
9598                break;
9599            }
9600            if namespace
9601                .get(&portable_path_key(candidate))
9602                .is_some_and(|(kind, _)| *kind == "file")
9603            {
9604                return Err(invalid_journal(
9605                    filesystem.display(path),
9606                    format!(
9607                        "materialization path {} is nested beneath a file destination",
9608                        path.display()
9609                    ),
9610                ));
9611            }
9612            parent = candidate.parent();
9613        }
9614    }
9615    let mut admitted_parent_entries = BTreeMap::<PathBuf, Vec<OsString>>::new();
9616    for (_, (_, path)) in namespace.iter() {
9617        let parent = path.parent().unwrap_or_else(|| Path::new(""));
9618        if !parent.as_os_str().is_empty() {
9619            let Some(parent_metadata) = filesystem.metadata(parent)? else {
9620                continue;
9621            };
9622            if !parent_metadata.is_dir() || parent_metadata.file_type().is_symlink() {
9623                return Err(FolderbaseError::InvalidRecord {
9624                    path: filesystem.display(parent),
9625                    message: "materialization parent is not an admitted directory".to_owned(),
9626                });
9627            }
9628        }
9629        if !admitted_parent_entries.contains_key(parent) {
9630            admitted_parent_entries.insert(
9631                parent.to_path_buf(),
9632                filesystem.directory_entry_names(parent, 65_536)?,
9633            );
9634        }
9635        let target_name = path
9636            .file_name()
9637            .ok_or_else(|| invalid_journal(path, "materialization target has no file name"))?;
9638        let target_key = portable_path_key(Path::new(target_name));
9639        if admitted_parent_entries[parent]
9640            .iter()
9641            .any(|name| portable_path_key(Path::new(name)) == target_key)
9642        {
9643            return Err(invalid_journal(
9644                filesystem.display(path),
9645                "materialization target collides with an existing admitted sibling",
9646            ));
9647        }
9648    }
9649    Ok(())
9650}
9651
9652fn migration_agent_adapter() -> String {
9653    "<!-- folderbase:begin -->\n\
9654     # Folderbase\n\n\
9655     Confirm this root through `.folderbase/manifest.json`, then work with its ordinary \
9656     files using Folderbase Core context and boundary rules. Treat summaries and questions \
9657     as optional hints, never as mutation or sharing authority.\n\
9658     <!-- folderbase:end -->\n"
9659        .to_owned()
9660}
9661
9662fn approved_materialization_specs(
9663    answers: &[MigrationAnswer],
9664    targets: &[MigrationTarget],
9665    operations: &[MigrationOperation],
9666    record_path: &Path,
9667) -> Result<(PathBuf, Vec<FolderbaseMaterializationSpec>)> {
9668    let canonical_scope = answers
9669        .iter()
9670        .find(|answer| answer.question_id == "question_canonical_scope")
9671        .map(|answer| answer.answer.as_str())
9672        .ok_or_else(|| {
9673            invalid_journal(
9674                record_path,
9675                "migration plan is missing its canonical-scope answer",
9676            )
9677        })?;
9678    let destination_root = operations
9679        .iter()
9680        .find_map(|operation| match operation {
9681            MigrationOperation::CreateFolder { path } => Some(path.clone()),
9682            MigrationOperation::CopyFile { .. } => None,
9683            _ => None,
9684        })
9685        .ok_or_else(|| {
9686            invalid_journal(
9687                record_path,
9688                "migration plan does not create a destination root",
9689            )
9690        })?;
9691    let selected_target_ids = answers
9692        .iter()
9693        .filter_map(|answer| {
9694            targets
9695                .iter()
9696                .find(|target| {
9697                    target.kind == MigrationTargetKind::Folderbase && target.id == answer.answer
9698                })
9699                .map(|target| target.id.as_str())
9700        })
9701        .collect::<BTreeSet<_>>();
9702    let mut materializations = Vec::new();
9703    for target in targets.iter().filter(|target| {
9704        target.kind == MigrationTargetKind::Folderbase
9705            && selected_target_ids.contains(target.id.as_str())
9706    }) {
9707        let path = match canonical_scope {
9708            "one_folderbase" if target.id == "target_primary_folderbase" => {
9709                destination_root.clone()
9710            }
9711            "proposed_boundaries" => {
9712                let folder_name = if target.id == "target_primary_folderbase" {
9713                    "Primary.folderbase".to_owned()
9714                } else {
9715                    format!("{}.folderbase", safe_boundary_name(&target.suggested_name))
9716                };
9717                destination_root.join(folder_name)
9718            }
9719            _ => {
9720                return Err(invalid_journal(
9721                    record_path,
9722                    "selected folderbase target is inconsistent with canonical scope",
9723                ));
9724            }
9725        };
9726        if !operations.iter().any(|operation| {
9727            matches!(
9728                operation,
9729                MigrationOperation::CreateFolder { path: planned } if planned == &path
9730            )
9731        }) {
9732            return Err(invalid_journal(
9733                record_path,
9734                format!(
9735                    "folderbase target {} has no approved destination operation",
9736                    target.id
9737                ),
9738            ));
9739        }
9740        materializations.push(FolderbaseMaterializationSpec {
9741            target_id: target.id.clone(),
9742            name: target.suggested_name.clone(),
9743            path,
9744        });
9745    }
9746    Ok((destination_root, materializations))
9747}
9748
9749/// Reopen a durable migration result by ID.
9750impl MigrationResult {
9751    pub fn reopen(root: impl AsRef<Path>, migration_id: &str) -> Result<Self> {
9752        reopen_migration_result(root.as_ref(), migration_id)
9753    }
9754
9755    /// Recover an interrupted released migration.
9756    ///
9757    /// Legacy `result.json` executions retain their exact released Recover
9758    /// semantics. Transaction-v1 executions retain this adapter's conservative
9759    /// rollback behavior. Terminal results are reopened without rewriting.
9760    pub fn recover(root: impl AsRef<Path>, migration_id: &str) -> Result<Self> {
9761        let root = root.as_ref();
9762        let (current, format) = match reopen_migration_result_with_format(root, migration_id) {
9763            Ok(current) => current,
9764            Err(FolderbaseError::InvalidMigrationState { actual, .. })
9765                if actual == "missing_execution_state" =>
9766            {
9767                return Err(FolderbaseError::InvalidMigrationState {
9768                    expected: MigrationState::Approved.as_str(),
9769                    actual,
9770                });
9771            }
9772            Err(error) => return Err(error),
9773        };
9774        if matches!(
9775            current.state,
9776            MigrationState::Verified | MigrationState::Conflicted | MigrationState::RolledBack
9777        ) {
9778            return Ok(current);
9779        }
9780        let command = match format {
9781            ExecutionFormat::LegacyResult => MigrationCommand::Recover { migration_id },
9782            ExecutionFormat::TransactionV1 => MigrationCommand::Rollback { migration_id },
9783            ExecutionFormat::None | ExecutionFormat::PrePreparedTransactionV1 => {
9784                return Err(FolderbaseError::InvalidMigrationState {
9785                    expected: MigrationState::Approved.as_str(),
9786                    actual: "missing_execution_state".to_owned(),
9787                });
9788            }
9789        };
9790        match MigrationExecution::run(RootClaim::Current { display_root: root }, command)? {
9791            MigrationOutcome::RolledBack(_) => Self::reopen(root, migration_id),
9792            MigrationOutcome::Applied(result) if format == ExecutionFormat::LegacyResult => {
9793                Ok(result)
9794            }
9795            MigrationOutcome::Conflicted { .. } if format == ExecutionFormat::LegacyResult => {
9796                Self::reopen(root, migration_id)
9797            }
9798            MigrationOutcome::Applied(_) | MigrationOutcome::Conflicted { .. } => {
9799                Err(FolderbaseError::InvalidMigrationState {
9800                    expected: MigrationState::RolledBack.as_str(),
9801                    actual: MigrationState::Conflicted.as_str().to_owned(),
9802                })
9803            }
9804            MigrationOutcome::RecoveryRequired { work, .. } => {
9805                Err(FolderbaseError::RecoveryRequired { work })
9806            }
9807        }
9808    }
9809
9810    /// Roll back a verified migration using only its durable ID.
9811    pub fn rollback_by_id(root: impl AsRef<Path>, migration_id: &str) -> Result<RollbackResult> {
9812        let root = root.as_ref();
9813        match MigrationExecution::run(
9814            RootClaim::Current { display_root: root },
9815            MigrationCommand::Rollback { migration_id },
9816        )? {
9817            MigrationOutcome::RolledBack(result) => Ok(result),
9818            MigrationOutcome::Applied(_) | MigrationOutcome::Conflicted { .. } => {
9819                Err(FolderbaseError::InvalidMigrationState {
9820                    expected: MigrationState::RolledBack.as_str(),
9821                    actual: MigrationState::Conflicted.as_str().to_owned(),
9822                })
9823            }
9824            MigrationOutcome::RecoveryRequired { work, .. } => {
9825                Err(FolderbaseError::RecoveryRequired { work })
9826            }
9827        }
9828    }
9829}
9830
9831fn reopen_migration_result(root: &Path, migration_id: &str) -> Result<MigrationResult> {
9832    reopen_migration_result_with_root_hook(root, migration_id, || {})
9833}
9834
9835fn reopen_migration_result_with_format(
9836    root: &Path,
9837    migration_id: &str,
9838) -> Result<(MigrationResult, ExecutionFormat)> {
9839    reopen_migration_result_with_format_and_root_hook(root, migration_id, || {})
9840}
9841
9842fn reopen_migration_result_with_root_hook(
9843    root: &Path,
9844    migration_id: &str,
9845    after_initial_root_open: impl FnOnce(),
9846) -> Result<MigrationResult> {
9847    reopen_migration_result_with_format_and_root_hook(root, migration_id, after_initial_root_open)
9848        .map(|(result, _)| result)
9849}
9850
9851fn reopen_migration_result_with_format_and_root_hook(
9852    root: &Path,
9853    migration_id: &str,
9854    after_initial_root_open: impl FnOnce(),
9855) -> Result<(MigrationResult, ExecutionFormat)> {
9856    let (root, root_identity) =
9857        canonical_root_with_identity_with_hook(root, after_initial_root_open)?;
9858    let coordinator =
9859        acquire_existing_folderbase_transaction_lock(&root, root_identity.identity())?;
9860    let filesystem = coordinator.migration_filesystem(&root)?;
9861    match classify_execution_format(&filesystem, migration_id)? {
9862        ExecutionFormat::TransactionV1 => {
9863            let migration_root = PathBuf::from(MIGRATIONS_DIR).join(migration_id);
9864            let transaction = reopen_transaction_v1(&filesystem, &migration_root, None)?;
9865            let current = transaction.generations.last().ok_or_else(|| {
9866                invalid_journal(
9867                    Path::new("<transaction-v1>"),
9868                    "transaction journal has no generation",
9869                )
9870            })?;
9871            let state = match current.phase() {
9872                TransactionPhaseV1::Prepared | TransactionPhaseV1::Applying => {
9873                    MigrationState::Applying
9874                }
9875                TransactionPhaseV1::Applied => MigrationState::Verified,
9876                TransactionPhaseV1::RollbackRequested | TransactionPhaseV1::RollingBack => {
9877                    MigrationState::RollingBack
9878                }
9879                TransactionPhaseV1::RolledBack => MigrationState::RolledBack,
9880                TransactionPhaseV1::Conflicted => MigrationState::Conflicted,
9881            };
9882            Ok((
9883                transaction_v1_result(&filesystem, &transaction, state),
9884                ExecutionFormat::TransactionV1,
9885            ))
9886        }
9887        ExecutionFormat::LegacyResult => {
9888            let (journal_path, journal) = load_journal_from(&filesystem, migration_id)?;
9889            Ok((
9890                result_from_journal(root, journal_path, &journal),
9891                ExecutionFormat::LegacyResult,
9892            ))
9893        }
9894        ExecutionFormat::None => Err(FolderbaseError::InvalidMigrationState {
9895            expected: MigrationState::Applying.as_str(),
9896            actual: "missing_execution_state".to_owned(),
9897        }),
9898        ExecutionFormat::PrePreparedTransactionV1 => Err(FolderbaseError::InvalidMigrationState {
9899            expected: MigrationState::Applying.as_str(),
9900            actual: "pre_prepared_execution_state".to_owned(),
9901        }),
9902    }
9903}
9904
9905fn legacy_recover_migration_in(
9906    root: &Path,
9907    migration_filesystem: &MigrationFilesystem,
9908    migration_id: &str,
9909) -> Result<MigrationResult> {
9910    let (journal_path, mut journal) = load_journal_from(migration_filesystem, migration_id)?;
9911    if matches!(
9912        journal.state,
9913        MigrationState::Applying | MigrationState::RollingBack
9914    ) {
9915        if is_structural_journal(&journal) {
9916            rollback_structural_journal_in(migration_filesystem, &journal_path, &mut journal)?;
9917        } else {
9918            rollback_journal_in(migration_filesystem, &journal_path, &mut journal)?;
9919        }
9920        persist_plan_transition_in(
9921            migration_filesystem,
9922            migration_id,
9923            &[
9924                MigrationState::Approved,
9925                MigrationState::Applying,
9926                MigrationState::Verified,
9927                MigrationState::RollingBack,
9928            ],
9929            MigrationState::RolledBack,
9930        )?;
9931    } else if journal.state == MigrationState::Verified {
9932        persist_plan_transition_in(
9933            migration_filesystem,
9934            migration_id,
9935            &[MigrationState::Applying, MigrationState::Verified],
9936            MigrationState::Verified,
9937        )?;
9938        cleanup_staging_in(migration_filesystem, migration_id);
9939    } else if journal.state == MigrationState::RolledBack {
9940        let plan = load_plan_from(migration_filesystem, migration_id)?;
9941        if plan.state != MigrationState::Conflicted {
9942            persist_plan_transition_in(
9943                migration_filesystem,
9944                migration_id,
9945                &[
9946                    MigrationState::Applying,
9947                    MigrationState::Verified,
9948                    MigrationState::RolledBack,
9949                ],
9950                MigrationState::RolledBack,
9951            )?;
9952        }
9953        cleanup_staging_in(migration_filesystem, migration_id);
9954    }
9955    Ok(result_from_journal(
9956        root.to_path_buf(),
9957        journal_path,
9958        &journal,
9959    ))
9960}
9961
9962fn legacy_rollback_migration_by_id_in(
9963    migration_filesystem: &MigrationFilesystem,
9964    migration_id: &str,
9965) -> Result<RollbackResult> {
9966    let (journal_path, mut journal) = load_journal_from(migration_filesystem, migration_id)?;
9967    if journal.state == MigrationState::RolledBack {
9968        return Ok(RollbackResult {
9969            migration_id: journal.id,
9970            removed_paths: Vec::new(),
9971            state: MigrationState::RolledBack,
9972        });
9973    }
9974    require_state(journal.state, MigrationState::Verified)?;
9975    let result = if is_structural_journal(&journal) {
9976        rollback_structural_journal_in(migration_filesystem, &journal_path, &mut journal)?
9977    } else {
9978        rollback_journal_in(migration_filesystem, &journal_path, &mut journal)?
9979    };
9980    persist_plan_transition_in(
9981        migration_filesystem,
9982        migration_id,
9983        &[MigrationState::Verified],
9984        MigrationState::RolledBack,
9985    )?;
9986    Ok(result)
9987}
9988
9989/// Roll back only additive, unchanged paths recorded by a verified migration.
9990pub fn rollback_migration(result: &MigrationResult) -> Result<RollbackResult> {
9991    require_state(result.state, MigrationState::Verified)?;
9992    MigrationResult::rollback_by_id(&result.root, &result.migration_id)
9993}
9994
9995#[cfg(test)]
9996#[allow(dead_code)]
9997fn create_directory_if_missing(path: &Path) -> Result<()> {
9998    match fs::symlink_metadata(path) {
9999        Ok(metadata) if metadata.is_dir() && !metadata.file_type().is_symlink() => Ok(()),
10000        Ok(_) => Err(FolderbaseError::WouldOverwrite(path.to_path_buf())),
10001        Err(source) if source.kind() == std::io::ErrorKind::NotFound => {
10002            fs::create_dir(path).map_err(|source| FolderbaseError::io(path, source))?;
10003            sync_parent(path)
10004        }
10005        Err(source) => Err(FolderbaseError::io(path, source)),
10006    }
10007}
10008
10009fn create_private_directory_if_missing(path: &Path) -> Result<()> {
10010    match fs::symlink_metadata(path) {
10011        Ok(metadata) if metadata.is_dir() && !metadata.file_type().is_symlink() => Ok(()),
10012        Ok(_) => Err(FolderbaseError::WouldOverwrite(path.to_path_buf())),
10013        Err(source) if source.kind() == std::io::ErrorKind::NotFound => {
10014            create_private_directory_new(path)
10015        }
10016        Err(source) => Err(FolderbaseError::io(path, source)),
10017    }
10018}
10019
10020fn create_private_directory_new(path: &Path) -> Result<()> {
10021    let builder = fs::DirBuilder::new();
10022    #[cfg(unix)]
10023    let builder = {
10024        use std::os::unix::fs::DirBuilderExt;
10025
10026        let mut builder = builder;
10027        builder.mode(0o700);
10028        builder
10029    };
10030    builder.create(path).map_err(|source| {
10031        if source.kind() == std::io::ErrorKind::AlreadyExists {
10032            FolderbaseError::WouldOverwrite(path.to_path_buf())
10033        } else {
10034            FolderbaseError::io(path, source)
10035        }
10036    })?;
10037    let metadata =
10038        fs::symlink_metadata(path).map_err(|source| FolderbaseError::io(path, source))?;
10039    validate_private_directory_mode(path, &metadata)?;
10040    sync_parent(path)
10041}
10042
10043fn validate_private_directory_mode(path: &Path, metadata: &fs::Metadata) -> Result<()> {
10044    #[cfg(unix)]
10045    {
10046        use std::os::unix::fs::PermissionsExt;
10047
10048        if metadata.permissions().mode() & 0o777 != 0o700 {
10049            return Err(FolderbaseError::InvalidRecord {
10050                path: path.to_path_buf(),
10051                message: "private migration directory is not owner-only".to_owned(),
10052            });
10053        }
10054    }
10055    #[cfg(not(unix))]
10056    let _ = (path, metadata);
10057    Ok(())
10058}
10059
10060#[cfg(test)]
10061#[allow(dead_code)]
10062fn load_journal(root: &Path, migration_id: &str) -> Result<(PathBuf, MigrationJournal)> {
10063    validate_migration_id(root, migration_id)?;
10064    let journal_relative = PathBuf::from(MIGRATIONS_DIR)
10065        .join(migration_id)
10066        .join("result.json");
10067    let journal_path = safe_join(root, &journal_relative)?;
10068    let bytes =
10069        fs::read(&journal_path).map_err(|source| FolderbaseError::io(&journal_path, source))?;
10070    let journal: MigrationJournal = serde_json::from_slice(&bytes)
10071        .map_err(|source| FolderbaseError::json(&journal_path, source))?;
10072    validate_journal(root, migration_id, &journal_path, &journal)?;
10073    if is_structural_journal(&journal) {
10074        let plan = load_plan(root, migration_id)?;
10075        validate_structural_recovery_invariants(root, &journal_path, &plan, &journal)?;
10076    }
10077    Ok((journal_path, journal))
10078}
10079
10080fn load_journal_from(
10081    filesystem: &MigrationFilesystem,
10082    migration_id: &str,
10083) -> Result<(PathBuf, MigrationJournal)> {
10084    validate_migration_id(filesystem.display_root(), migration_id)?;
10085    let journal_relative = PathBuf::from(MIGRATIONS_DIR)
10086        .join(migration_id)
10087        .join("result.json");
10088    let journal_path = filesystem.display(&journal_relative);
10089    let bytes = filesystem.read_regular_bounded(&journal_relative, MAX_MIGRATION_PLAN_BYTES)?;
10090    let journal: MigrationJournal = serde_json::from_slice(&bytes)
10091        .map_err(|source| FolderbaseError::json(&journal_path, source))?;
10092    validate_journal(
10093        filesystem.display_root(),
10094        migration_id,
10095        &journal_path,
10096        &journal,
10097    )?;
10098    if is_structural_journal(&journal) {
10099        let plan = load_plan_from(filesystem, migration_id)?;
10100        validate_structural_recovery_invariants_in(filesystem, &journal_path, &plan, &journal)?;
10101    }
10102    Ok((journal_path, journal))
10103}
10104
10105fn validate_journal(
10106    root: &Path,
10107    migration_id: &str,
10108    journal_path: &Path,
10109    journal: &MigrationJournal,
10110) -> Result<()> {
10111    if journal.protocol_version != "0.2.0"
10112        || journal.id != migration_id
10113        || journal.root != root
10114        || journal.source_inventory.algorithm != "sha256"
10115        || journal.completed_operations > journal.operations.len()
10116        || journal
10117            .in_flight_operation
10118            .is_some_and(|index| index >= journal.operations.len())
10119    {
10120        return Err(invalid_journal(
10121            journal_path,
10122            "migration journal metadata is inconsistent",
10123        ));
10124    }
10125    if !matches!(
10126        journal.state,
10127        MigrationState::Applying
10128            | MigrationState::Verified
10129            | MigrationState::Conflicted
10130            | MigrationState::RollingBack
10131            | MigrationState::RolledBack
10132    ) {
10133        return Err(invalid_journal(
10134            journal_path,
10135            format!(
10136                "released migration journal has unsupported execution state {}",
10137                journal.state.as_str()
10138            ),
10139        ));
10140    }
10141    if journal_plan_digest(journal)? != journal.approval_digest {
10142        return Err(FolderbaseError::MigrationApprovalMismatch);
10143    }
10144    if is_structural_journal(journal) {
10145        let progress_is_consistent = match journal.state {
10146            MigrationState::Applying => journal
10147                .in_flight_operation
10148                .is_none_or(|index| index == journal.completed_operations),
10149            MigrationState::RollingBack => journal.in_flight_operation.is_none_or(|index| {
10150                journal.completed_operations > 0 && index + 1 == journal.completed_operations
10151            }),
10152            MigrationState::Verified => {
10153                journal.completed_operations == journal.operations.len()
10154                    && journal.in_flight_operation.is_none()
10155            }
10156            MigrationState::RolledBack => {
10157                journal.completed_operations == 0 && journal.in_flight_operation.is_none()
10158            }
10159            _ => false,
10160        };
10161        if !progress_is_consistent {
10162            return Err(invalid_journal(
10163                journal_path,
10164                "structural journal state and progress are inconsistent",
10165            ));
10166        }
10167    }
10168    validate_materialization_records(journal_path, journal)?;
10169    for path in &journal.created_paths {
10170        ensure_safe_relative(path)?;
10171        if !journal_path_is_authorized(journal, path) {
10172            return Err(invalid_journal(
10173                journal_path,
10174                "journal contains a path outside the approved destination set",
10175            ));
10176        }
10177    }
10178    Ok(())
10179}
10180
10181#[derive(Debug, Clone, Copy, PartialEq, Eq)]
10182enum StructuralDiskState {
10183    Original,
10184    Applied,
10185    OriginalAndApplied,
10186    PartialSameInode,
10187    RestoredWithPreservedDestination,
10188    Unknown,
10189}
10190
10191#[cfg(test)]
10192#[allow(dead_code)]
10193fn validate_structural_recovery_invariants(
10194    root: &Path,
10195    journal_path: &Path,
10196    plan: &MigrationPlan,
10197    journal: &MigrationJournal,
10198) -> Result<()> {
10199    validate_structural_recovery_invariants_with(journal_path, plan, journal, |operation| {
10200        observe_structural_disk_state(root, operation)
10201    })
10202}
10203
10204fn validate_structural_recovery_invariants_in(
10205    filesystem: &MigrationFilesystem,
10206    journal_path: &Path,
10207    plan: &MigrationPlan,
10208    journal: &MigrationJournal,
10209) -> Result<()> {
10210    validate_structural_recovery_invariants_with(journal_path, plan, journal, |operation| {
10211        observe_structural_disk_state_in(filesystem, operation)
10212    })
10213}
10214
10215fn validate_structural_recovery_invariants_with(
10216    journal_path: &Path,
10217    plan: &MigrationPlan,
10218    journal: &MigrationJournal,
10219    mut observe: impl FnMut(&MigrationOperation) -> Result<StructuralDiskState>,
10220) -> Result<()> {
10221    let legal_state_pair = match plan.state {
10222        MigrationState::Approved => journal.state == MigrationState::Applying,
10223        MigrationState::Applying => matches!(
10224            journal.state,
10225            MigrationState::Applying
10226                | MigrationState::Verified
10227                | MigrationState::RollingBack
10228                | MigrationState::RolledBack
10229        ),
10230        MigrationState::Verified => matches!(
10231            journal.state,
10232            MigrationState::Verified | MigrationState::RollingBack | MigrationState::RolledBack
10233        ),
10234        MigrationState::Conflicted => matches!(
10235            journal.state,
10236            MigrationState::Applying | MigrationState::RollingBack | MigrationState::RolledBack
10237        ),
10238        MigrationState::RolledBack => journal.state == MigrationState::RolledBack,
10239        _ => false,
10240    };
10241    if !legal_state_pair {
10242        return Err(invalid_journal(
10243            journal_path,
10244            "structural plan and journal states are inconsistent",
10245        ));
10246    }
10247
10248    for (index, operation) in journal.operations.iter().enumerate() {
10249        let observed = observe(operation)?;
10250        let valid = match journal.state {
10251            MigrationState::Applying => {
10252                if index < journal.completed_operations {
10253                    matches!(
10254                        observed,
10255                        StructuralDiskState::Applied | StructuralDiskState::OriginalAndApplied
10256                    )
10257                } else if journal.in_flight_operation == Some(index) {
10258                    matches!(
10259                        observed,
10260                        StructuralDiskState::Original
10261                            | StructuralDiskState::Applied
10262                            | StructuralDiskState::OriginalAndApplied
10263                            | StructuralDiskState::PartialSameInode
10264                    )
10265                } else {
10266                    matches!(
10267                        observed,
10268                        StructuralDiskState::Original | StructuralDiskState::OriginalAndApplied
10269                    )
10270                }
10271            }
10272            MigrationState::RollingBack => {
10273                if journal.in_flight_operation == Some(index) {
10274                    matches!(
10275                        observed,
10276                        StructuralDiskState::Original
10277                            | StructuralDiskState::Applied
10278                            | StructuralDiskState::OriginalAndApplied
10279                            | StructuralDiskState::PartialSameInode
10280                            | StructuralDiskState::RestoredWithPreservedDestination
10281                    )
10282                } else if index < journal.completed_operations {
10283                    matches!(
10284                        observed,
10285                        StructuralDiskState::Applied | StructuralDiskState::OriginalAndApplied
10286                    )
10287                } else {
10288                    matches!(
10289                        observed,
10290                        StructuralDiskState::Original
10291                            | StructuralDiskState::OriginalAndApplied
10292                            | StructuralDiskState::RestoredWithPreservedDestination
10293                    )
10294                }
10295            }
10296            MigrationState::RolledBack => matches!(
10297                observed,
10298                StructuralDiskState::Original
10299                    | StructuralDiskState::OriginalAndApplied
10300                    | StructuralDiskState::RestoredWithPreservedDestination
10301            ),
10302            MigrationState::Verified if plan.state == MigrationState::Applying => {
10303                matches!(
10304                    observed,
10305                    StructuralDiskState::Applied | StructuralDiskState::OriginalAndApplied
10306                )
10307            }
10308            MigrationState::Verified => true,
10309            _ => false,
10310        };
10311        if !valid {
10312            return Err(invalid_journal(
10313                journal_path,
10314                format!(
10315                    "structural operation {index} observed as {observed:?} does not match durable \
10316                     recovery state {:?}, completed prefix {}, or in-flight cursor {:?}",
10317                    journal.state, journal.completed_operations, journal.in_flight_operation
10318                ),
10319            ));
10320        }
10321    }
10322    Ok(())
10323}
10324
10325#[cfg(test)]
10326#[allow(dead_code)]
10327fn observe_structural_disk_state(
10328    root: &Path,
10329    operation: &MigrationOperation,
10330) -> Result<StructuralDiskState> {
10331    match operation {
10332        MigrationOperation::MoveObject {
10333            source_path,
10334            destination_path,
10335            expected_sha256,
10336            ..
10337        } => {
10338            let source = safe_join(root, source_path)?;
10339            let destination = safe_join(root, destination_path)?;
10340            let source_digest = regular_file_digest_if_present(&source)?;
10341            let destination_digest = regular_file_digest_if_present(&destination)?;
10342            match (source_digest, destination_digest) {
10343                (Some(source_digest), None) if source_digest == *expected_sha256 => {
10344                    Ok(StructuralDiskState::Original)
10345                }
10346                (None, Some(_)) if !source.exists() => Ok(StructuralDiskState::Applied),
10347                (Some(source_digest), Some(destination_digest))
10348                    if source_digest == *expected_sha256
10349                        && destination_digest == *expected_sha256 =>
10350                {
10351                    let (source_capability, destination_capability) =
10352                        open_migration_leaf_pair(root, source_path, destination_path)?;
10353                    if source_capability.identity == destination_capability.identity {
10354                        Ok(StructuralDiskState::PartialSameInode)
10355                    } else {
10356                        Ok(StructuralDiskState::RestoredWithPreservedDestination)
10357                    }
10358                }
10359                (Some(source_digest), Some(_)) if source_digest == *expected_sha256 => {
10360                    Ok(StructuralDiskState::RestoredWithPreservedDestination)
10361                }
10362                _ => Ok(StructuralDiskState::Unknown),
10363            }
10364        }
10365        operation if operation.is_structural() => {
10366            let source_path = operation
10367                .structural_source_path()
10368                .expect("structural operation has a source");
10369            let source = safe_join(root, source_path)?;
10370            let expected = operation
10371                .structural_expected_sha256()
10372                .expect("structural operation has an approved source digest");
10373            let result = operation
10374                .structural_expected_result_sha256()
10375                .expect("structural mutation has an approved result digest");
10376            match regular_file_digest_if_present(&source)? {
10377                Some(digest) if digest == expected && digest == result => {
10378                    Ok(StructuralDiskState::OriginalAndApplied)
10379                }
10380                Some(digest) if digest == expected => Ok(StructuralDiskState::Original),
10381                Some(digest) if digest == result => Ok(StructuralDiskState::Applied),
10382                _ => Ok(StructuralDiskState::Unknown),
10383            }
10384        }
10385        _ => Ok(StructuralDiskState::Unknown),
10386    }
10387}
10388
10389fn observe_structural_disk_state_in(
10390    filesystem: &MigrationFilesystem,
10391    operation: &MigrationOperation,
10392) -> Result<StructuralDiskState> {
10393    match operation {
10394        MigrationOperation::MoveObject {
10395            source_path,
10396            destination_path,
10397            expected_sha256,
10398            ..
10399        } => {
10400            let source_digest = filesystem.sha256_regular_if_present(source_path)?;
10401            let destination_digest = filesystem.sha256_regular_if_present(destination_path)?;
10402            match (source_digest, destination_digest) {
10403                (Some(source_digest), None) if source_digest == *expected_sha256 => {
10404                    Ok(StructuralDiskState::Original)
10405                }
10406                (None, Some(_)) => Ok(StructuralDiskState::Applied),
10407                (Some(source_digest), Some(destination_digest))
10408                    if source_digest == *expected_sha256
10409                        && destination_digest == *expected_sha256 =>
10410                {
10411                    let (source_capability, destination_capability) =
10412                        open_migration_leaf_pair_in(filesystem, source_path, destination_path)?;
10413                    if source_capability.identity == destination_capability.identity {
10414                        Ok(StructuralDiskState::PartialSameInode)
10415                    } else {
10416                        Ok(StructuralDiskState::RestoredWithPreservedDestination)
10417                    }
10418                }
10419                (Some(source_digest), Some(_)) if source_digest == *expected_sha256 => {
10420                    Ok(StructuralDiskState::RestoredWithPreservedDestination)
10421                }
10422                _ => Ok(StructuralDiskState::Unknown),
10423            }
10424        }
10425        operation if operation.is_structural() => {
10426            let source_path = operation
10427                .structural_source_path()
10428                .expect("structural operation has a source");
10429            let expected = operation
10430                .structural_expected_sha256()
10431                .expect("structural operation has an approved source digest");
10432            let result = operation
10433                .structural_expected_result_sha256()
10434                .expect("structural mutation has an approved result digest");
10435            match filesystem.sha256_regular_if_present(source_path)? {
10436                Some(digest) if digest == expected && digest == result => {
10437                    Ok(StructuralDiskState::OriginalAndApplied)
10438                }
10439                Some(digest) if digest == expected => Ok(StructuralDiskState::Original),
10440                Some(digest) if digest == result => Ok(StructuralDiskState::Applied),
10441                _ => Ok(StructuralDiskState::Unknown),
10442            }
10443        }
10444        _ => Ok(StructuralDiskState::Unknown),
10445    }
10446}
10447
10448fn validate_materialization_records(journal_path: &Path, journal: &MigrationJournal) -> Result<()> {
10449    const TEMPLATE_REFERENCE: &str = "folderbase.project@0.2.2";
10450
10451    let binds_template = journal
10452        .template_references
10453        .iter()
10454        .any(|reference| reference == TEMPLATE_REFERENCE);
10455    if !binds_template {
10456        if journal.materialized_folderbases.is_empty() && journal.materialized_workspace.is_none() {
10457            return Ok(());
10458        }
10459        return Err(invalid_journal(
10460            journal_path,
10461            "materialization records are not bound by the approved plan",
10462        ));
10463    }
10464    let (workspace_path, approved) = approved_materialization_specs(
10465        &journal.answers,
10466        &journal.targets,
10467        &journal.operations,
10468        journal_path,
10469    )?;
10470    if journal.materialized_folderbases.len() > approved.len() {
10471        return Err(invalid_journal(
10472            journal_path,
10473            "materialized folderbase count exceeds the approved target set",
10474        ));
10475    }
10476    let (allowed_directories, allowed_files) = approved_template_output_paths()?;
10477    for (index, materialized) in journal.materialized_folderbases.iter().enumerate() {
10478        let expected = &approved[index];
10479        if materialized.target_id != expected.target_id
10480            || materialized.path != expected.path
10481            || materialized.name != expected.name
10482            || materialized.template_reference != TEMPLATE_REFERENCE
10483            || !materialized.folderbase_id.starts_with("folderbase_")
10484        {
10485            return Err(invalid_journal(
10486                journal_path,
10487                "materialized folderbase does not match the approved target topology",
10488            ));
10489        }
10490        ensure_safe_relative(&materialized.path)?;
10491        let mut unique_directories = BTreeSet::new();
10492        for path in &materialized.created_directories {
10493            ensure_safe_relative(path)?;
10494            let relative = path.strip_prefix(&materialized.path).map_err(|_| {
10495                invalid_journal(
10496                    journal_path,
10497                    "materialized folderbase path escapes its approved folderbase root",
10498                )
10499            })?;
10500            if !unique_directories.insert(path) || !allowed_directories.contains(relative) {
10501                return Err(invalid_journal(
10502                    journal_path,
10503                    "materialized folderbase contains an unapproved template directory",
10504                ));
10505            }
10506        }
10507        for path in materialized.created_files.keys() {
10508            ensure_safe_relative(path)?;
10509            let relative = path.strip_prefix(&materialized.path).map_err(|_| {
10510                invalid_journal(
10511                    journal_path,
10512                    "materialized folderbase path escapes its approved folderbase root",
10513                )
10514            })?;
10515            if !allowed_files.contains(relative) {
10516                return Err(invalid_journal(
10517                    journal_path,
10518                    "materialized folderbase contains an unapproved template file",
10519                ));
10520            }
10521        }
10522        let manifest = materialized.path.join(".folderbase/manifest.json");
10523        if !materialized.created_files.contains_key(&manifest) {
10524            return Err(invalid_journal(
10525                journal_path,
10526                "materialized folderbase does not include its required manifest write",
10527            ));
10528        }
10529    }
10530    if journal.state == MigrationState::Verified
10531        && (journal.materialized_folderbases.len() != approved.len()
10532            || journal
10533                .materialized_folderbases
10534                .iter()
10535                .any(|folderbase| folderbase.state != MaterializationState::Verified))
10536    {
10537        return Err(invalid_journal(
10538            journal_path,
10539            "verified migration has incomplete folderbase materialization",
10540        ));
10541    }
10542
10543    match &journal.materialized_workspace {
10544        Some(workspace) => {
10545            if approved.len() < 2
10546                || journal.materialized_folderbases.len() != approved.len()
10547                || workspace.path != workspace_path
10548                || workspace.name != materialized_workspace_name(&workspace_path)
10549                || !workspace.workspace_id.starts_with("workspace_")
10550            {
10551                return Err(invalid_journal(
10552                    journal_path,
10553                    "materialized workspace does not match the approved topology",
10554                ));
10555            }
10556            let expected_folderbases = journal
10557                .materialized_folderbases
10558                .iter()
10559                .map(|folderbase| {
10560                    let path = folderbase.path.strip_prefix(&workspace.path).map_err(|_| {
10561                        invalid_journal(
10562                            journal_path,
10563                            "materialized folderbase is outside its approved workspace",
10564                        )
10565                    })?;
10566                    ensure_safe_relative(path)?;
10567                    Ok(WorkspaceFolderbaseLink {
10568                        folderbase_id: folderbase.folderbase_id.clone(),
10569                        label: folderbase.name.clone(),
10570                        path: path.to_path_buf(),
10571                    })
10572                })
10573                .collect::<Result<Vec<_>>>()?;
10574            let expected_files = BTreeSet::from([
10575                workspace.path.join("WORKSPACE.md"),
10576                workspace.path.join(".folderbase-workspace.json"),
10577            ]);
10578            if workspace.folderbases != expected_folderbases
10579                || workspace
10580                    .created_files
10581                    .keys()
10582                    .cloned()
10583                    .collect::<BTreeSet<_>>()
10584                    != expected_files
10585                || (journal.state == MigrationState::Verified
10586                    && workspace.state != MaterializationState::Verified)
10587            {
10588                return Err(invalid_journal(
10589                    journal_path,
10590                    "materialized workspace records exceed the approved navigation surface",
10591                ));
10592            }
10593        }
10594        None if journal.state == MigrationState::Verified && approved.len() > 1 => {
10595            return Err(invalid_journal(
10596                journal_path,
10597                "verified multi-folderbase migration is missing its workspace descriptor",
10598            ));
10599        }
10600        None => {}
10601    }
10602    Ok(())
10603}
10604
10605fn approved_template_output_paths() -> Result<(BTreeSet<PathBuf>, BTreeSet<PathBuf>)> {
10606    let package = load_builtin_template("folderbase.project", "0.2.2")?;
10607    let mut directories = BTreeSet::new();
10608    let mut files = BTreeSet::from([
10609        PathBuf::from(".folderbase/manifest.json"),
10610        PathBuf::from("AGENTS.md"),
10611        PathBuf::from("CLAUDE.md"),
10612    ]);
10613    for artifact in &package.artifacts {
10614        match artifact.kind {
10615            TemplateArtifactKind::Directory => {
10616                directories.insert(artifact.target.clone());
10617            }
10618            TemplateArtifactKind::Text => {
10619                files.insert(artifact.target.clone());
10620            }
10621        }
10622    }
10623    let paths = directories
10624        .iter()
10625        .chain(files.iter())
10626        .cloned()
10627        .collect::<Vec<_>>();
10628    for path in paths {
10629        let mut parent = path.parent();
10630        while let Some(path) = parent {
10631            if path.as_os_str().is_empty() {
10632                break;
10633            }
10634            directories.insert(path.to_path_buf());
10635            parent = path.parent();
10636        }
10637    }
10638    Ok((directories, files))
10639}
10640
10641fn materialized_workspace_name(path: &Path) -> String {
10642    path.file_name()
10643        .and_then(|name| name.to_str())
10644        .map(humanize_name)
10645        .unwrap_or_else(|| "Migration Workspace".to_owned())
10646}
10647
10648fn journal_plan_digest(journal: &MigrationJournal) -> Result<String> {
10649    let bytes = if journal.approval_scheme.as_deref() == Some("migration_plan_v0.2") {
10650        serde_json::to_vec(&(
10651            &journal.protocol_version,
10652            &journal.id,
10653            &journal.root,
10654            MigrationState::Approved,
10655            &journal.source_inventory,
10656            &journal.answers,
10657            &journal.template_references,
10658            &journal.targets,
10659            &journal.operations,
10660            &journal.exclusions,
10661            &journal.plan_extensions,
10662        ))
10663    } else if journal.targets.is_empty() {
10664        serde_json::to_vec(&(
10665            &journal.id,
10666            &journal.root,
10667            MigrationState::Approved,
10668            &journal.source_inventory.digest,
10669            &journal.answers,
10670            &journal.operations,
10671            &journal.exclusions,
10672        ))
10673    } else {
10674        serde_json::to_vec(&(
10675            &journal.id,
10676            &journal.root,
10677            MigrationState::Approved,
10678            &journal.source_inventory.digest,
10679            &journal.answers,
10680            &journal.targets,
10681            &journal.operations,
10682            &journal.exclusions,
10683        ))
10684    }
10685    .map_err(|source| FolderbaseError::json(&journal.root, source))?;
10686    Ok(format!("{:x}", Sha256::digest(bytes)))
10687}
10688
10689fn journal_path_is_authorized(journal: &MigrationJournal, path: &Path) -> bool {
10690    journal.operations.iter().any(|operation| match operation {
10691        MigrationOperation::CreateFolder { path: destination } => {
10692            destination == path || destination.starts_with(path)
10693        }
10694        MigrationOperation::CopyFile {
10695            destination_path, ..
10696        } => destination_path == path || destination_path.starts_with(path),
10697        _ => false,
10698    }) || journal.materialized_folderbases.iter().any(|materialized| {
10699        materialized
10700            .created_directories
10701            .iter()
10702            .any(|candidate| candidate == path)
10703            || materialized.created_files.contains_key(path)
10704    }) || journal
10705        .materialized_workspace
10706        .as_ref()
10707        .is_some_and(|workspace| workspace.created_files.contains_key(path))
10708}
10709
10710#[cfg(test)]
10711#[allow(dead_code)]
10712fn reconcile_in_flight(
10713    root: &Path,
10714    journal_path: &Path,
10715    journal: &mut MigrationJournal,
10716) -> Result<()> {
10717    let Some(index) = journal.in_flight_operation else {
10718        return Ok(());
10719    };
10720    let operation = journal
10721        .operations
10722        .get(index)
10723        .cloned()
10724        .ok_or_else(|| invalid_journal(journal_path, "in-flight operation is out of range"))?;
10725    match operation {
10726        MigrationOperation::CreateFolder { path } => {
10727            let absolute = safe_join(root, &path)?;
10728            if absolute.exists() && !journal.created_paths.contains(&path) {
10729                let metadata = fs::symlink_metadata(&absolute)
10730                    .map_err(|source| FolderbaseError::io(&absolute, source))?;
10731                if !metadata.is_dir() || metadata.file_type().is_symlink() {
10732                    return Err(FolderbaseError::MigrationVerificationFailed(absolute));
10733                }
10734                journal.created_paths.push(path);
10735            }
10736        }
10737        MigrationOperation::CopyFile {
10738            destination_path,
10739            expected_sha256,
10740            ..
10741        } => {
10742            let absolute = safe_join(root, &destination_path)?;
10743            if absolute.exists() && !journal.created_paths.contains(&destination_path) {
10744                let metadata = fs::symlink_metadata(&absolute)
10745                    .map_err(|source| FolderbaseError::io(&absolute, source))?;
10746                if !metadata.is_file()
10747                    || metadata.file_type().is_symlink()
10748                    || sha256_path(&absolute)? != expected_sha256
10749                {
10750                    return Err(FolderbaseError::MigrationVerificationFailed(absolute));
10751                }
10752                journal.created_paths.push(destination_path);
10753            }
10754        }
10755        _ => {
10756            return Err(invalid_journal(
10757                journal_path,
10758                "structural operation reached additive recovery",
10759            ));
10760        }
10761    }
10762    persist_journal(journal_path, journal)
10763}
10764
10765fn reconcile_in_flight_in(
10766    filesystem: &MigrationFilesystem,
10767    journal_path: &Path,
10768    journal: &mut MigrationJournal,
10769) -> Result<()> {
10770    let Some(index) = journal.in_flight_operation else {
10771        return Ok(());
10772    };
10773    let operation = journal
10774        .operations
10775        .get(index)
10776        .cloned()
10777        .ok_or_else(|| invalid_journal(journal_path, "in-flight operation is out of range"))?;
10778    match operation {
10779        MigrationOperation::CreateFolder { path } => {
10780            if let Some(metadata) = filesystem.metadata(&path)?
10781                && !journal.created_paths.contains(&path)
10782            {
10783                if !metadata.is_dir() || metadata.file_type().is_symlink() {
10784                    return Err(FolderbaseError::MigrationVerificationFailed(
10785                        filesystem.display(&path),
10786                    ));
10787                }
10788                journal.created_paths.push(path);
10789            }
10790        }
10791        MigrationOperation::CopyFile {
10792            destination_path,
10793            expected_sha256,
10794            ..
10795        } => {
10796            if let Some(metadata) = filesystem.metadata(&destination_path)?
10797                && !journal.created_paths.contains(&destination_path)
10798            {
10799                if !metadata.is_file()
10800                    || metadata.file_type().is_symlink()
10801                    || filesystem.sha256_regular(&destination_path)? != expected_sha256
10802                {
10803                    return Err(FolderbaseError::MigrationVerificationFailed(
10804                        filesystem.display(&destination_path),
10805                    ));
10806                }
10807                journal.created_paths.push(destination_path);
10808            }
10809        }
10810        _ => {
10811            return Err(invalid_journal(
10812                journal_path,
10813                "structural operation reached additive recovery",
10814            ));
10815        }
10816    }
10817    persist_journal_in(filesystem, journal)
10818}
10819
10820#[cfg(test)]
10821#[allow(dead_code)]
10822fn reconcile_structural_in_flight(
10823    root: &Path,
10824    journal_path: &Path,
10825    journal: &mut MigrationJournal,
10826) -> Result<()> {
10827    reconcile_structural_in_flight_with_hook(root, journal_path, journal, |_| {})
10828}
10829
10830fn reconcile_structural_in_flight_in(
10831    filesystem: &MigrationFilesystem,
10832    journal_path: &Path,
10833    journal: &mut MigrationJournal,
10834) -> Result<()> {
10835    let Some(index) = journal.in_flight_operation else {
10836        return Ok(());
10837    };
10838    let operation = journal
10839        .operations
10840        .get(index)
10841        .ok_or_else(|| invalid_journal(journal_path, "in-flight operation is out of range"))?;
10842    let expected_precondition_identity = journal
10843        .operation_precondition_identities
10844        .get(index)
10845        .and_then(|identity| identity.as_deref());
10846    let expected_result_identity = journal
10847        .operation_result_identities
10848        .get(index)
10849        .and_then(|identity| identity.as_deref());
10850    let verify_identity = |path: &Path, expected: Option<&str>| -> Result<()> {
10851        if let Some(expected) = expected
10852            && filesystem.physical_identity_sha256(path)? != expected
10853        {
10854            return Err(FolderbaseError::MigrationVerificationFailed(
10855                filesystem.display(path),
10856            ));
10857        }
10858        Ok(())
10859    };
10860    refuse_structural_operation_boundaries_in(filesystem, operation)?;
10861    let applied = match operation {
10862        MigrationOperation::MoveObject {
10863            source_path,
10864            destination_path,
10865            expected_sha256,
10866            ..
10867        } => {
10868            let source_digest = filesystem.sha256_regular_if_present(source_path)?;
10869            let destination_digest = filesystem.sha256_regular_if_present(destination_path)?;
10870            if journal.state == MigrationState::RollingBack {
10871                match (source_digest, destination_digest) {
10872                    (Some(source_digest), Some(destination_digest))
10873                        if source_digest == *expected_sha256
10874                            && destination_digest == *expected_sha256 =>
10875                    {
10876                        verify_identity(source_path, expected_precondition_identity)?;
10877                        verify_identity(destination_path, expected_result_identity)?;
10878                        let (source_capability, destination_capability) =
10879                            open_migration_leaf_pair_in(filesystem, source_path, destination_path)?;
10880                        if source_capability.identity == destination_capability.identity {
10881                            remove_matching_destination_with(
10882                                source_capability,
10883                                destination_capability,
10884                                &mut |_| {},
10885                            )?;
10886                        }
10887                        true
10888                    }
10889                    (Some(source_digest), _) if source_digest == *expected_sha256 => {
10890                        verify_identity(source_path, expected_precondition_identity)?;
10891                        true
10892                    }
10893                    (None, _) => false,
10894                    _ => {
10895                        return Err(FolderbaseError::MigrationVerificationFailed(
10896                            filesystem.display(source_path),
10897                        ));
10898                    }
10899                }
10900            } else {
10901                match (source_digest, destination_digest) {
10902                    (Some(source_digest), None) if source_digest == *expected_sha256 => {
10903                        verify_identity(source_path, expected_precondition_identity)?;
10904                        false
10905                    }
10906                    (None, Some(destination_digest)) if destination_digest == *expected_sha256 => {
10907                        verify_identity(destination_path, expected_result_identity)?;
10908                        true
10909                    }
10910                    (Some(source_digest), Some(destination_digest))
10911                        if source_digest == *expected_sha256
10912                            && destination_digest == *expected_sha256 =>
10913                    {
10914                        verify_identity(source_path, expected_precondition_identity)?;
10915                        verify_identity(destination_path, expected_result_identity)?;
10916                        let (source_capability, destination_capability) =
10917                            open_migration_leaf_pair_in(filesystem, source_path, destination_path)?;
10918                        if source_capability.identity != destination_capability.identity {
10919                            return Err(FolderbaseError::MigrationVerificationFailed(
10920                                filesystem.display(destination_path),
10921                            ));
10922                        }
10923                        remove_matching_destination_with(
10924                            source_capability,
10925                            destination_capability,
10926                            &mut |_| {},
10927                        )?;
10928                        false
10929                    }
10930                    _ => {
10931                        return Err(FolderbaseError::MigrationVerificationFailed(
10932                            filesystem.display(destination_path),
10933                        ));
10934                    }
10935                }
10936            }
10937        }
10938        operation if operation.is_structural() => {
10939            let source_path = operation
10940                .structural_source_path()
10941                .expect("structural operation has a source");
10942            let current = filesystem.sha256_regular(source_path)?;
10943            let expected = operation
10944                .structural_expected_sha256()
10945                .expect("structural operation has a source digest");
10946            let result = operation
10947                .structural_expected_result_sha256()
10948                .expect("structural operation has a result digest");
10949            if journal.state == MigrationState::RollingBack {
10950                if current == expected {
10951                    verify_identity(source_path, expected_precondition_identity)?;
10952                    true
10953                } else if current == result {
10954                    verify_identity(source_path, expected_result_identity)?;
10955                    false
10956                } else {
10957                    return Err(FolderbaseError::MigrationVerificationFailed(
10958                        filesystem.display(source_path),
10959                    ));
10960                }
10961            } else if current == expected {
10962                verify_identity(source_path, expected_precondition_identity)?;
10963                false
10964            } else if current == result {
10965                verify_identity(source_path, expected_result_identity)?;
10966                true
10967            } else {
10968                return Err(FolderbaseError::MigrationVerificationFailed(
10969                    filesystem.display(source_path),
10970                ));
10971            }
10972        }
10973        _ => {
10974            return Err(invalid_journal(
10975                journal_path,
10976                "additive operation reached structural recovery",
10977            ));
10978        }
10979    };
10980    if journal.state == MigrationState::RollingBack && applied {
10981        journal.completed_operations = index;
10982    } else if applied {
10983        journal.completed_operations = journal.completed_operations.max(index + 1);
10984    }
10985    journal.in_flight_operation = None;
10986    persist_journal_in(filesystem, journal)
10987}
10988
10989#[cfg(test)]
10990#[allow(dead_code)]
10991fn reconcile_structural_in_flight_with_hook(
10992    root: &Path,
10993    journal_path: &Path,
10994    journal: &mut MigrationJournal,
10995    mut before_final_destination_revalidation: impl FnMut(&Path),
10996) -> Result<()> {
10997    let Some(index) = journal.in_flight_operation else {
10998        return Ok(());
10999    };
11000    let operation = journal
11001        .operations
11002        .get(index)
11003        .ok_or_else(|| invalid_journal(journal_path, "in-flight operation is out of range"))?;
11004    refuse_structural_operation_boundaries(root, operation)?;
11005    let applied = match operation {
11006        MigrationOperation::MoveObject {
11007            source_path,
11008            destination_path,
11009            expected_sha256,
11010            ..
11011        } => {
11012            let source = safe_join(root, source_path)?;
11013            let destination = safe_join(root, destination_path)?;
11014            if journal.state == MigrationState::RollingBack {
11015                match (
11016                    regular_file_digest_if_present(&source)?,
11017                    regular_file_digest_if_present(&destination)?,
11018                ) {
11019                    (Some(source_digest), Some(destination_digest))
11020                        if source_digest == *expected_sha256
11021                            && destination_digest == *expected_sha256 =>
11022                    {
11023                        let (source_capability, destination_capability) =
11024                            open_migration_leaf_pair(root, source_path, destination_path)?;
11025                        if source_capability.identity == destination_capability.identity {
11026                            remove_matching_destination_with(
11027                                source_capability,
11028                                destination_capability,
11029                                &mut before_final_destination_revalidation,
11030                            )?;
11031                        }
11032                        true
11033                    }
11034                    (Some(source_digest), _) if source_digest == *expected_sha256 => true,
11035                    (None, _) if !source.exists() => false,
11036                    _ => {
11037                        return Err(FolderbaseError::MigrationVerificationFailed(
11038                            source_path.clone(),
11039                        ));
11040                    }
11041                }
11042            } else {
11043                match (source.exists(), destination.exists()) {
11044                    (true, false) if sha256_path(&source)? == *expected_sha256 => false,
11045                    (false, true) if sha256_path(&destination)? == *expected_sha256 => true,
11046                    (true, true)
11047                        if sha256_path(&source)? == *expected_sha256
11048                            && sha256_path(&destination)? == *expected_sha256 =>
11049                    {
11050                        let (source_capability, destination_capability) =
11051                            open_migration_leaf_pair(root, source_path, destination_path)?;
11052                        if source_capability.identity != destination_capability.identity {
11053                            return Err(FolderbaseError::MigrationVerificationFailed(
11054                                destination_path.clone(),
11055                            ));
11056                        }
11057                        remove_matching_destination_with(
11058                            source_capability,
11059                            destination_capability,
11060                            &mut before_final_destination_revalidation,
11061                        )?;
11062                        false
11063                    }
11064                    _ => {
11065                        return Err(FolderbaseError::MigrationVerificationFailed(
11066                            destination_path.clone(),
11067                        ));
11068                    }
11069                }
11070            }
11071        }
11072        operation if operation.is_structural() => {
11073            let source_path = operation
11074                .structural_source_path()
11075                .expect("structural operation has a source");
11076            let source = safe_join(root, source_path)?;
11077            let current = sha256_path(&source)?;
11078            let expected = operation
11079                .structural_expected_sha256()
11080                .expect("structural operation has a source digest");
11081            let result = operation
11082                .structural_expected_result_sha256()
11083                .expect("structural operation has a result digest");
11084            if journal.state == MigrationState::RollingBack {
11085                if current == expected {
11086                    true
11087                } else if current == result {
11088                    false
11089                } else {
11090                    return Err(FolderbaseError::MigrationVerificationFailed(source));
11091                }
11092            } else if current == expected {
11093                false
11094            } else if current == result {
11095                true
11096            } else {
11097                return Err(FolderbaseError::MigrationVerificationFailed(source));
11098            }
11099        }
11100        _ => {
11101            return Err(invalid_journal(
11102                journal_path,
11103                "additive operation reached structural recovery",
11104            ));
11105        }
11106    };
11107    if journal.state == MigrationState::RollingBack && applied {
11108        journal.completed_operations = index;
11109    } else if applied {
11110        journal.completed_operations = journal.completed_operations.max(index + 1);
11111    }
11112    journal.in_flight_operation = None;
11113    persist_journal(journal_path, journal)
11114}
11115
11116struct MigrationLeafCapability {
11117    root: Dir,
11118    root_display: PathBuf,
11119    _parent: Dir,
11120    parent_identity: PhysicalIdentity,
11121    parent_relative: PathBuf,
11122    name: OsString,
11123    display: PathBuf,
11124    identity: RetainedPhysicalIdentity,
11125}
11126
11127#[cfg(test)]
11128#[allow(dead_code)]
11129fn open_migration_leaf_pair(
11130    root: &Path,
11131    source: &Path,
11132    destination: &Path,
11133) -> Result<(MigrationLeafCapability, MigrationLeafCapability)> {
11134    let root_capability = open_migration_root_nofollow(root)?;
11135    Ok((
11136        open_migration_leaf_from_root(&root_capability, root, source)?,
11137        open_migration_leaf_from_root(&root_capability, root, destination)?,
11138    ))
11139}
11140
11141fn open_migration_leaf_pair_in(
11142    filesystem: &MigrationFilesystem,
11143    source: &Path,
11144    destination: &Path,
11145) -> Result<(MigrationLeafCapability, MigrationLeafCapability)> {
11146    let root_capability = filesystem.open_directory(Path::new(""))?;
11147    Ok((
11148        open_migration_leaf_from_root(&root_capability, filesystem.display_root(), source)?,
11149        open_migration_leaf_from_root(&root_capability, filesystem.display_root(), destination)?,
11150    ))
11151}
11152
11153fn open_migration_leaf_from_root(
11154    root_capability: &Dir,
11155    root: &Path,
11156    relative: &Path,
11157) -> Result<MigrationLeafCapability> {
11158    let name = relative
11159        .file_name()
11160        .ok_or_else(|| FolderbaseError::UnsafePath(relative.to_path_buf()))?
11161        .to_os_string();
11162    let parent_relative = relative.parent().unwrap_or_else(|| Path::new(""));
11163    let parent = open_migration_directory_from_root(root_capability, parent_relative, root)?;
11164    let parent_identity = migration_directory_identity(&parent, &root.join(parent_relative))?;
11165    let display = root.join(relative);
11166    let identity = open_migration_regular_identity(&parent, &name, &display)?;
11167    Ok(MigrationLeafCapability {
11168        root: root_capability
11169            .try_clone()
11170            .map_err(|error| FolderbaseError::io(root, error))?,
11171        root_display: root.to_path_buf(),
11172        _parent: parent,
11173        parent_identity,
11174        parent_relative: parent_relative.to_path_buf(),
11175        name,
11176        display,
11177        identity,
11178    })
11179}
11180
11181#[cfg(test)]
11182#[allow(dead_code)]
11183fn open_migration_root_nofollow(root: &Path) -> Result<Dir> {
11184    let mut options = fs::OpenOptions::new();
11185    options.read(true);
11186    #[cfg(unix)]
11187    {
11188        use std::os::unix::fs::OpenOptionsExt;
11189
11190        options.custom_flags(libc::O_CLOEXEC | libc::O_DIRECTORY | libc::O_NOFOLLOW);
11191    }
11192    #[cfg(windows)]
11193    {
11194        use std::os::windows::fs::OpenOptionsExt;
11195        use windows_sys::Win32::Storage::FileSystem::{
11196            FILE_FLAG_BACKUP_SEMANTICS, FILE_FLAG_OPEN_REPARSE_POINT, FILE_SHARE_READ,
11197            FILE_SHARE_WRITE,
11198        };
11199
11200        options
11201            .access_mode(0)
11202            .custom_flags(FILE_FLAG_BACKUP_SEMANTICS | FILE_FLAG_OPEN_REPARSE_POINT)
11203            .share_mode(FILE_SHARE_READ | FILE_SHARE_WRITE);
11204    }
11205    let file = options
11206        .open(root)
11207        .map_err(|error| FolderbaseError::io(root, error))?;
11208    let metadata = file
11209        .metadata()
11210        .map_err(|error| FolderbaseError::io(root, error))?;
11211    if metadata_is_link_or_reparse(&metadata) || !metadata.is_dir() {
11212        return Err(FolderbaseError::UnsafePath(root.to_path_buf()));
11213    }
11214    Ok(Dir::from_std_file(file))
11215}
11216
11217fn open_migration_directory_from_root(
11218    root: &Dir,
11219    relative: &Path,
11220    root_display: &Path,
11221) -> Result<Dir> {
11222    let mut directory = root
11223        .try_clone()
11224        .map_err(|error| FolderbaseError::io(root_display, error))?;
11225    let mut current_display = root_display.to_path_buf();
11226    for component in relative.components() {
11227        let Component::Normal(name) = component else {
11228            return Err(FolderbaseError::UnsafePath(relative.to_path_buf()));
11229        };
11230        current_display.push(name);
11231        directory = open_migration_directory_nofollow(&directory, name, &current_display)
11232            .map_err(|error| FolderbaseError::io(&current_display, error))?;
11233    }
11234    Ok(directory)
11235}
11236
11237#[cfg(not(windows))]
11238fn open_migration_directory_nofollow(
11239    parent: &Dir,
11240    name: &OsStr,
11241    _display: &Path,
11242) -> io::Result<Dir> {
11243    parent.open_dir_nofollow(name)
11244}
11245
11246#[cfg(windows)]
11247fn open_migration_directory_nofollow(
11248    parent: &Dir,
11249    name: &OsStr,
11250    display: &Path,
11251) -> io::Result<Dir> {
11252    use cap_std::fs::OpenOptionsExt;
11253    use windows_sys::Win32::Storage::FileSystem::{
11254        FILE_FLAG_BACKUP_SEMANTICS, FILE_FLAG_OPEN_REPARSE_POINT, FILE_SHARE_READ, FILE_SHARE_WRITE,
11255    };
11256
11257    let mut options = CapOpenOptions::new();
11258    options
11259        .access_mode(0)
11260        .follow(FollowSymlinks::No)
11261        .custom_flags(FILE_FLAG_BACKUP_SEMANTICS | FILE_FLAG_OPEN_REPARSE_POINT)
11262        .share_mode(FILE_SHARE_READ | FILE_SHARE_WRITE);
11263    let file = parent.open_with(name, &options)?.into_std();
11264    let metadata = file.metadata()?;
11265    if metadata_is_link_or_reparse(&metadata) || !metadata.is_dir() {
11266        return Err(io::Error::other(format!(
11267            "unsafe migration directory capability: {}",
11268            display.display()
11269        )));
11270    }
11271    Ok(Dir::from_std_file(file))
11272}
11273
11274fn migration_directory_identity(directory: &Dir, display: &Path) -> Result<PhysicalIdentity> {
11275    let file = directory
11276        .try_clone()
11277        .map_err(|error| FolderbaseError::io(display, error))?
11278        .into_std_file();
11279    PhysicalIdentity::from_file(&file).map_err(|error| FolderbaseError::io(display, error))
11280}
11281
11282fn open_migration_regular_identity(
11283    parent: &Dir,
11284    name: &OsStr,
11285    display: &Path,
11286) -> Result<RetainedPhysicalIdentity> {
11287    let mut options = CapOpenOptions::new();
11288    options.read(true).follow(FollowSymlinks::No);
11289    #[cfg(windows)]
11290    {
11291        use cap_std::fs::OpenOptionsExt;
11292        use windows_sys::Win32::Storage::FileSystem::{
11293            FILE_FLAG_BACKUP_SEMANTICS, FILE_FLAG_OPEN_REPARSE_POINT, FILE_SHARE_READ,
11294            FILE_SHARE_WRITE,
11295        };
11296
11297        options
11298            .access_mode(0)
11299            .custom_flags(FILE_FLAG_BACKUP_SEMANTICS | FILE_FLAG_OPEN_REPARSE_POINT)
11300            .share_mode(FILE_SHARE_READ | FILE_SHARE_WRITE);
11301    }
11302    let file = parent
11303        .open_with(name, &options)
11304        .map_err(|error| FolderbaseError::io(display, error))?
11305        .into_std();
11306    let metadata = file
11307        .metadata()
11308        .map_err(|error| FolderbaseError::io(display, error))?;
11309    if metadata_is_link_or_reparse(&metadata) || !metadata.is_file() {
11310        return Err(FolderbaseError::UnsafePath(display.to_path_buf()));
11311    }
11312    RetainedPhysicalIdentity::from_file(file).map_err(|error| FolderbaseError::io(display, error))
11313}
11314
11315impl MigrationLeafCapability {
11316    fn reopen_parent(&self) -> Result<Dir> {
11317        let parent = open_migration_directory_from_root(
11318            &self.root,
11319            &self.parent_relative,
11320            &self.root_display,
11321        )?;
11322        if migration_directory_identity(
11323            &parent,
11324            self.display
11325                .parent()
11326                .ok_or_else(|| FolderbaseError::UnsafePath(self.display.clone()))?,
11327        )? != self.parent_identity
11328        {
11329            return Err(FolderbaseError::MigrationVerificationFailed(
11330                self.display.clone(),
11331            ));
11332        }
11333        Ok(parent)
11334    }
11335}
11336
11337fn remove_matching_destination_with(
11338    source: MigrationLeafCapability,
11339    destination: MigrationLeafCapability,
11340    before_final_destination_revalidation: &mut impl FnMut(&Path),
11341) -> Result<()> {
11342    if source.identity != destination.identity {
11343        return Err(FolderbaseError::MigrationVerificationFailed(
11344            destination.display.clone(),
11345        ));
11346    }
11347    before_final_destination_revalidation(&destination.display);
11348    let destination_parent = destination.reopen_parent()?;
11349    let final_destination = open_migration_regular_identity(
11350        &destination_parent,
11351        &destination.name,
11352        &destination.display,
11353    )?;
11354    if final_destination != destination.identity {
11355        return Err(FolderbaseError::MigrationVerificationFailed(
11356            destination.display.clone(),
11357        ));
11358    }
11359
11360    #[cfg(windows)]
11361    {
11362        // Windows child handles deny deletion. Relinquish them only after the
11363        // final capability-relative identity proof; retain both the root and
11364        // exact parent capabilities so ancestor substitution cannot redirect
11365        // the removal. The remaining leaf-name transition uses the same
11366        // cooperative namespace contract as ADR 0001.
11367        drop(final_destination);
11368        drop(destination.identity);
11369        drop(source.identity);
11370    }
11371    #[cfg(not(windows))]
11372    {
11373        // POSIX permits unlink through the retained parent while every child
11374        // authority remains live, eliminating identity-reuse authorization.
11375        let _ = (&final_destination, &destination.identity, &source.identity);
11376    }
11377
11378    destination_parent
11379        .remove_file(&destination.name)
11380        .map_err(|error| FolderbaseError::io(&destination.display, error))?;
11381    sync_migration_directory(
11382        &destination_parent,
11383        destination
11384            .display
11385            .parent()
11386            .ok_or_else(|| FolderbaseError::UnsafePath(destination.display.clone()))?,
11387    )
11388}
11389
11390#[cfg(unix)]
11391fn sync_migration_directory(directory: &Dir, display: &Path) -> Result<()> {
11392    let mut options = CapOpenOptions::new();
11393    options.read(true).follow(FollowSymlinks::No);
11394    directory
11395        .open_with(Path::new("."), &options)
11396        .and_then(|file| file.into_std().sync_all())
11397        .map_err(|error| FolderbaseError::io(display, error))
11398}
11399
11400#[cfg(windows)]
11401fn sync_migration_directory(_directory: &Dir, _display: &Path) -> Result<()> {
11402    // Windows exposes no documented POSIX directory-fsync equivalent. The
11403    // retained directory capability still confines and revalidates removal.
11404    Ok(())
11405}
11406
11407#[cfg(not(any(unix, windows)))]
11408fn sync_migration_directory(directory: &Dir, display: &Path) -> Result<()> {
11409    directory
11410        .try_clone()
11411        .and_then(|directory| directory.into_std_file().sync_all())
11412        .map_err(|error| FolderbaseError::io(display, error))
11413}
11414
11415#[cfg(test)]
11416#[allow(dead_code)]
11417fn rollback_structural_journal(
11418    root: &Path,
11419    journal_path: &Path,
11420    journal: &mut MigrationJournal,
11421) -> Result<RollbackResult> {
11422    rollback_structural_journal_with_hook(root, journal_path, journal, |_| {})
11423}
11424
11425fn rollback_structural_journal_in(
11426    filesystem: &MigrationFilesystem,
11427    journal_path: &Path,
11428    journal: &mut MigrationJournal,
11429) -> Result<RollbackResult> {
11430    if !matches!(
11431        journal.state,
11432        MigrationState::Applying | MigrationState::Verified | MigrationState::RollingBack
11433    ) || !is_structural_journal(journal)
11434    {
11435        return Err(FolderbaseError::InvalidMigrationState {
11436            expected: MigrationState::Verified.as_str(),
11437            actual: journal.state.as_str().to_owned(),
11438        });
11439    }
11440    reconcile_structural_in_flight_in(filesystem, journal_path, journal)?;
11441    for operation in journal.operations.iter().take(journal.completed_operations) {
11442        verify_structural_rollback_precondition_in(filesystem, operation)?;
11443    }
11444    journal.state = MigrationState::RollingBack;
11445    persist_journal_in(filesystem, journal)?;
11446    let mut affected_paths = Vec::new();
11447
11448    while journal.completed_operations > 0 {
11449        let index = journal.completed_operations - 1;
11450        let operation = journal.operations[index].clone();
11451        refuse_structural_operation_boundaries_in(filesystem, &operation)?;
11452        journal.in_flight_operation = Some(index);
11453        persist_journal_in(filesystem, journal)?;
11454        if let Some(expected_identity) = journal
11455            .operation_result_identities
11456            .get(index)
11457            .and_then(|identity| identity.as_deref())
11458        {
11459            let result_path = structural_visible_result_path(&operation);
11460            if filesystem.physical_identity_sha256(result_path)? != expected_identity {
11461                return Err(FolderbaseError::MigrationVerificationFailed(
11462                    filesystem.display(result_path),
11463                ));
11464            }
11465        }
11466        match &operation {
11467            MigrationOperation::MoveObject {
11468                source_path,
11469                destination_path,
11470                expected_sha256,
11471                ..
11472            } => {
11473                let (snapshot_path, snapshot_sha256) =
11474                    operation.structural_snapshot().ok_or_else(|| {
11475                        invalid_journal(journal_path, "structural snapshot is missing")
11476                    })?;
11477                match filesystem.sha256_regular_if_present(source_path)? {
11478                    Some(digest) if digest == *expected_sha256 => {}
11479                    Some(_) => {
11480                        return Err(FolderbaseError::MigrationVerificationFailed(
11481                            filesystem.display(source_path),
11482                        ));
11483                    }
11484                    None => {
11485                        if filesystem
11486                            .sha256_regular_if_present(destination_path)?
11487                            .is_some_and(|digest| digest == *expected_sha256)
11488                        {
11489                            move_file_no_replace_in(
11490                                filesystem,
11491                                destination_path,
11492                                source_path,
11493                                expected_sha256,
11494                            )?;
11495                            affected_paths.push(destination_path.clone());
11496                        } else {
11497                            let snapshot = filesystem
11498                                .read_regular_bounded(snapshot_path, MAX_MIGRATION_PLAN_BYTES)?;
11499                            if sha256_bytes(&snapshot) != snapshot_sha256 {
11500                                return Err(FolderbaseError::MigrationVerificationFailed(
11501                                    filesystem.display(snapshot_path),
11502                                ));
11503                            }
11504                            filesystem.publish_new(source_path, &snapshot)?;
11505                        }
11506                    }
11507                }
11508                if filesystem.sha256_regular(source_path)? != snapshot_sha256 {
11509                    return Err(FolderbaseError::MigrationVerificationFailed(
11510                        filesystem.display(source_path),
11511                    ));
11512                }
11513            }
11514            operation if operation.is_structural() => {
11515                let source_path = operation
11516                    .structural_source_path()
11517                    .expect("structural operation has a source");
11518                let expected_result = operation
11519                    .structural_expected_result_sha256()
11520                    .expect("structural mutation has a result digest");
11521                let (snapshot_path, snapshot_sha256) =
11522                    operation.structural_snapshot().ok_or_else(|| {
11523                        invalid_journal(journal_path, "structural snapshot is missing")
11524                    })?;
11525                let snapshot =
11526                    filesystem.read_regular_bounded(snapshot_path, MAX_MIGRATION_PLAN_BYTES)?;
11527                if sha256_bytes(&snapshot) != snapshot_sha256 {
11528                    return Err(FolderbaseError::MigrationVerificationFailed(
11529                        filesystem.display(snapshot_path),
11530                    ));
11531                }
11532                replace_file_atomically_in(filesystem, source_path, expected_result, &snapshot)?;
11533                affected_paths.push(source_path.to_path_buf());
11534            }
11535            _ => {
11536                return Err(invalid_journal(
11537                    journal_path,
11538                    "additive operation reached structural rollback",
11539                ));
11540            }
11541        }
11542        journal.completed_operations = index;
11543        journal.in_flight_operation = None;
11544        persist_journal_in(filesystem, journal)?;
11545    }
11546
11547    journal.in_flight_operation = None;
11548    journal.state = MigrationState::RolledBack;
11549    persist_journal_in(filesystem, journal)?;
11550    cleanup_staging_in(filesystem, &journal.id);
11551    Ok(RollbackResult {
11552        migration_id: journal.id.clone(),
11553        removed_paths: affected_paths,
11554        state: MigrationState::RolledBack,
11555    })
11556}
11557
11558#[cfg(test)]
11559#[allow(dead_code)]
11560fn rollback_structural_journal_with_hook(
11561    root: &Path,
11562    journal_path: &Path,
11563    journal: &mut MigrationJournal,
11564    mut checkpoint: impl FnMut(StructuralRollbackCheckpoint),
11565) -> Result<RollbackResult> {
11566    if !matches!(
11567        journal.state,
11568        MigrationState::Applying | MigrationState::Verified | MigrationState::RollingBack
11569    ) || !is_structural_journal(journal)
11570    {
11571        return Err(FolderbaseError::InvalidMigrationState {
11572            expected: MigrationState::Verified.as_str(),
11573            actual: journal.state.as_str().to_owned(),
11574        });
11575    }
11576    reconcile_structural_in_flight(root, journal_path, journal)?;
11577    for operation in journal.operations.iter().take(journal.completed_operations) {
11578        verify_structural_rollback_precondition(root, operation)?;
11579    }
11580    journal.state = MigrationState::RollingBack;
11581    persist_journal(journal_path, journal)?;
11582    checkpoint(StructuralRollbackCheckpoint::Started);
11583    let mut affected_paths = Vec::new();
11584
11585    while journal.completed_operations > 0 {
11586        let index = journal.completed_operations - 1;
11587        let operation = journal.operations[index].clone();
11588        refuse_structural_operation_boundaries(root, &operation)?;
11589        journal.in_flight_operation = Some(index);
11590        persist_journal(journal_path, journal)?;
11591        checkpoint(StructuralRollbackCheckpoint::OperationPlanned(index));
11592        if let Some(expected_identity) = journal
11593            .operation_result_identities
11594            .get(index)
11595            .and_then(|identity| identity.as_deref())
11596        {
11597            let result_path = safe_join(root, structural_visible_result_path(&operation))?;
11598            let current_identity = PhysicalIdentity::from_path(&result_path)
11599                .map(PhysicalIdentity::stable_sha256)
11600                .map_err(|source| FolderbaseError::io(&result_path, source))?;
11601            if current_identity != expected_identity {
11602                return Err(FolderbaseError::MigrationVerificationFailed(result_path));
11603            }
11604        }
11605        match &operation {
11606            MigrationOperation::MoveObject {
11607                source_path,
11608                destination_path,
11609                expected_sha256,
11610                ..
11611            } => {
11612                let source = safe_join(root, source_path)?;
11613                let destination = safe_join(root, destination_path)?;
11614                let (snapshot_path, snapshot_sha256) =
11615                    operation.structural_snapshot().ok_or_else(|| {
11616                        invalid_journal(journal_path, "structural snapshot is missing")
11617                    })?;
11618                let snapshot = safe_join(root, snapshot_path)?;
11619                match regular_file_digest_if_present(&source)? {
11620                    Some(digest) if digest == *expected_sha256 => {}
11621                    Some(_) => {
11622                        return Err(FolderbaseError::MigrationVerificationFailed(source));
11623                    }
11624                    None => {
11625                        if regular_file_digest_if_present(&destination)?
11626                            .is_some_and(|digest| digest == *expected_sha256)
11627                        {
11628                            move_file_no_replace(&destination, &source, expected_sha256)?;
11629                            affected_paths.push(destination_path.clone());
11630                        } else {
11631                            restore_snapshot_no_clobber(
11632                                root,
11633                                &journal.id,
11634                                index,
11635                                &snapshot,
11636                                &source,
11637                                snapshot_sha256,
11638                            )?;
11639                            if sha256_path(&source)? != snapshot_sha256 {
11640                                return Err(FolderbaseError::MigrationVerificationFailed(source));
11641                            }
11642                        }
11643                    }
11644                }
11645            }
11646            operation if operation.is_structural() => {
11647                let source_path = operation
11648                    .structural_source_path()
11649                    .expect("structural operation has a source");
11650                let source = safe_join(root, source_path)?;
11651                let expected_result = operation
11652                    .structural_expected_result_sha256()
11653                    .expect("structural mutation has a result digest");
11654                let (snapshot_path, snapshot_sha256) =
11655                    operation.structural_snapshot().ok_or_else(|| {
11656                        invalid_journal(journal_path, "structural snapshot is missing")
11657                    })?;
11658                let snapshot = safe_join(root, snapshot_path)?;
11659                let snapshot_bytes = read_bounded_regular(&snapshot, MAX_MIGRATION_PLAN_BYTES)?;
11660                if sha256_bytes(&snapshot_bytes) != snapshot_sha256 {
11661                    return Err(FolderbaseError::MigrationVerificationFailed(snapshot));
11662                }
11663                replace_file_atomically(&source, expected_result, &snapshot_bytes)?;
11664                if sha256_path(&source)? != snapshot_sha256 {
11665                    return Err(FolderbaseError::MigrationVerificationFailed(source));
11666                }
11667                affected_paths.push(source_path.to_path_buf());
11668            }
11669            _ => {
11670                return Err(invalid_journal(
11671                    journal_path,
11672                    "additive operation reached structural rollback",
11673                ));
11674            }
11675        }
11676        checkpoint(StructuralRollbackCheckpoint::OperationApplied(index));
11677        journal.completed_operations = index;
11678        journal.in_flight_operation = None;
11679        persist_journal(journal_path, journal)?;
11680        checkpoint(StructuralRollbackCheckpoint::OperationCompleted(index));
11681    }
11682
11683    journal.in_flight_operation = None;
11684    journal.state = MigrationState::RolledBack;
11685    persist_journal(journal_path, journal)?;
11686    checkpoint(StructuralRollbackCheckpoint::Completed);
11687    cleanup_staging(root, &journal.id);
11688    Ok(RollbackResult {
11689        migration_id: journal.id.clone(),
11690        removed_paths: affected_paths,
11691        state: MigrationState::RolledBack,
11692    })
11693}
11694
11695#[cfg(test)]
11696#[allow(dead_code)]
11697fn verify_structural_rollback_precondition(
11698    root: &Path,
11699    operation: &MigrationOperation,
11700) -> Result<()> {
11701    refuse_structural_operation_boundaries(root, operation)?;
11702    let (snapshot_path, snapshot_sha256) = operation
11703        .structural_snapshot()
11704        .ok_or_else(|| invalid_journal(root, "structural snapshot is missing"))?;
11705    let snapshot = safe_join(root, snapshot_path)?;
11706    if sha256_path(&snapshot)? != snapshot_sha256 {
11707        return Err(FolderbaseError::MigrationVerificationFailed(snapshot));
11708    }
11709    match operation {
11710        MigrationOperation::MoveObject {
11711            source_path,
11712            destination_path,
11713            expected_sha256,
11714            ..
11715        } => {
11716            let source = safe_join(root, source_path)?;
11717            match regular_file_digest_if_present(&source)? {
11718                Some(digest) if digest == *expected_sha256 => {}
11719                Some(_) => return Err(FolderbaseError::MigrationVerificationFailed(source)),
11720                None => {
11721                    let _ = safe_join(root, destination_path)?;
11722                }
11723            }
11724        }
11725        operation if operation.is_structural() => {
11726            let source_path = operation
11727                .structural_source_path()
11728                .expect("structural operation has a source");
11729            if sha256_path(&safe_join(root, source_path)?)?
11730                != operation
11731                    .structural_expected_result_sha256()
11732                    .expect("structural operation has a result digest")
11733            {
11734                return Err(FolderbaseError::MigrationVerificationFailed(
11735                    source_path.to_path_buf(),
11736                ));
11737            }
11738        }
11739        _ => {
11740            return Err(invalid_journal(
11741                root,
11742                "additive operation reached structural rollback verification",
11743            ));
11744        }
11745    }
11746    Ok(())
11747}
11748
11749fn verify_structural_rollback_precondition_in(
11750    filesystem: &MigrationFilesystem,
11751    operation: &MigrationOperation,
11752) -> Result<()> {
11753    refuse_structural_operation_boundaries_in(filesystem, operation)?;
11754    let (snapshot_path, snapshot_sha256) = operation.structural_snapshot().ok_or_else(|| {
11755        invalid_journal(filesystem.display_root(), "structural snapshot is missing")
11756    })?;
11757    if filesystem.sha256_regular(snapshot_path)? != snapshot_sha256 {
11758        return Err(FolderbaseError::MigrationVerificationFailed(
11759            filesystem.display(snapshot_path),
11760        ));
11761    }
11762    match operation {
11763        MigrationOperation::MoveObject {
11764            source_path,
11765            destination_path,
11766            expected_sha256,
11767            ..
11768        } => match filesystem.sha256_regular_if_present(source_path)? {
11769            Some(digest) if digest == *expected_sha256 => {}
11770            Some(_) => {
11771                return Err(FolderbaseError::MigrationVerificationFailed(
11772                    filesystem.display(source_path),
11773                ));
11774            }
11775            None => {
11776                let _ = filesystem.metadata(destination_path)?;
11777            }
11778        },
11779        operation if operation.is_structural() => {
11780            let source_path = operation
11781                .structural_source_path()
11782                .expect("structural operation has a source");
11783            if filesystem.sha256_regular(source_path)?
11784                != operation
11785                    .structural_expected_result_sha256()
11786                    .expect("structural operation has a result digest")
11787            {
11788                return Err(FolderbaseError::MigrationVerificationFailed(
11789                    filesystem.display(source_path),
11790                ));
11791            }
11792        }
11793        _ => {
11794            return Err(invalid_journal(
11795                filesystem.display_root(),
11796                "additive operation reached structural rollback verification",
11797            ));
11798        }
11799    }
11800    Ok(())
11801}
11802
11803#[cfg(test)]
11804#[allow(dead_code)]
11805fn refuse_structural_operation_boundaries(
11806    root: &Path,
11807    operation: &MigrationOperation,
11808) -> Result<()> {
11809    if let MigrationOperation::MoveObject {
11810        source_path,
11811        destination_path,
11812        ..
11813    } = operation
11814    {
11815        ensure_move_content_path(source_path)?;
11816        ensure_move_content_path(destination_path)?;
11817        refuse_tracked_move_path(root, source_path)?;
11818        refuse_tracked_move_path(root, destination_path)?;
11819    }
11820    let source_path = operation
11821        .structural_source_path()
11822        .expect("structural operation has a source");
11823    refuse_nested_folderbase_path(root, source_path)?;
11824    if let Some(destination_path) = operation.structural_destination_path() {
11825        refuse_nested_folderbase_path(root, destination_path)?;
11826    }
11827    Ok(())
11828}
11829
11830fn refuse_structural_operation_boundaries_in(
11831    filesystem: &MigrationFilesystem,
11832    operation: &MigrationOperation,
11833) -> Result<()> {
11834    if let MigrationOperation::MoveObject {
11835        source_path,
11836        destination_path,
11837        ..
11838    } = operation
11839    {
11840        ensure_move_content_path(source_path)?;
11841        ensure_move_content_path(destination_path)?;
11842        refuse_tracked_move_path_in(filesystem, source_path)?;
11843        refuse_tracked_move_path_in(filesystem, destination_path)?;
11844    }
11845    let source_path = operation
11846        .structural_source_path()
11847        .expect("structural operation has a source");
11848    refuse_nested_folderbase_path_in(filesystem, source_path)?;
11849    if let Some(destination_path) = operation.structural_destination_path() {
11850        refuse_nested_folderbase_path_in(filesystem, destination_path)?;
11851    }
11852    Ok(())
11853}
11854
11855fn refuse_tracked_move_path_in(filesystem: &MigrationFilesystem, path: &Path) -> Result<()> {
11856    let objects = Path::new(".folderbase/objects");
11857    let Some(metadata) = filesystem.metadata(objects)? else {
11858        return Ok(());
11859    };
11860    if !metadata.is_dir() || metadata.file_type().is_symlink() {
11861        return Err(FolderbaseError::UnsafePath(filesystem.display(objects)));
11862    }
11863    for name in filesystem.closed_regular_file_names(objects, 65_536)? {
11864        if Path::new(&name)
11865            .extension()
11866            .and_then(|value| value.to_str())
11867            != Some("json")
11868        {
11869            continue;
11870        }
11871        let record_path = objects.join(&name);
11872        let bytes = filesystem.read_regular_bounded(&record_path, MAX_MIGRATION_PLAN_BYTES)?;
11873        let value: serde_json::Value = serde_json::from_slice(&bytes)
11874            .map_err(|source| FolderbaseError::json(filesystem.display(&record_path), source))?;
11875        let Some(stored) = value.get("path").and_then(serde_json::Value::as_str) else {
11876            return Err(invalid_journal(
11877                filesystem.display(&record_path),
11878                "tracked object record is missing its path",
11879            ));
11880        };
11881        let portable_path = portable_migration_wire_path(path)?;
11882        if stored.eq_ignore_ascii_case(&portable_path) {
11883            return Err(FolderbaseError::InvalidRecord {
11884                path: path.to_path_buf(),
11885                message: "ordinary moves cannot relocate a version-tracked object".to_owned(),
11886            });
11887        }
11888    }
11889    Ok(())
11890}
11891
11892fn refuse_tracked_move_path(root: &Path, path: &Path) -> Result<()> {
11893    if LocalVersionStore::open(root)?
11894        .tracked_object_id(path)?
11895        .is_some()
11896    {
11897        return Err(FolderbaseError::InvalidRecord {
11898            path: path.to_path_buf(),
11899            message: "ordinary moves cannot relocate a version-tracked object".to_owned(),
11900        });
11901    }
11902    Ok(())
11903}
11904
11905fn ensure_move_content_path(path: &Path) -> Result<()> {
11906    ensure_safe_relative(path)?;
11907    if path.components().any(|component| {
11908        matches!(component, Component::Normal(name) if is_reserved_workspace_component(name))
11909    }) {
11910        return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
11911    }
11912    if path.parent().is_none()
11913        && path
11914            .file_name()
11915            .and_then(|name| name.to_str())
11916            .is_some_and(|name| {
11917                ["AGENTS.md", "CLAUDE.md", ".folderbaseignore"]
11918                    .iter()
11919                    .any(|reserved| name.eq_ignore_ascii_case(reserved))
11920            })
11921    {
11922        return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
11923    }
11924    Ok(())
11925}
11926
11927#[cfg(test)]
11928#[allow(dead_code)]
11929fn regular_file_digest_if_present(path: &Path) -> Result<Option<String>> {
11930    match fs::symlink_metadata(path) {
11931        Ok(metadata) if metadata.is_file() && !metadata.file_type().is_symlink() => {
11932            sha256_path(path).map(Some)
11933        }
11934        Ok(_) => Ok(None),
11935        Err(source) if source.kind() == std::io::ErrorKind::NotFound => Ok(None),
11936        Err(source) => Err(FolderbaseError::io(path, source)),
11937    }
11938}
11939
11940#[cfg(test)]
11941#[allow(dead_code)]
11942fn rollback_journal(
11943    root: &Path,
11944    journal_path: &Path,
11945    journal: &mut MigrationJournal,
11946) -> Result<RollbackResult> {
11947    if !matches!(
11948        journal.state,
11949        MigrationState::Applying | MigrationState::Verified | MigrationState::RollingBack
11950    ) {
11951        return Err(FolderbaseError::InvalidMigrationState {
11952            expected: MigrationState::Verified.as_str(),
11953            actual: journal.state.as_str().to_owned(),
11954        });
11955    }
11956    reconcile_in_flight(root, journal_path, journal)?;
11957    verify_rollback_paths(root, journal)?;
11958    journal.state = MigrationState::RollingBack;
11959    persist_journal(journal_path, journal)?;
11960    let mut removed_paths = Vec::new();
11961
11962    while let Some(path) = journal.created_paths.last().cloned() {
11963        ensure_safe_relative(&path)?;
11964        let absolute = safe_join(root, &path)?;
11965        match fs::symlink_metadata(&absolute) {
11966            Ok(metadata) if metadata.is_file() && !metadata.file_type().is_symlink() => {
11967                verify_rollback_file(journal, &path, &absolute)?;
11968                fs::remove_file(&absolute)
11969                    .map_err(|source| FolderbaseError::io(&absolute, source))?;
11970                sync_parent(&absolute)?;
11971                removed_paths.push(path.clone());
11972            }
11973            Ok(metadata) if metadata.is_dir() && !metadata.file_type().is_symlink() => {
11974                if fs::read_dir(&absolute)
11975                    .map_err(|source| FolderbaseError::io(&absolute, source))?
11976                    .next()
11977                    .is_none()
11978                {
11979                    fs::remove_dir(&absolute)
11980                        .map_err(|source| FolderbaseError::io(&absolute, source))?;
11981                    sync_parent(&absolute)?;
11982                    removed_paths.push(path.clone());
11983                }
11984            }
11985            Ok(_) => return Err(FolderbaseError::MigrationVerificationFailed(absolute)),
11986            Err(source) if source.kind() == std::io::ErrorKind::NotFound => {}
11987            Err(source) => return Err(FolderbaseError::io(&absolute, source)),
11988        }
11989        journal.created_paths.pop();
11990        persist_journal(journal_path, journal)?;
11991    }
11992
11993    journal.in_flight_operation = None;
11994    journal.state = MigrationState::RolledBack;
11995    persist_journal(journal_path, journal)?;
11996    cleanup_staging(root, &journal.id);
11997    Ok(RollbackResult {
11998        migration_id: journal.id.clone(),
11999        removed_paths,
12000        state: MigrationState::RolledBack,
12001    })
12002}
12003
12004fn rollback_journal_in(
12005    filesystem: &MigrationFilesystem,
12006    journal_path: &Path,
12007    journal: &mut MigrationJournal,
12008) -> Result<RollbackResult> {
12009    if !matches!(
12010        journal.state,
12011        MigrationState::Applying | MigrationState::Verified | MigrationState::RollingBack
12012    ) {
12013        return Err(FolderbaseError::InvalidMigrationState {
12014            expected: MigrationState::Verified.as_str(),
12015            actual: journal.state.as_str().to_owned(),
12016        });
12017    }
12018    reconcile_in_flight_in(filesystem, journal_path, journal)?;
12019    verify_rollback_paths_in(filesystem, journal)?;
12020    journal.state = MigrationState::RollingBack;
12021    persist_journal_in(filesystem, journal)?;
12022    let mut removed_paths = Vec::new();
12023
12024    while let Some(path) = journal.created_paths.last().cloned() {
12025        ensure_safe_relative(&path)?;
12026        match filesystem.metadata(&path)? {
12027            Some(metadata) if metadata.is_file() && !metadata.file_type().is_symlink() => {
12028                verify_rollback_file_in(filesystem, journal, &path)?;
12029                filesystem.remove_file(&path)?;
12030                removed_paths.push(path.clone());
12031            }
12032            Some(metadata) if metadata.is_dir() && !metadata.file_type().is_symlink() => {
12033                if filesystem.remove_empty_directory_if_present(&path)? {
12034                    removed_paths.push(path.clone());
12035                }
12036            }
12037            Some(_) => {
12038                return Err(FolderbaseError::MigrationVerificationFailed(
12039                    filesystem.display(&path),
12040                ));
12041            }
12042            None => {}
12043        }
12044        journal.created_paths.pop();
12045        persist_journal_in(filesystem, journal)?;
12046    }
12047
12048    journal.in_flight_operation = None;
12049    journal.state = MigrationState::RolledBack;
12050    persist_journal_in(filesystem, journal)?;
12051    cleanup_staging_in(filesystem, &journal.id);
12052    Ok(RollbackResult {
12053        migration_id: journal.id.clone(),
12054        removed_paths,
12055        state: MigrationState::RolledBack,
12056    })
12057}
12058
12059#[cfg(test)]
12060#[allow(dead_code)]
12061fn verify_rollback_paths(root: &Path, journal: &MigrationJournal) -> Result<()> {
12062    let approved_boundaries = journal
12063        .materialized_folderbases
12064        .iter()
12065        .map(|materialized| materialized.path.clone())
12066        .collect::<BTreeSet<_>>();
12067    for path in &journal.created_paths {
12068        refuse_unapproved_nested_folderbase_path(root, path, &approved_boundaries)?;
12069        let absolute = safe_join(root, path)?;
12070        match fs::symlink_metadata(&absolute) {
12071            Ok(metadata) if metadata.is_file() && !metadata.file_type().is_symlink() => {
12072                verify_rollback_file(journal, path, &absolute)?;
12073            }
12074            Ok(metadata) if metadata.is_dir() && !metadata.file_type().is_symlink() => {}
12075            Ok(_) => return Err(FolderbaseError::MigrationVerificationFailed(absolute)),
12076            Err(source) if source.kind() == std::io::ErrorKind::NotFound => {}
12077            Err(source) => return Err(FolderbaseError::io(&absolute, source)),
12078        }
12079    }
12080    Ok(())
12081}
12082
12083fn verify_rollback_paths_in(
12084    filesystem: &MigrationFilesystem,
12085    journal: &MigrationJournal,
12086) -> Result<()> {
12087    let approved_boundaries = journal
12088        .materialized_folderbases
12089        .iter()
12090        .map(|materialized| materialized.path.clone())
12091        .collect::<BTreeSet<_>>();
12092    for path in &journal.created_paths {
12093        ensure_safe_relative(path)?;
12094        refuse_unapproved_nested_folderbase_path_in(filesystem, path, &approved_boundaries)?;
12095        match filesystem.metadata(path)? {
12096            Some(metadata) if metadata.is_file() && !metadata.file_type().is_symlink() => {
12097                verify_rollback_file_in(filesystem, journal, path)?;
12098            }
12099            Some(metadata) if metadata.is_dir() && !metadata.file_type().is_symlink() => {}
12100            Some(_) => {
12101                return Err(FolderbaseError::MigrationVerificationFailed(
12102                    filesystem.display(path),
12103                ));
12104            }
12105            None => {}
12106        }
12107    }
12108    Ok(())
12109}
12110
12111fn refuse_unapproved_nested_folderbase_path_in(
12112    filesystem: &MigrationFilesystem,
12113    relative: &Path,
12114    approved_boundaries: &BTreeSet<PathBuf>,
12115) -> Result<()> {
12116    ensure_safe_relative(relative)?;
12117    let mut prefix = PathBuf::new();
12118    for component in relative.components() {
12119        let Component::Normal(component) = component else {
12120            return Err(FolderbaseError::UnsafePath(relative.to_path_buf()));
12121        };
12122        prefix.push(component);
12123        match filesystem.metadata(&prefix)? {
12124            Some(metadata) if metadata.is_dir() && !metadata.file_type().is_symlink() => {
12125                let directory = filesystem.open_directory(&prefix)?;
12126                if classify_nested_folderbase_boundary(&directory, &filesystem.display(&prefix))?
12127                    != NestedFolderbaseBoundaryKind::None
12128                    && !approved_boundaries.contains(&prefix)
12129                {
12130                    return Err(FolderbaseError::UnsafePath(prefix));
12131                }
12132            }
12133            Some(_) if prefix == relative => {}
12134            Some(_) => return Err(FolderbaseError::UnsafePath(prefix)),
12135            None => break,
12136        }
12137    }
12138    Ok(())
12139}
12140
12141#[cfg(test)]
12142#[allow(dead_code)]
12143fn refuse_unapproved_nested_folderbase_path(
12144    root: &Path,
12145    relative: &Path,
12146    approved_boundaries: &BTreeSet<PathBuf>,
12147) -> Result<()> {
12148    ensure_safe_relative(relative)?;
12149    let mut prefix = PathBuf::new();
12150    for component in relative.components() {
12151        let Component::Normal(component) = component else {
12152            return Err(FolderbaseError::UnsafePath(relative.to_path_buf()));
12153        };
12154        prefix.push(component);
12155        let directory = safe_join(root, &prefix)?;
12156        match fs::symlink_metadata(&directory) {
12157            Ok(metadata) if metadata.is_dir() && !metadata.file_type().is_symlink() => {
12158                if migration_nested_folderbase_marker(&directory, &prefix)?
12159                    && !approved_boundaries.contains(&prefix)
12160                {
12161                    return Err(FolderbaseError::UnsafePath(prefix));
12162                }
12163            }
12164            Ok(_) if prefix == relative => {}
12165            Ok(_) => return Err(FolderbaseError::UnsafePath(prefix)),
12166            Err(source) if source.kind() == std::io::ErrorKind::NotFound => break,
12167            Err(source) => return Err(FolderbaseError::io(directory, source)),
12168        }
12169    }
12170    Ok(())
12171}
12172
12173#[cfg(test)]
12174#[allow(dead_code)]
12175fn verify_rollback_file(
12176    journal: &MigrationJournal,
12177    relative: &Path,
12178    absolute: &Path,
12179) -> Result<()> {
12180    let expected = journal
12181        .operations
12182        .iter()
12183        .find_map(|operation| match operation {
12184            MigrationOperation::CopyFile {
12185                destination_path,
12186                expected_sha256,
12187                ..
12188            } if destination_path == relative => Some(expected_sha256),
12189            _ => None,
12190        })
12191        .or_else(|| {
12192            journal
12193                .materialized_folderbases
12194                .iter()
12195                .find_map(|materialized| materialized.created_files.get(relative))
12196        })
12197        .or_else(|| {
12198            journal
12199                .materialized_workspace
12200                .as_ref()
12201                .and_then(|workspace| workspace.created_files.get(relative))
12202        });
12203    match expected {
12204        Some(expected) if sha256_path(absolute)? == *expected => Ok(()),
12205        _ => Err(FolderbaseError::MigrationVerificationFailed(
12206            absolute.to_path_buf(),
12207        )),
12208    }
12209}
12210
12211fn verify_rollback_file_in(
12212    filesystem: &MigrationFilesystem,
12213    journal: &MigrationJournal,
12214    relative: &Path,
12215) -> Result<()> {
12216    let expected = journal
12217        .operations
12218        .iter()
12219        .find_map(|operation| match operation {
12220            MigrationOperation::CopyFile {
12221                destination_path,
12222                expected_sha256,
12223                ..
12224            } if destination_path == relative => Some(expected_sha256),
12225            _ => None,
12226        })
12227        .or_else(|| {
12228            journal
12229                .materialized_folderbases
12230                .iter()
12231                .find_map(|materialized| materialized.created_files.get(relative))
12232        })
12233        .or_else(|| {
12234            journal
12235                .materialized_workspace
12236                .as_ref()
12237                .and_then(|workspace| workspace.created_files.get(relative))
12238        });
12239    match expected {
12240        Some(expected) if filesystem.sha256_regular(relative)? == *expected => Ok(()),
12241        _ => Err(FolderbaseError::MigrationVerificationFailed(
12242            filesystem.display(relative),
12243        )),
12244    }
12245}
12246
12247fn result_from_journal(
12248    root: PathBuf,
12249    journal_absolute: PathBuf,
12250    journal: &MigrationJournal,
12251) -> MigrationResult {
12252    let journal_path = journal_absolute
12253        .strip_prefix(&root)
12254        .unwrap_or(&journal_absolute)
12255        .to_path_buf();
12256    MigrationResult {
12257        migration_id: journal.id.clone(),
12258        root,
12259        state: journal.state,
12260        created_paths: journal.created_paths.clone(),
12261        journal_path,
12262    }
12263}
12264
12265fn invalid_journal(path: impl Into<PathBuf>, message: impl Into<String>) -> FolderbaseError {
12266    FolderbaseError::InvalidRecord {
12267        path: path.into(),
12268        message: message.into(),
12269    }
12270}
12271
12272fn validate_migration_id(root: &Path, migration_id: &str) -> Result<()> {
12273    ensure_safe_relative(Path::new(migration_id))?;
12274    if !migration_id.starts_with("migration_") {
12275        return Err(invalid_journal(
12276            root,
12277            "migration ID must start with `migration_`",
12278        ));
12279    }
12280    Ok(())
12281}
12282
12283fn migration_plan_relative(migration_id: &str) -> PathBuf {
12284    PathBuf::from(MIGRATIONS_DIR)
12285        .join(migration_id)
12286        .join("plan.json")
12287}
12288
12289fn persist_new_plan(plan: &MigrationPlan) -> Result<()> {
12290    validate_plan(&plan.root, &plan.id, Path::new("plan.json"), plan)?;
12291    let state_dir = safe_join(&plan.root, Path::new(STATE_DIR))?;
12292    create_private_directory_if_missing(&state_dir)?;
12293    let migrations_dir = safe_join(&plan.root, Path::new(MIGRATIONS_DIR))?;
12294    create_private_directory_if_missing(&migrations_dir)?;
12295    let migration_dir = safe_join(&plan.root, &PathBuf::from(MIGRATIONS_DIR).join(&plan.id))?;
12296    create_private_directory_new(&migration_dir)?;
12297    sync_parent(&migration_dir)?;
12298    write_json_new(&migration_dir.join("plan.json"), plan)
12299}
12300
12301#[cfg(test)]
12302#[allow(dead_code)]
12303fn persist_plan_transition(
12304    root: &Path,
12305    migration_id: &str,
12306    expected: &[MigrationState],
12307    next: MigrationState,
12308) -> Result<()> {
12309    let mut plan = load_plan(root, migration_id)?;
12310    if !expected.contains(&plan.state) {
12311        return Err(FolderbaseError::InvalidMigrationState {
12312            expected: expected.first().copied().unwrap_or(next).as_str(),
12313            actual: plan.state.as_str().to_owned(),
12314        });
12315    }
12316    plan.state = next;
12317    persist_plan(&plan)
12318}
12319
12320fn persist_plan_transition_in(
12321    filesystem: &MigrationFilesystem,
12322    migration_id: &str,
12323    expected: &[MigrationState],
12324    next: MigrationState,
12325) -> Result<()> {
12326    let mut plan = load_plan_from(filesystem, migration_id)?;
12327    if !expected.contains(&plan.state) {
12328        return Err(FolderbaseError::InvalidMigrationState {
12329            expected: expected.first().copied().unwrap_or(next).as_str(),
12330            actual: plan.state.as_str().to_owned(),
12331        });
12332    }
12333    plan.state = next;
12334    persist_plan_in(filesystem, &plan)
12335}
12336
12337fn load_plan(root: &Path, migration_id: &str) -> Result<MigrationPlan> {
12338    validate_migration_id(root, migration_id)?;
12339    let plan_path = safe_join(root, &migration_plan_relative(migration_id))?;
12340    let metadata = fs::symlink_metadata(&plan_path)
12341        .map_err(|source| FolderbaseError::io(&plan_path, source))?;
12342    if !metadata.is_file()
12343        || metadata.file_type().is_symlink()
12344        || metadata.len() > MAX_MIGRATION_PLAN_BYTES
12345    {
12346        return Err(invalid_journal(
12347            &plan_path,
12348            "migration plan must be a bounded regular file",
12349        ));
12350    }
12351    let bytes = fs::read(&plan_path).map_err(|source| FolderbaseError::io(&plan_path, source))?;
12352    let mut plan: MigrationPlan = serde_json::from_slice(&bytes)
12353        .map_err(|source| FolderbaseError::json(&plan_path, source))?;
12354    validate_plan(root, migration_id, &plan_path, &plan)?;
12355    plan.root_identity = Some(
12356        RetainedPhysicalIdentity::from_path(root)
12357            .map_err(|source| FolderbaseError::io(root, source))?,
12358    );
12359    Ok(plan)
12360}
12361
12362fn load_plan_from(filesystem: &MigrationFilesystem, migration_id: &str) -> Result<MigrationPlan> {
12363    let root = filesystem.display_root();
12364    validate_migration_id(root, migration_id)?;
12365    let plan_relative = migration_plan_relative(migration_id);
12366    let plan_path = filesystem.display(&plan_relative);
12367    let bytes = filesystem.read_regular_bounded(&plan_relative, MAX_MIGRATION_PLAN_BYTES)?;
12368    let plan: MigrationPlan = serde_json::from_slice(&bytes)
12369        .map_err(|source| FolderbaseError::json(&plan_path, source))?;
12370    validate_plan(root, migration_id, &plan_path, &plan)?;
12371    Ok(plan)
12372}
12373
12374fn validate_plan(
12375    root: &Path,
12376    migration_id: &str,
12377    plan_path: &Path,
12378    plan: &MigrationPlan,
12379) -> Result<()> {
12380    if plan.protocol_version != "0.2.0"
12381        || plan.id != migration_id
12382        || plan.root != root
12383        || plan.source_inventory.algorithm != "sha256"
12384        || inventory_digest(&plan.source_inventory.files)? != plan.source_inventory.digest
12385        || !matches!(
12386            plan.state,
12387            MigrationState::Proposed
12388                | MigrationState::Approved
12389                | MigrationState::Applying
12390                | MigrationState::Verified
12391                | MigrationState::Conflicted
12392                | MigrationState::Rejected
12393                | MigrationState::RolledBack
12394        )
12395    {
12396        return Err(invalid_journal(
12397            plan_path,
12398            "migration plan metadata is inconsistent",
12399        ));
12400    }
12401    let approval_metadata_is_consistent = match plan.state {
12402        MigrationState::Proposed | MigrationState::Rejected => plan.approval_digest.is_none(),
12403        MigrationState::Approved
12404        | MigrationState::Applying
12405        | MigrationState::Verified
12406        | MigrationState::Conflicted
12407        | MigrationState::RolledBack => plan.approval_digest.is_some(),
12408        MigrationState::Analyzing | MigrationState::Questions | MigrationState::RollingBack => {
12409            false
12410        }
12411    };
12412    if !approval_metadata_is_consistent {
12413        return Err(invalid_journal(
12414            plan_path,
12415            "migration plan approval metadata is inconsistent with its state",
12416        ));
12417    }
12418    if let Some(approval_digest) = &plan.approval_digest
12419        && plan_digest(plan)? != *approval_digest
12420    {
12421        return Err(FolderbaseError::MigrationApprovalMismatch);
12422    }
12423    validate_grouped_assignments_extension(plan_path, plan)?;
12424    validate_expanded_reconstructable_trees_extension(plan_path, plan)?;
12425    for source in &plan.source_inventory.files {
12426        ensure_safe_relative(&source.path)?;
12427    }
12428    for operation in &plan.operations {
12429        match operation {
12430            MigrationOperation::CreateFolder { path } => ensure_safe_relative(path)?,
12431            MigrationOperation::CopyFile {
12432                source_path,
12433                destination_path,
12434                expected_sha256,
12435            } => {
12436                ensure_safe_relative(source_path)?;
12437                ensure_safe_relative(destination_path)?;
12438                if !plan
12439                    .source_inventory
12440                    .files
12441                    .iter()
12442                    .any(|source| source.path == *source_path && source.sha256 == *expected_sha256)
12443                {
12444                    return Err(invalid_journal(
12445                        plan_path,
12446                        "copy operation is not bound to the source inventory",
12447                    ));
12448                }
12449            }
12450            operation if operation.is_structural() => {
12451                let source_path = operation
12452                    .structural_source_path()
12453                    .expect("structural operation has a source");
12454                ensure_safe_relative(source_path)?;
12455                refuse_nested_folderbase_path(root, source_path)?;
12456                let expected = operation
12457                    .structural_expected_sha256()
12458                    .filter(|digest| is_sha256(digest))
12459                    .ok_or_else(|| {
12460                        invalid_journal(plan_path, "structural source digest is invalid")
12461                    })?;
12462                if !plan
12463                    .source_inventory
12464                    .files
12465                    .iter()
12466                    .any(|source| source.path == source_path && source.sha256 == expected)
12467                {
12468                    return Err(invalid_journal(
12469                        plan_path,
12470                        "structural operation is not bound to the source inventory",
12471                    ));
12472                }
12473                if let Some(destination) = operation.structural_destination_path() {
12474                    ensure_safe_relative(destination)?;
12475                    refuse_nested_folderbase_path(root, destination)?;
12476                } else if !operation
12477                    .structural_expected_result_sha256()
12478                    .is_some_and(is_sha256)
12479                {
12480                    return Err(invalid_journal(
12481                        plan_path,
12482                        "structural result digest is invalid",
12483                    ));
12484                }
12485                match operation.structural_snapshot() {
12486                    Some((snapshot_path, snapshot_sha256)) => {
12487                        ensure_safe_relative(snapshot_path)?;
12488                        if !is_sha256(snapshot_sha256) || snapshot_sha256 != expected {
12489                            return Err(invalid_journal(
12490                                plan_path,
12491                                "structural snapshot metadata is invalid",
12492                            ));
12493                        }
12494                    }
12495                    None if plan.state != MigrationState::Proposed => {
12496                        return Err(invalid_journal(
12497                            plan_path,
12498                            "approved structural operation requires a verified snapshot",
12499                        ));
12500                    }
12501                    None => {}
12502                }
12503            }
12504            _ => {
12505                return Err(invalid_journal(
12506                    plan_path,
12507                    "migration operation kind is invalid",
12508                ));
12509            }
12510        }
12511    }
12512    Ok(())
12513}
12514
12515fn validate_grouped_assignments_extension(plan_path: &Path, plan: &MigrationPlan) -> Result<()> {
12516    let grouped_answers = plan
12517        .answers
12518        .iter()
12519        .filter(|answer| answer.question_id.starts_with("question_assignment_group_"))
12520        .collect::<Vec<_>>();
12521    if plan.answers.iter().any(|answer| {
12522        !answer.question_id.starts_with("question_assignment_group_")
12523            && !answer.exceptions.is_empty()
12524    }) {
12525        return Err(invalid_journal(
12526            plan_path,
12527            "only grouped migration answers may contain exceptions",
12528        ));
12529    }
12530    let Some(value) = plan.extensions.get(GROUPED_ASSIGNMENTS_EXTENSION) else {
12531        if grouped_answers.is_empty() {
12532            if plan
12533                .answers
12534                .iter()
12535                .any(|answer| !answer.exceptions.is_empty())
12536            {
12537                return Err(invalid_journal(
12538                    plan_path,
12539                    "only grouped migration answers may contain exceptions",
12540                ));
12541            }
12542            return Ok(());
12543        }
12544        return Err(invalid_journal(
12545            plan_path,
12546            "grouped migration answers require their normalized contract extension",
12547        ));
12548    };
12549    if grouped_answers.is_empty() {
12550        return Err(invalid_journal(
12551            plan_path,
12552            "grouped migration contract has no corresponding answers",
12553        ));
12554    }
12555    let contract: GroupedAssignmentsExtension = serde_json::from_value(value.clone())
12556        .map_err(|_| invalid_journal(plan_path, "grouped migration contract is invalid"))?;
12557    if contract.version != "1" || contract.groups.len() != grouped_answers.len() {
12558        return Err(invalid_journal(
12559            plan_path,
12560            "grouped migration contract version or coverage is invalid",
12561        ));
12562    }
12563
12564    let one_folderbase = plan.answers.iter().any(|answer| {
12565        answer.question_id == "question_canonical_scope" && answer.answer == "one_folderbase"
12566    });
12567    let exclude_generated = plan.answers.iter().any(|answer| {
12568        answer.question_id == "question_generated_content" && answer.answer == "exclude_generated"
12569    });
12570    let mut question_ids = BTreeSet::new();
12571    let mut member_keys = BTreeSet::new();
12572    let source_topology_value =
12573        plan.extensions
12574            .get(SOURCE_TOPOLOGY_EXTENSION)
12575            .ok_or_else(|| {
12576                invalid_journal(
12577                    plan_path,
12578                    "grouped migration contract requires a source-topology snapshot",
12579                )
12580            })?;
12581    let source_topology: SourceTopologySnapshot =
12582        serde_json::from_value(source_topology_value.clone())
12583            .map_err(|_| invalid_journal(plan_path, "source-topology snapshot is invalid"))?;
12584    if source_topology.version != "1" {
12585        return Err(invalid_journal(
12586            plan_path,
12587            "source-topology snapshot version is unsupported",
12588        ));
12589    }
12590    let expected_members = source_topology
12591        .files
12592        .into_iter()
12593        .map(|path| (path, AssignmentSourceKind::File))
12594        .chain(
12595            source_topology
12596                .reconstructable_trees
12597                .into_iter()
12598                .map(|path| (path, AssignmentSourceKind::ReconstructableTree)),
12599        )
12600        .collect::<BTreeMap<_, _>>();
12601    let mut contract_members = BTreeMap::new();
12602    for group in &contract.groups {
12603        if group.rule_version != ASSIGNMENT_GROUP_RULE_VERSION
12604            || group.members.is_empty()
12605            || !question_ids.insert(group.question_id.as_str())
12606        {
12607            return Err(invalid_journal(
12608                plan_path,
12609                "grouped migration contract contains an unsupported or duplicate group",
12610            ));
12611        }
12612        if group.source_root != Path::new(".") {
12613            ensure_safe_relative(&group.source_root)?;
12614        }
12615        let mut members = Vec::with_capacity(group.members.len());
12616        let mut previous_path: Option<&Path> = None;
12617        for member in &group.members {
12618            ensure_safe_relative(&member.source_path)?;
12619            if previous_path.is_some_and(|previous| previous >= member.source_path.as_path())
12620                || assignment_source_root(&member.source_path, member.source_kind)
12621                    != group.source_root
12622                || !member_keys.insert(portable_path_key(&member.source_path))
12623            {
12624                return Err(invalid_journal(
12625                    plan_path,
12626                    "grouped migration members must be sorted, exact, and portable-case unique",
12627                ));
12628            }
12629            previous_path = Some(&member.source_path);
12630            if contract_members
12631                .insert(member.source_path.clone(), member.source_kind)
12632                .is_some()
12633            {
12634                return Err(invalid_journal(
12635                    plan_path,
12636                    "grouped migration member appears more than once",
12637                ));
12638            }
12639            members.push(AssignmentGroupMember {
12640                path: member.source_path.clone(),
12641                kind: member.source_kind,
12642            });
12643        }
12644        let digest =
12645            assignment_group_coverage_digest(&group.source_root, group.content_kind, &members)?;
12646        if group.coverage_digest != digest
12647            || group.question_id != format!("question_assignment_group_{digest}")
12648        {
12649            return Err(invalid_journal(
12650                plan_path,
12651                "grouped migration coverage digest is invalid",
12652            ));
12653        }
12654        let answer = grouped_answers
12655            .iter()
12656            .find(|answer| answer.question_id == group.question_id)
12657            .ok_or_else(|| {
12658                invalid_journal(
12659                    plan_path,
12660                    "grouped migration contract does not match its answer",
12661                )
12662            })?;
12663        let mut normalized_exceptions = answer.exceptions.clone();
12664        normalized_exceptions.sort_by(|left, right| {
12665            portable_path_key(&left.source_path).cmp(&portable_path_key(&right.source_path))
12666        });
12667        if answer.answer != group.default_target_id || normalized_exceptions != group.exceptions {
12668            return Err(invalid_journal(
12669                plan_path,
12670                "grouped migration defaults or exceptions are inconsistent",
12671            ));
12672        }
12673        validate_group_target(
12674            plan_path,
12675            plan,
12676            group.content_kind,
12677            &group.default_target_id,
12678            one_folderbase,
12679            exclude_generated,
12680        )?;
12681        let member_paths = group
12682            .members
12683            .iter()
12684            .map(|member| member.source_path.as_path())
12685            .collect::<BTreeSet<_>>();
12686        let mut exception_keys = BTreeSet::new();
12687        for exception in &group.exceptions {
12688            ensure_safe_relative(&exception.source_path)?;
12689            if !member_paths.contains(exception.source_path.as_path())
12690                || !exception_keys.insert(portable_path_key(&exception.source_path))
12691            {
12692                return Err(invalid_journal(
12693                    plan_path,
12694                    "grouped migration exception is duplicate or not an exact member",
12695                ));
12696            }
12697            validate_group_target(
12698                plan_path,
12699                plan,
12700                group.content_kind,
12701                &exception.target_id,
12702                one_folderbase,
12703                exclude_generated,
12704            )?;
12705        }
12706    }
12707    if question_ids
12708        != grouped_answers
12709            .iter()
12710            .map(|answer| answer.question_id.as_str())
12711            .collect()
12712    {
12713        return Err(invalid_journal(
12714            plan_path,
12715            "grouped migration answers and contract records must correspond exactly once",
12716        ));
12717    }
12718    if contract_members != expected_members {
12719        return Err(invalid_journal(
12720            plan_path,
12721            "grouped migration members do not match the approved source topology",
12722        ));
12723    }
12724    Ok(())
12725}
12726
12727fn validate_group_target(
12728    plan_path: &Path,
12729    plan: &MigrationPlan,
12730    content_kind: MigrationContentKind,
12731    target_id: &str,
12732    one_folderbase: bool,
12733    exclude_generated: bool,
12734) -> Result<()> {
12735    let target = plan
12736        .targets
12737        .iter()
12738        .find(|target| target.id == target_id)
12739        .ok_or_else(|| invalid_journal(plan_path, "grouped migration target is unknown"))?;
12740    let allowed = match content_kind {
12741        MigrationContentKind::Canonical => matches!(
12742            target.kind,
12743            MigrationTargetKind::Folderbase | MigrationTargetKind::RetainedFolder
12744        ),
12745        MigrationContentKind::Generated | MigrationContentKind::Temporary => matches!(
12746            target.kind,
12747            MigrationTargetKind::Folderbase
12748                | MigrationTargetKind::RetainedFolder
12749                | MigrationTargetKind::Exclusion
12750        ),
12751        MigrationContentKind::SecretShaped => target.kind == MigrationTargetKind::RetainedFolder,
12752    };
12753    if !allowed
12754        || (one_folderbase
12755            && target.kind == MigrationTargetKind::Folderbase
12756            && target.id != "target_primary_folderbase")
12757        || (content_kind == MigrationContentKind::Generated
12758            && exclude_generated
12759            && target.kind == MigrationTargetKind::Folderbase)
12760    {
12761        return Err(invalid_journal(
12762            plan_path,
12763            "grouped migration target is not allowed for this content",
12764        ));
12765    }
12766    Ok(())
12767}
12768
12769fn validate_expanded_reconstructable_trees_extension(
12770    plan_path: &Path,
12771    plan: &MigrationPlan,
12772) -> Result<()> {
12773    let Some(source_topology_value) = plan.extensions.get(SOURCE_TOPOLOGY_EXTENSION) else {
12774        if plan
12775            .extensions
12776            .contains_key(EXPANDED_RECONSTRUCTABLE_TREES_EXTENSION)
12777        {
12778            return Err(invalid_journal(
12779                plan_path,
12780                "expanded reconstructable trees require a source-topology snapshot",
12781            ));
12782        }
12783        return Ok(());
12784    };
12785    let source_topology: SourceTopologySnapshot =
12786        serde_json::from_value(source_topology_value.clone())
12787            .map_err(|_| invalid_journal(plan_path, "source-topology snapshot is invalid"))?;
12788    let required_roots =
12789        required_expanded_reconstructable_roots(plan_path, plan, &source_topology)?;
12790    let Some(value) = plan
12791        .extensions
12792        .get(EXPANDED_RECONSTRUCTABLE_TREES_EXTENSION)
12793    else {
12794        if required_roots.is_empty() {
12795            return Ok(());
12796        }
12797        return Err(invalid_journal(
12798            plan_path,
12799            "included reconstructable trees require exact expanded membership",
12800        ));
12801    };
12802    let contract: ExpandedReconstructableTreesExtension = serde_json::from_value(value.clone())
12803        .map_err(|_| {
12804            invalid_journal(
12805                plan_path,
12806                "expanded reconstructable-tree contract is invalid",
12807            )
12808        })?;
12809    if contract.version != "1" || contract.trees.is_empty() {
12810        return Err(invalid_journal(
12811            plan_path,
12812            "expanded reconstructable-tree contract version or coverage is invalid",
12813        ));
12814    }
12815    let reconstructable_roots = source_topology
12816        .reconstructable_trees
12817        .iter()
12818        .map(|path| portable_path_key(path))
12819        .collect::<BTreeSet<_>>();
12820    let mut tree_root_keys = BTreeSet::new();
12821    let mut tree_roots = BTreeSet::new();
12822    for tree in contract.trees {
12823        ensure_safe_relative(&tree.source_root)?;
12824        if !tree_root_keys.insert(portable_path_key(&tree.source_root))
12825            || !tree_roots.insert(tree.source_root.clone())
12826            || !reconstructable_roots.contains(&portable_path_key(&tree.source_root))
12827            || tree.source_paths.windows(2).any(|pair| pair[0] >= pair[1])
12828        {
12829            return Err(invalid_journal(
12830                plan_path,
12831                "expanded reconstructable-tree members must be sorted with unique source roots",
12832            ));
12833        }
12834        let mut source_path_keys = BTreeSet::new();
12835        for source_path in tree.source_paths {
12836            ensure_safe_relative(&source_path)?;
12837            if !source_path.starts_with(&tree.source_root)
12838                || !source_path_keys.insert(portable_path_key(&source_path))
12839                || !plan
12840                    .source_inventory
12841                    .files
12842                    .iter()
12843                    .any(|source| source.path == source_path)
12844            {
12845                return Err(invalid_journal(
12846                    plan_path,
12847                    "expanded reconstructable-tree member is not source-inventory bound",
12848                ));
12849            }
12850        }
12851    }
12852    if tree_roots != required_roots {
12853        return Err(invalid_journal(
12854            plan_path,
12855            "expanded reconstructable-tree coverage does not match included tree assignments",
12856        ));
12857    }
12858    Ok(())
12859}
12860
12861fn required_expanded_reconstructable_roots(
12862    plan_path: &Path,
12863    plan: &MigrationPlan,
12864    source_topology: &SourceTopologySnapshot,
12865) -> Result<BTreeSet<PathBuf>> {
12866    let target_is_folderbase = |target_id: &str| {
12867        plan.targets
12868            .iter()
12869            .find(|target| target.id == target_id)
12870            .map(|target| target.kind == MigrationTargetKind::Folderbase)
12871            .ok_or_else(|| invalid_journal(plan_path, "migration assignment target is unknown"))
12872    };
12873    let mut required = BTreeSet::new();
12874    if let Some(value) = plan.extensions.get(GROUPED_ASSIGNMENTS_EXTENSION) {
12875        let grouped: GroupedAssignmentsExtension = serde_json::from_value(value.clone())
12876            .map_err(|_| invalid_journal(plan_path, "grouped migration contract is invalid"))?;
12877        for group in grouped.groups {
12878            for member in group
12879                .members
12880                .iter()
12881                .filter(|member| member.source_kind == AssignmentSourceKind::ReconstructableTree)
12882            {
12883                let target_id = group
12884                    .exceptions
12885                    .iter()
12886                    .find(|exception| exception.source_path == member.source_path)
12887                    .map(|exception| exception.target_id.as_str())
12888                    .unwrap_or(&group.default_target_id);
12889                if target_is_folderbase(target_id)? {
12890                    required.insert(member.source_path.clone());
12891                }
12892            }
12893        }
12894        return Ok(required);
12895    }
12896
12897    for source_root in &source_topology.reconstructable_trees {
12898        let question_id = stable_path_id("question_assignment", source_root)?;
12899        let answer = plan
12900            .answers
12901            .iter()
12902            .find(|answer| answer.question_id == question_id)
12903            .ok_or_else(|| {
12904                invalid_journal(
12905                    plan_path,
12906                    "reconstructable tree is missing its exact assignment answer",
12907                )
12908            })?;
12909        if target_is_folderbase(&answer.answer)? {
12910            required.insert(source_root.clone());
12911        }
12912    }
12913    Ok(required)
12914}
12915
12916fn canonical_root_with_identity_with_hook(
12917    path: &Path,
12918    after_initial_nofollow_open: impl FnOnce(),
12919) -> Result<(PathBuf, RetainedPhysicalIdentity)> {
12920    let retained = match RetainedPhysicalIdentity::from_path(path) {
12921        Ok(retained) => retained,
12922        Err(source) => {
12923            if fs::symlink_metadata(path)
12924                .is_ok_and(|metadata| metadata_is_link_or_reparse(&metadata))
12925            {
12926                return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
12927            }
12928            return Err(FolderbaseError::io(path, source));
12929        }
12930    };
12931    let retained_metadata = retained
12932        .metadata()
12933        .map_err(|source| FolderbaseError::io(path, source))?;
12934    if metadata_is_link_or_reparse(&retained_metadata) {
12935        return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
12936    }
12937    if !retained_metadata.is_dir() {
12938        return Err(FolderbaseError::InvalidRoot(path.to_path_buf()));
12939    }
12940    after_initial_nofollow_open();
12941    let canonical = path
12942        .canonicalize()
12943        .map_err(|source| FolderbaseError::io(path, source))?;
12944    let canonical_retained = RetainedPhysicalIdentity::from_path(&canonical)
12945        .map_err(|source| FolderbaseError::io(&canonical, source))?;
12946    let canonical_metadata = canonical_retained
12947        .metadata()
12948        .map_err(|source| FolderbaseError::io(&canonical, source))?;
12949    if metadata_is_link_or_reparse(&canonical_metadata)
12950        || !canonical_metadata.is_dir()
12951        || canonical_retained.identity() != retained.identity()
12952    {
12953        return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
12954    }
12955    let display_root = caller_visible_canonical_path(path, canonical)
12956        .map_err(|source| FolderbaseError::io(path, source))?;
12957    Ok((display_root, retained))
12958}
12959
12960#[cfg(not(windows))]
12961fn caller_visible_canonical_path(
12962    _caller_path: &Path,
12963    canonical: PathBuf,
12964) -> std::io::Result<PathBuf> {
12965    Ok(canonical)
12966}
12967
12968#[cfg(windows)]
12969fn caller_visible_canonical_path(
12970    caller_path: &Path,
12971    _canonical: PathBuf,
12972) -> std::io::Result<PathBuf> {
12973    std::path::absolute(caller_path)
12974}
12975
12976fn canonical_root_with_identity(path: &Path) -> Result<(PathBuf, RetainedPhysicalIdentity)> {
12977    canonical_root_with_identity_with_hook(path, || {})
12978}
12979
12980fn canonical_root(path: &Path) -> Result<PathBuf> {
12981    canonical_root_with_identity(path).map(|(canonical, _retained)| canonical)
12982}
12983
12984fn ensure_safe_relative(path: &Path) -> Result<()> {
12985    if path.as_os_str().is_empty()
12986        || path.is_absolute()
12987        || path
12988            .components()
12989            .any(|component| !matches!(component, Component::Normal(_)))
12990    {
12991        return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
12992    }
12993    Ok(())
12994}
12995
12996fn safe_join(root: &Path, relative: &Path) -> Result<PathBuf> {
12997    ensure_safe_relative(relative)?;
12998    let destination = root.join(relative);
12999    let mut current = root.to_path_buf();
13000    if let Some(parent) = relative.parent() {
13001        for component in parent.components() {
13002            let Component::Normal(component) = component else {
13003                return Err(FolderbaseError::UnsafePath(relative.to_path_buf()));
13004            };
13005            current.push(component);
13006            if let Ok(metadata) = fs::symlink_metadata(&current)
13007                && metadata.file_type().is_symlink()
13008            {
13009                return Err(FolderbaseError::UnsafePath(current));
13010            }
13011        }
13012    }
13013    Ok(destination)
13014}
13015
13016fn refuse_nested_folderbase_path(root: &Path, relative: &Path) -> Result<()> {
13017    ensure_safe_relative(relative)?;
13018    let mut prefix = PathBuf::new();
13019    for component in relative.parent().into_iter().flat_map(Path::components) {
13020        let Component::Normal(component) = component else {
13021            return Err(FolderbaseError::UnsafePath(relative.to_path_buf()));
13022        };
13023        prefix.push(component);
13024        let directory = safe_join(root, &prefix)?;
13025        match fs::symlink_metadata(&directory) {
13026            Ok(metadata) if metadata.is_dir() && !metadata.file_type().is_symlink() => {
13027                if migration_nested_folderbase_marker(&directory, &prefix)? {
13028                    return Err(FolderbaseError::UnsafePath(prefix));
13029                }
13030            }
13031            Ok(_) => return Err(FolderbaseError::UnsafePath(prefix)),
13032            Err(source) if source.kind() == std::io::ErrorKind::NotFound => {}
13033            Err(source) => return Err(FolderbaseError::io(directory, source)),
13034        }
13035    }
13036    Ok(())
13037}
13038
13039fn migration_nested_folderbase_marker(directory: &Path, prefix: &Path) -> Result<bool> {
13040    has_nested_folderbase_marker(directory).map_err(|error| match error {
13041        FolderbaseError::UnsafePath(_) => FolderbaseError::UnsafePath(prefix.to_path_buf()),
13042        error => error,
13043    })
13044}
13045
13046fn humanize_name(name: &str) -> String {
13047    name.replace(['-', '_'], " ")
13048        .split_whitespace()
13049        .map(|word| {
13050            let mut chars = word.chars();
13051            chars
13052                .next()
13053                .map(|first| first.to_uppercase().collect::<String>() + chars.as_str())
13054                .unwrap_or_default()
13055        })
13056        .collect::<Vec<_>>()
13057        .join(" ")
13058}
13059
13060fn portable_migration_wire_path(path: &Path) -> Result<String> {
13061    crate::portable_wire_path::relative_to_wire(path).map_err(|message| {
13062        FolderbaseError::InvalidRecord {
13063            path: path.to_path_buf(),
13064            message: message.to_owned(),
13065        }
13066    })
13067}
13068
13069fn portable_migration_wire_scope(path: &Path) -> Result<String> {
13070    if path == Path::new(".") {
13071        Ok(".".to_owned())
13072    } else {
13073        portable_migration_wire_path(path)
13074    }
13075}
13076
13077fn stable_path_id(prefix: &str, path: &Path) -> Result<String> {
13078    let portable = portable_migration_wire_path(path)?;
13079    let digest = Sha256::digest(portable.as_bytes());
13080    Ok(format!("{prefix}_{digest:x}"))
13081}
13082
13083fn portable_path_key(path: &Path) -> PathBuf {
13084    path.components()
13085        .map(|component| match component {
13086            Component::Normal(name) => name
13087                .to_string_lossy()
13088                .case_fold()
13089                .collect::<String>()
13090                .into(),
13091            _ => component.as_os_str().to_owned(),
13092        })
13093        .collect()
13094}
13095
13096fn target_kind_for_boundary(path: &Path) -> MigrationTargetKind {
13097    let name = path
13098        .file_name()
13099        .and_then(|name| name.to_str())
13100        .unwrap_or_default()
13101        .to_ascii_lowercase()
13102        .replace(['_', ' '], "-");
13103    if name.contains("workspace") {
13104        MigrationTargetKind::Workspace
13105    } else if name.contains("shared")
13106        && (name.contains("client")
13107            || name.contains("customer")
13108            || name.contains("external")
13109            || name == "shared")
13110    {
13111        MigrationTargetKind::ScopedView
13112    } else {
13113        MigrationTargetKind::Folderbase
13114    }
13115}
13116
13117fn assignment_questions(
13118    files: &[AnalyzedFile],
13119    reconstructable_trees: &[ReconstructableTree],
13120    targets: &[MigrationTarget],
13121) -> Result<Vec<MigrationQuestion>> {
13122    let mut assignments = files
13123        .iter()
13124        .map(|file| {
13125            let content_kind = if file.is_secret_shaped() {
13126                MigrationContentKind::SecretShaped
13127            } else if file.is_temporary() {
13128                MigrationContentKind::Temporary
13129            } else if file.is_generated() {
13130                MigrationContentKind::Generated
13131            } else {
13132                MigrationContentKind::Canonical
13133            };
13134            (file.path.clone(), content_kind, AssignmentSourceKind::File)
13135        })
13136        .chain(reconstructable_trees.iter().map(|tree| {
13137            (
13138                tree.path.clone(),
13139                MigrationContentKind::Generated,
13140                AssignmentSourceKind::ReconstructableTree,
13141            )
13142        }))
13143        .collect::<Vec<_>>();
13144    if assignments.len() <= GROUPED_ASSIGNMENT_THRESHOLD {
13145        return assignments
13146            .into_iter()
13147            .map(|(path, content_kind, _)| assignment_question(&path, content_kind, targets))
13148            .collect();
13149    }
13150
13151    let mut groups = BTreeMap::<(PathBuf, MigrationContentKind), Vec<AssignmentGroupMember>>::new();
13152    for (path, content_kind, source_kind) in assignments.drain(..) {
13153        let source_root = assignment_source_root(&path, source_kind);
13154        groups
13155            .entry((source_root, content_kind))
13156            .or_default()
13157            .push(AssignmentGroupMember {
13158                path,
13159                kind: source_kind,
13160            });
13161    }
13162
13163    groups
13164        .into_iter()
13165        .map(|((source_root, content_kind), mut members)| {
13166            members.sort_by(|left, right| left.path.cmp(&right.path));
13167            assignment_group_question(&source_root, members, content_kind, targets)
13168        })
13169        .collect()
13170}
13171
13172fn assignment_source_root(path: &Path, source_kind: AssignmentSourceKind) -> PathBuf {
13173    if source_kind == AssignmentSourceKind::ReconstructableTree
13174        || path
13175            .parent()
13176            .is_some_and(|parent| !parent.as_os_str().is_empty())
13177    {
13178        path.components()
13179            .next()
13180            .map(|component| PathBuf::from(component.as_os_str()))
13181            .unwrap_or_else(|| PathBuf::from("."))
13182    } else {
13183        PathBuf::from(".")
13184    }
13185}
13186
13187fn assignment_group_question(
13188    source_root: &Path,
13189    members: Vec<AssignmentGroupMember>,
13190    content_kind: MigrationContentKind,
13191    targets: &[MigrationTarget],
13192) -> Result<MigrationQuestion> {
13193    let coverage_digest = assignment_group_coverage_digest(source_root, content_kind, &members)?;
13194    let source_paths = members
13195        .into_iter()
13196        .map(|member| member.path)
13197        .collect::<Vec<_>>();
13198    let mut question = assignment_question(&source_paths[0], content_kind, targets)?;
13199    question.id = format!("question_assignment_group_{coverage_digest}");
13200    question.prompt = format!(
13201        "Choose an explicit destination for {} grouped items under `{}`.",
13202        source_paths.len(),
13203        source_root.display()
13204    );
13205    question.context = "The group is metadata-derived and lists every covered source path explicitly. Workspace and scoped-view targets remain navigation only."
13206        .to_owned();
13207    question.kind = MigrationQuestionKind::AssignmentGroup {
13208        rule_version: ASSIGNMENT_GROUP_RULE_VERSION.to_owned(),
13209        source_root: source_root.to_path_buf(),
13210        source_paths,
13211        content_kind,
13212        coverage_digest,
13213    };
13214    Ok(question)
13215}
13216
13217fn assignment_group_coverage_digest(
13218    source_root: &Path,
13219    content_kind: MigrationContentKind,
13220    members: &[AssignmentGroupMember],
13221) -> Result<String> {
13222    fn update_field(hasher: &mut Sha256, value: &[u8]) {
13223        hasher.update((value.len() as u64).to_le_bytes());
13224        hasher.update(value);
13225    }
13226
13227    let mut hasher = Sha256::new();
13228    update_field(&mut hasher, ASSIGNMENT_GROUP_RULE_VERSION.as_bytes());
13229    update_field(
13230        &mut hasher,
13231        portable_migration_wire_scope(source_root)?.as_bytes(),
13232    );
13233    update_field(
13234        &mut hasher,
13235        match content_kind {
13236            MigrationContentKind::Canonical => b"canonical",
13237            MigrationContentKind::Generated => b"generated",
13238            MigrationContentKind::SecretShaped => b"secret_shaped",
13239            MigrationContentKind::Temporary => b"temporary",
13240        },
13241    );
13242    for member in members {
13243        update_field(
13244            &mut hasher,
13245            match member.kind {
13246                AssignmentSourceKind::File => b"file",
13247                AssignmentSourceKind::ReconstructableTree => b"reconstructable_tree",
13248            },
13249        );
13250        update_field(
13251            &mut hasher,
13252            portable_migration_wire_path(&member.path)?.as_bytes(),
13253        );
13254    }
13255    Ok(format!("{:x}", hasher.finalize()))
13256}
13257
13258fn assignment_question(
13259    source_path: &Path,
13260    content_kind: MigrationContentKind,
13261    targets: &[MigrationTarget],
13262) -> Result<MigrationQuestion> {
13263    let accepted_kinds: &[MigrationTargetKind] = match content_kind {
13264        MigrationContentKind::Canonical => &[
13265            MigrationTargetKind::Folderbase,
13266            MigrationTargetKind::RetainedFolder,
13267        ],
13268        MigrationContentKind::Generated | MigrationContentKind::Temporary => &[
13269            MigrationTargetKind::Folderbase,
13270            MigrationTargetKind::RetainedFolder,
13271            MigrationTargetKind::Exclusion,
13272        ],
13273        MigrationContentKind::SecretShaped => &[MigrationTargetKind::RetainedFolder],
13274    };
13275    let options = targets
13276        .iter()
13277        .filter(|target| accepted_kinds.contains(&target.kind))
13278        .map(|target| MigrationOption {
13279            id: target.id.clone(),
13280            label: target.suggested_name.clone(),
13281            consequence: match target.kind {
13282                MigrationTargetKind::Folderbase => {
13283                    "Copy this content into the selected folderbase's permission boundary."
13284                        .to_owned()
13285                }
13286                MigrationTargetKind::RetainedFolder => {
13287                    "Leave this content in the source folder and do not copy it.".to_owned()
13288                }
13289                MigrationTargetKind::Exclusion => {
13290                    "Record an explicit exclusion and leave the source unchanged.".to_owned()
13291                }
13292                MigrationTargetKind::Workspace | MigrationTargetKind::ScopedView => {
13293                    unreachable!("navigation targets cannot own canonical content")
13294                }
13295            },
13296        })
13297        .collect();
13298    let recommended_option_id = match content_kind {
13299        MigrationContentKind::Canonical => "target_primary_folderbase",
13300        MigrationContentKind::SecretShaped => "target_retained_source",
13301        MigrationContentKind::Generated | MigrationContentKind::Temporary => "target_exclusion",
13302    }
13303    .to_owned();
13304
13305    Ok(MigrationQuestion {
13306        id: stable_path_id("question_assignment", source_path)?,
13307        prompt: format!(
13308            "Choose an explicit destination for `{}`.",
13309            source_path.display()
13310        ),
13311        context: "Workspace and scoped-view targets are navigation only and cannot own canonical content."
13312            .to_owned(),
13313        kind: MigrationQuestionKind::Assignment {
13314            source_path: source_path.to_path_buf(),
13315            content_kind,
13316        },
13317        options,
13318        recommended_option_id,
13319    })
13320}
13321
13322fn safe_boundary_name(name: &str) -> String {
13323    let normalized = name
13324        .chars()
13325        .map(|character| {
13326            if character.is_ascii_alphanumeric() || matches!(character, '-' | '_') {
13327                character
13328            } else {
13329                '-'
13330            }
13331        })
13332        .collect::<String>();
13333    let normalized = normalized.trim_matches('-');
13334    if normalized.is_empty() {
13335        "Boundary".to_owned()
13336    } else {
13337        normalized.to_owned()
13338    }
13339}
13340
13341fn validate_answers(
13342    analysis: &MigrationAnalysis,
13343    answers: &[MigrationAnswer],
13344) -> Result<ParsedMigrationAnswers> {
13345    let expected_assignment_questions = assignment_questions(
13346        &analysis.files,
13347        &analysis.reconstructable_trees,
13348        &analysis.proposed_targets,
13349    )?;
13350    let actual_assignment_questions = analysis
13351        .questions
13352        .iter()
13353        .filter(|question| !matches!(question.kind, MigrationQuestionKind::Decision))
13354        .cloned()
13355        .collect::<Vec<_>>();
13356    if actual_assignment_questions != expected_assignment_questions {
13357        return Err(FolderbaseError::InvalidRecord {
13358            path: analysis.root.clone(),
13359            message: "migration assignment questions do not match the canonical analyzer output"
13360                .to_owned(),
13361        });
13362    }
13363    let known: BTreeSet<&str> = analysis
13364        .questions
13365        .iter()
13366        .map(|question| question.id.as_str())
13367        .collect();
13368    let supplied: BTreeSet<&str> = answers
13369        .iter()
13370        .filter(|answer| !answer.answer.trim().is_empty())
13371        .map(|answer| answer.question_id.as_str())
13372        .collect();
13373    if known != supplied || answers.len() != known.len() {
13374        return Err(FolderbaseError::InvalidRecord {
13375            path: analysis.root.clone(),
13376            message: "every migration question must have exactly one non-empty answer".to_owned(),
13377        });
13378    }
13379    for answer in answers {
13380        let question = analysis
13381            .questions
13382            .iter()
13383            .find(|question| question.id == answer.question_id)
13384            .ok_or_else(|| FolderbaseError::InvalidRecord {
13385                path: analysis.root.clone(),
13386                message: format!("unknown migration question: {}", answer.question_id),
13387            })?;
13388        if !question
13389            .options
13390            .iter()
13391            .any(|option| option.id == answer.answer)
13392        {
13393            return Err(FolderbaseError::InvalidRecord {
13394                path: analysis.root.clone(),
13395                message: format!(
13396                    "{} must use one of the question's accepted option IDs",
13397                    answer.question_id
13398                ),
13399            });
13400        }
13401    }
13402
13403    let answer = |question_id: &str| {
13404        answers
13405            .iter()
13406            .find(|answer| answer.question_id == question_id)
13407            .map(|answer| answer.answer.as_str())
13408            .ok_or_else(|| FolderbaseError::InvalidRecord {
13409                path: analysis.root.clone(),
13410                message: format!("missing migration answer for {question_id}"),
13411            })
13412    };
13413    let canonical_scope = match answer("question_canonical_scope")? {
13414        "one_folderbase" => CanonicalScopeAnswer::OneFolderbase,
13415        "proposed_boundaries" => CanonicalScopeAnswer::ProposedBoundaries,
13416        _ => {
13417            return Err(FolderbaseError::InvalidRecord {
13418                path: analysis.root.clone(),
13419                message:
13420                    "question_canonical_scope must be `one_folderbase` or `proposed_boundaries`"
13421                        .to_owned(),
13422            });
13423        }
13424    };
13425    let generated_content = match answer("question_generated_content")? {
13426        "exclude_generated" => GeneratedContentAnswer::Exclude,
13427        "include_generated" => GeneratedContentAnswer::Include,
13428        _ => {
13429            return Err(FolderbaseError::InvalidRecord {
13430                path: analysis.root.clone(),
13431                message:
13432                    "question_generated_content must be `exclude_generated` or `include_generated`"
13433                        .to_owned(),
13434            });
13435        }
13436    };
13437    if known.contains("question_secrets") && !matches!(answer("question_secrets")?, "local_only") {
13438        return Err(FolderbaseError::InvalidRecord {
13439            path: analysis.root.clone(),
13440            message: "question_secrets must be `local_only`".to_owned(),
13441        });
13442    }
13443    let mut assignments = BTreeMap::new();
13444    let reconstructable_paths = analysis
13445        .reconstructable_trees
13446        .iter()
13447        .map(|tree| tree.path.as_path())
13448        .collect::<BTreeSet<_>>();
13449    let mut grouped_assignments = Vec::new();
13450    for question in &analysis.questions {
13451        let answered = answers
13452            .iter()
13453            .find(|answered| answered.question_id == question.id)
13454            .ok_or_else(|| FolderbaseError::InvalidRecord {
13455                path: analysis.root.clone(),
13456                message: format!("missing migration answer for {}", question.id),
13457            })?;
13458        let (source_paths, content_kind, is_group) = match &question.kind {
13459            MigrationQuestionKind::Assignment {
13460                source_path,
13461                content_kind,
13462            } => (std::slice::from_ref(source_path), *content_kind, false),
13463            MigrationQuestionKind::AssignmentGroup {
13464                rule_version,
13465                source_root,
13466                source_paths,
13467                content_kind,
13468                coverage_digest,
13469            } => {
13470                if rule_version != ASSIGNMENT_GROUP_RULE_VERSION
13471                    || source_paths.windows(2).any(|pair| pair[0] >= pair[1])
13472                {
13473                    return Err(FolderbaseError::InvalidRecord {
13474                        path: analysis.root.clone(),
13475                        message: format!(
13476                            "{} uses an unsupported or non-deterministic assignment group",
13477                            question.id
13478                        ),
13479                    });
13480                }
13481                let members = source_paths
13482                    .iter()
13483                    .map(|source_path| AssignmentGroupMember {
13484                        path: source_path.clone(),
13485                        kind: if reconstructable_paths.contains(source_path.as_path()) {
13486                            AssignmentSourceKind::ReconstructableTree
13487                        } else {
13488                            AssignmentSourceKind::File
13489                        },
13490                    })
13491                    .collect::<Vec<_>>();
13492                if assignment_group_coverage_digest(source_root, *content_kind, &members)?
13493                    != *coverage_digest
13494                {
13495                    return Err(FolderbaseError::InvalidRecord {
13496                        path: analysis.root.clone(),
13497                        message: format!("{} has stale assignment group coverage", question.id),
13498                    });
13499                }
13500                let mut normalized_exceptions = answered.exceptions.clone();
13501                normalized_exceptions.sort_by(|left, right| {
13502                    portable_path_key(&left.source_path).cmp(&portable_path_key(&right.source_path))
13503                });
13504                grouped_assignments.push(GroupedAssignmentContract {
13505                    question_id: question.id.clone(),
13506                    rule_version: rule_version.clone(),
13507                    source_root: source_root.clone(),
13508                    members: members
13509                        .iter()
13510                        .map(|member| GroupedAssignmentMemberContract {
13511                            source_path: member.path.clone(),
13512                            source_kind: member.kind,
13513                        })
13514                        .collect(),
13515                    content_kind: *content_kind,
13516                    coverage_digest: coverage_digest.clone(),
13517                    default_target_id: answered.answer.clone(),
13518                    exceptions: normalized_exceptions,
13519                });
13520                (source_paths.as_slice(), *content_kind, true)
13521            }
13522            MigrationQuestionKind::Decision => continue,
13523        };
13524        if !is_group && !answered.exceptions.is_empty() {
13525            return Err(FolderbaseError::InvalidRecord {
13526                path: analysis.root.clone(),
13527                message: format!("{} does not accept grouped exceptions", question.id),
13528            });
13529        }
13530        for source_path in source_paths {
13531            if assignments.contains_key(source_path) {
13532                return Err(FolderbaseError::InvalidRecord {
13533                    path: analysis.root.clone(),
13534                    message: format!(
13535                        "migration assignment scopes must be unique: {}",
13536                        source_path.display()
13537                    ),
13538                });
13539            }
13540            assignments.insert(
13541                source_path.clone(),
13542                ParsedAssignment {
13543                    content_kind,
13544                    target_id: answer(&question.id)?.to_owned(),
13545                },
13546            );
13547        }
13548        let mut exception_paths = BTreeSet::new();
13549        for exception in &answered.exceptions {
13550            ensure_safe_relative(&exception.source_path)?;
13551            if !exception_paths.insert(portable_path_key(&exception.source_path)) {
13552                return Err(FolderbaseError::InvalidRecord {
13553                    path: analysis.root.clone(),
13554                    message: format!(
13555                        "{} contains a duplicate exception for {}",
13556                        question.id,
13557                        exception.source_path.display()
13558                    ),
13559                });
13560            }
13561            if !source_paths.contains(&exception.source_path) {
13562                return Err(FolderbaseError::InvalidRecord {
13563                    path: analysis.root.clone(),
13564                    message: format!(
13565                        "{} contains a nonmember exception for {}",
13566                        question.id,
13567                        exception.source_path.display()
13568                    ),
13569                });
13570            }
13571            if !question
13572                .options
13573                .iter()
13574                .any(|option| option.id == exception.target_id)
13575            {
13576                return Err(FolderbaseError::InvalidRecord {
13577                    path: analysis.root.clone(),
13578                    message: format!(
13579                        "{} exception must use one of the question's accepted option IDs",
13580                        question.id
13581                    ),
13582                });
13583            }
13584            assignments.insert(
13585                exception.source_path.clone(),
13586                ParsedAssignment {
13587                    content_kind,
13588                    target_id: exception.target_id.clone(),
13589                },
13590            );
13591        }
13592    }
13593    let expected_scopes = analysis
13594        .files
13595        .iter()
13596        .map(|file| file.path.as_path())
13597        .chain(
13598            analysis
13599                .reconstructable_trees
13600                .iter()
13601                .map(|tree| tree.path.as_path()),
13602        )
13603        .collect::<BTreeSet<_>>();
13604    let assigned_scopes = assignments
13605        .keys()
13606        .map(PathBuf::as_path)
13607        .collect::<BTreeSet<_>>();
13608    if assigned_scopes != expected_scopes {
13609        return Err(FolderbaseError::InvalidRecord {
13610            path: analysis.root.clone(),
13611            message: "migration assignments must cover every analyzed source scope exactly once"
13612                .to_owned(),
13613        });
13614    }
13615    for assignment in assignments.values() {
13616        let target = analysis
13617            .proposed_targets
13618            .iter()
13619            .find(|target| target.id == assignment.target_id)
13620            .ok_or_else(|| FolderbaseError::InvalidRecord {
13621                path: analysis.root.clone(),
13622                message: format!("unknown migration target: {}", assignment.target_id),
13623            })?;
13624        if matches!(
13625            target.kind,
13626            MigrationTargetKind::Workspace | MigrationTargetKind::ScopedView
13627        ) {
13628            return Err(FolderbaseError::InvalidRecord {
13629                path: analysis.root.clone(),
13630                message: format!("navigation target cannot own content: {}", target.id),
13631            });
13632        }
13633        if canonical_scope == CanonicalScopeAnswer::OneFolderbase
13634            && target.kind == MigrationTargetKind::Folderbase
13635            && target.id != "target_primary_folderbase"
13636        {
13637            return Err(FolderbaseError::InvalidRecord {
13638                path: analysis.root.clone(),
13639                message: "one_folderbase assignments must use target_primary_folderbase".to_owned(),
13640            });
13641        }
13642        if assignment.content_kind == MigrationContentKind::Generated
13643            && generated_content == GeneratedContentAnswer::Exclude
13644            && target.kind == MigrationTargetKind::Folderbase
13645        {
13646            return Err(FolderbaseError::InvalidRecord {
13647                path: analysis.root.clone(),
13648                message: "exclude_generated cannot assign generated content to a folderbase target"
13649                    .to_owned(),
13650            });
13651        }
13652        if assignment.content_kind == MigrationContentKind::SecretShaped
13653            && target.kind != MigrationTargetKind::RetainedFolder
13654        {
13655            return Err(FolderbaseError::InvalidRecord {
13656                path: analysis.root.clone(),
13657                message: "secret-shaped content requires an explicit retained-local target"
13658                    .to_owned(),
13659            });
13660        }
13661    }
13662    Ok(ParsedMigrationAnswers {
13663        canonical_scope,
13664        generated_content,
13665        assignments,
13666        grouped_assignments,
13667    })
13668}
13669
13670fn inventory_digest(files: &[SourceFile]) -> Result<String> {
13671    let mut hasher = Sha256::new();
13672    for file in files {
13673        let portable = portable_migration_wire_path(&file.path)?;
13674        hasher.update(portable.as_bytes());
13675        hasher.update([0]);
13676        hasher.update(file.bytes.to_le_bytes());
13677        hasher.update([0]);
13678        hasher.update(file.sha256.as_bytes());
13679        hasher.update([b'\n']);
13680    }
13681    Ok(format!("{:x}", hasher.finalize()))
13682}
13683
13684fn metadata_inventory_digest(
13685    files: &[AnalyzedFile],
13686    reconstructable_trees: &[ReconstructableTree],
13687    nested_folderbases: &[NestedFolderbaseBoundary],
13688) -> Result<String> {
13689    let mut hasher = Sha256::new();
13690    for file in files {
13691        let portable = portable_migration_wire_path(&file.path)?;
13692        hasher.update(portable.as_bytes());
13693        hasher.update([0]);
13694        hasher.update(file.bytes.to_le_bytes());
13695        hasher.update([0]);
13696        hasher.update([file.classification_bits()]);
13697        hasher.update([b'\n']);
13698    }
13699    for tree in reconstructable_trees {
13700        hasher.update(b"reconstructable:");
13701        let portable = portable_migration_wire_path(&tree.path)?;
13702        hasher.update(portable.as_bytes());
13703        hasher.update([b'\n']);
13704    }
13705    for boundary in nested_folderbases {
13706        hasher.update(b"nested:");
13707        let portable = portable_migration_wire_path(&boundary.path)?;
13708        hasher.update(portable.as_bytes());
13709        hasher.update([boundary.state as u8, b'\n']);
13710    }
13711    Ok(format!("{:x}", hasher.finalize()))
13712}
13713
13714fn additive_destination_roots(operations: &[MigrationOperation]) -> Vec<PathBuf> {
13715    let mut roots = operations
13716        .iter()
13717        .filter_map(|operation| match operation {
13718            MigrationOperation::CreateFolder { path } => Some(path.clone()),
13719            _ => None,
13720        })
13721        .collect::<Vec<_>>();
13722    roots.sort();
13723    roots.dedup();
13724    roots
13725        .iter()
13726        .filter(|candidate| {
13727            !roots
13728                .iter()
13729                .any(|other| candidate != &other && candidate.starts_with(other))
13730        })
13731        .cloned()
13732        .collect()
13733}
13734
13735fn source_topology_snapshot(
13736    files: &[AnalyzedFile],
13737    reconstructable_trees: &[ReconstructableTree],
13738    nested_folderbases: &[NestedFolderbaseBoundary],
13739    destination_roots: &[PathBuf],
13740) -> SourceTopologySnapshot {
13741    let is_destination = |path: &Path| {
13742        destination_roots
13743            .iter()
13744            .any(|destination| path == destination || path.starts_with(destination))
13745    };
13746    SourceTopologySnapshot {
13747        version: "1".to_owned(),
13748        files: files
13749            .iter()
13750            .filter(|file| !is_destination(&file.path))
13751            .map(|file| file.path.clone())
13752            .collect(),
13753        reconstructable_trees: reconstructable_trees
13754            .iter()
13755            .filter(|tree| !is_destination(&tree.path))
13756            .map(|tree| tree.path.clone())
13757            .collect(),
13758        nested_folderbases: nested_folderbases
13759            .iter()
13760            .filter(|boundary| !is_destination(&boundary.path))
13761            .cloned()
13762            .collect(),
13763    }
13764}
13765
13766fn verify_additive_source_topology_in(
13767    filesystem: &MigrationFilesystem,
13768    plan: &MigrationPlan,
13769) -> Result<()> {
13770    let expected_value = plan
13771        .extensions
13772        .get(SOURCE_TOPOLOGY_EXTENSION)
13773        .ok_or_else(|| FolderbaseError::MigrationSourceChanged(plan.root.clone()))?;
13774    let expected: SourceTopologySnapshot = serde_json::from_value(expected_value.clone())
13775        .map_err(|_| FolderbaseError::MigrationSourceChanged(plan.root.clone()))?;
13776    if expected.version != "1" {
13777        return Err(FolderbaseError::MigrationSourceChanged(plan.root.clone()));
13778    }
13779    let current_analysis = filesystem.analyze_retained_root()?;
13780    let current = source_topology_snapshot(
13781        &current_analysis.files,
13782        &current_analysis.reconstructable_trees,
13783        &current_analysis.nested_folderbases,
13784        &additive_destination_roots(&plan.operations),
13785    );
13786    if current == expected {
13787        return Ok(());
13788    }
13789
13790    let expected_files = expected.files.iter().collect::<BTreeSet<_>>();
13791    let current_files = current.files.iter().collect::<BTreeSet<_>>();
13792    if let Some(path) = current_files.difference(&expected_files).next() {
13793        return Err(FolderbaseError::MigrationSourceChanged((*path).clone()));
13794    }
13795    if let Some(path) = expected_files.difference(&current_files).next() {
13796        return Err(FolderbaseError::MigrationSourceChanged((*path).clone()));
13797    }
13798    let expected_trees = expected
13799        .reconstructable_trees
13800        .iter()
13801        .collect::<BTreeSet<_>>();
13802    let current_trees = current
13803        .reconstructable_trees
13804        .iter()
13805        .collect::<BTreeSet<_>>();
13806    if let Some(path) = current_trees.difference(&expected_trees).next() {
13807        return Err(FolderbaseError::MigrationSourceChanged((*path).clone()));
13808    }
13809    if let Some(path) = expected_trees.difference(&current_trees).next() {
13810        return Err(FolderbaseError::MigrationSourceChanged((*path).clone()));
13811    }
13812    Err(FolderbaseError::MigrationSourceChanged(plan.root.clone()))
13813}
13814
13815fn verify_expanded_reconstructable_trees_in(
13816    filesystem: &MigrationFilesystem,
13817    plan: &MigrationPlan,
13818) -> Result<()> {
13819    let Some(value) = plan
13820        .extensions
13821        .get(EXPANDED_RECONSTRUCTABLE_TREES_EXTENSION)
13822    else {
13823        return Ok(());
13824    };
13825    let expected: ExpandedReconstructableTreesExtension = serde_json::from_value(value.clone())
13826        .map_err(|_| FolderbaseError::MigrationSourceChanged(plan.root.clone()))?;
13827    if expected.version != "1" {
13828        return Err(FolderbaseError::MigrationSourceChanged(plan.root.clone()));
13829    }
13830    for tree in expected.trees {
13831        let expanded = filesystem.expand_retained_tree(&tree.source_root)?;
13832        if !expanded.nested_folderbases.is_empty()
13833            || expanded.files.iter().any(AnalyzedFile::is_secret_shaped)
13834        {
13835            return Err(FolderbaseError::MigrationSourceChanged(tree.source_root));
13836        }
13837        let mut current_paths = expanded
13838            .files
13839            .into_iter()
13840            .map(|file| tree.source_root.join(file.path))
13841            .collect::<Vec<_>>();
13842        current_paths.sort();
13843        if current_paths != tree.source_paths {
13844            let expected_paths = tree.source_paths.iter().collect::<BTreeSet<_>>();
13845            let current = current_paths.iter().collect::<BTreeSet<_>>();
13846            let changed = current
13847                .symmetric_difference(&expected_paths)
13848                .next()
13849                .map(|path| (*path).clone())
13850                .unwrap_or(tree.source_root);
13851            return Err(FolderbaseError::MigrationSourceChanged(changed));
13852        }
13853    }
13854    Ok(())
13855}
13856
13857fn verify_root_identity(plan: &MigrationPlan) -> Result<()> {
13858    let current = PhysicalIdentity::from_path(&plan.root)
13859        .map_err(|source| FolderbaseError::io(&plan.root, source))?;
13860    if plan.root_identity.as_ref().map(|root| root.identity()) != Some(current) {
13861        return Err(FolderbaseError::MigrationSourceChanged(plan.root.clone()));
13862    }
13863    Ok(())
13864}
13865
13866fn verify_source_files(plan: &MigrationPlan) -> Result<()> {
13867    let mut current = Vec::new();
13868    for file in &plan.source_inventory.files {
13869        refuse_nested_folderbase_path(&plan.root, &file.path)?;
13870        let path = safe_join(&plan.root, &file.path)?;
13871        let metadata = fs::symlink_metadata(&path)
13872            .map_err(|_| FolderbaseError::MigrationSourceChanged(file.path.clone()))?;
13873        if !metadata.is_file()
13874            || metadata.file_type().is_symlink()
13875            || metadata.len() != file.bytes
13876            || sha256_path(&path)? != file.sha256
13877        {
13878            return Err(FolderbaseError::MigrationSourceChanged(file.path.clone()));
13879        }
13880        current.push(file.clone());
13881    }
13882    if inventory_digest(&current)? != plan.source_inventory.digest {
13883        return Err(FolderbaseError::MigrationSourceChanged(plan.root.clone()));
13884    }
13885    Ok(())
13886}
13887
13888fn verify_source_files_in(filesystem: &MigrationFilesystem, plan: &MigrationPlan) -> Result<()> {
13889    let mut current = Vec::new();
13890    for file in &plan.source_inventory.files {
13891        refuse_nested_folderbase_path_in(filesystem, &file.path)?;
13892        let metadata = filesystem
13893            .metadata(&file.path)?
13894            .ok_or_else(|| FolderbaseError::MigrationSourceChanged(file.path.clone()))?;
13895        if !metadata.is_file()
13896            || metadata.file_type().is_symlink()
13897            || metadata.len() != file.bytes
13898            || filesystem.sha256_regular(&file.path)? != file.sha256
13899        {
13900            return Err(FolderbaseError::MigrationSourceChanged(file.path.clone()));
13901        }
13902        current.push(file.clone());
13903    }
13904    if inventory_digest(&current)? != plan.source_inventory.digest {
13905        return Err(FolderbaseError::MigrationSourceChanged(
13906            filesystem.display_root().to_path_buf(),
13907        ));
13908    }
13909    Ok(())
13910}
13911
13912fn refuse_nested_folderbase_path_in(
13913    filesystem: &MigrationFilesystem,
13914    relative: &Path,
13915) -> Result<()> {
13916    ensure_safe_relative(relative)?;
13917    let mut prefix = PathBuf::new();
13918    let mut components = relative.components().peekable();
13919    while let Some(component) = components.next() {
13920        let Component::Normal(component) = component else {
13921            return Err(FolderbaseError::UnsafePath(relative.to_path_buf()));
13922        };
13923        if components.peek().is_none() {
13924            break;
13925        }
13926        prefix.push(component);
13927        let directory = filesystem.open_directory(&prefix)?;
13928        if classify_nested_folderbase_boundary(&directory, &filesystem.display(&prefix))?
13929            != NestedFolderbaseBoundaryKind::None
13930        {
13931            return Err(FolderbaseError::UnsafePath(prefix));
13932        }
13933    }
13934    Ok(())
13935}
13936
13937fn plan_digest(plan: &MigrationPlan) -> Result<String> {
13938    let bytes = serde_json::to_vec(&(
13939        &plan.protocol_version,
13940        &plan.id,
13941        &plan.root,
13942        MigrationState::Approved,
13943        &plan.source_inventory,
13944        &plan.answers,
13945        &plan.template_references,
13946        &plan.targets,
13947        &plan.operations,
13948        &plan.exclusions,
13949        &plan.extensions,
13950    ))
13951    .map_err(|source| FolderbaseError::json(&plan.root, source))?;
13952    Ok(format!("{:x}", Sha256::digest(bytes)))
13953}
13954
13955fn require_state(actual: MigrationState, expected: MigrationState) -> Result<()> {
13956    if actual != expected {
13957        return Err(FolderbaseError::InvalidMigrationState {
13958            expected: expected.as_str(),
13959            actual: actual.as_str().to_owned(),
13960        });
13961    }
13962    Ok(())
13963}
13964
13965fn sha256_path(path: &Path) -> Result<String> {
13966    let mut file = fs::File::open(path).map_err(|source| FolderbaseError::io(path, source))?;
13967    let mut hasher = Sha256::new();
13968    let mut buffer = [0_u8; 64 * 1024];
13969    loop {
13970        let read = file
13971            .read(&mut buffer)
13972            .map_err(|source| FolderbaseError::io(path, source))?;
13973        if read == 0 {
13974            break;
13975        }
13976        hasher.update(&buffer[..read]);
13977    }
13978    Ok(format!("{:x}", hasher.finalize()))
13979}
13980
13981fn copy_new(source: &Path, destination: &Path) -> Result<()> {
13982    let source_metadata =
13983        fs::symlink_metadata(source).map_err(|error| FolderbaseError::io(source, error))?;
13984    if !source_metadata.is_file() || source_metadata.file_type().is_symlink() {
13985        return Err(FolderbaseError::MigrationSourceChanged(
13986            source.to_path_buf(),
13987        ));
13988    }
13989    let mut input = fs::File::open(source).map_err(|error| FolderbaseError::io(source, error))?;
13990    let mut output = fs::OpenOptions::new()
13991        .write(true)
13992        .create_new(true)
13993        .open(destination)
13994        .map_err(|error| {
13995            if error.kind() == std::io::ErrorKind::AlreadyExists {
13996                FolderbaseError::WouldOverwrite(destination.to_path_buf())
13997            } else {
13998                FolderbaseError::io(destination, error)
13999            }
14000        })?;
14001    output
14002        .set_permissions(source_metadata.permissions())
14003        .map_err(|error| FolderbaseError::io(destination, error))?;
14004    std::io::copy(&mut input, &mut output)
14005        .map_err(|error| FolderbaseError::io(destination, error))?;
14006    output
14007        .flush()
14008        .and_then(|()| output.sync_all())
14009        .map_err(|error| FolderbaseError::io(destination, error))
14010}
14011
14012#[cfg(test)]
14013#[allow(dead_code)]
14014fn restore_snapshot_no_clobber(
14015    root: &Path,
14016    migration_id: &str,
14017    index: usize,
14018    snapshot: &Path,
14019    destination: &Path,
14020    expected_sha256: &str,
14021) -> Result<()> {
14022    let metadata =
14023        fs::symlink_metadata(snapshot).map_err(|error| FolderbaseError::io(snapshot, error))?;
14024    if !metadata.is_file()
14025        || metadata.file_type().is_symlink()
14026        || sha256_path(snapshot)? != expected_sha256
14027    {
14028        return Err(FolderbaseError::MigrationVerificationFailed(
14029            snapshot.to_path_buf(),
14030        ));
14031    }
14032
14033    if let Some(digest) = regular_file_digest_if_present(destination)? {
14034        if digest == expected_sha256 {
14035            return Ok(());
14036        }
14037        return Err(FolderbaseError::WouldOverwrite(destination.to_path_buf()));
14038    }
14039
14040    let staging_relative = PathBuf::from(MIGRATIONS_DIR)
14041        .join(migration_id)
14042        .join("staging");
14043    let staging = safe_join(root, &staging_relative)?;
14044    create_directory_if_missing(&staging)?;
14045    let temporary = staging.join(format!("restore-{index}.tmp"));
14046    let temporary_ready = match fs::symlink_metadata(&temporary) {
14047        Ok(metadata) if metadata.is_file() && !metadata.file_type().is_symlink() => {
14048            if sha256_path(&temporary)? == expected_sha256 {
14049                true
14050            } else {
14051                fs::remove_file(&temporary)
14052                    .map_err(|error| FolderbaseError::io(&temporary, error))?;
14053                sync_parent(&temporary)?;
14054                false
14055            }
14056        }
14057        Ok(_) => {
14058            return Err(FolderbaseError::MigrationVerificationFailed(temporary));
14059        }
14060        Err(error) if error.kind() == std::io::ErrorKind::NotFound => false,
14061        Err(error) => return Err(FolderbaseError::io(&temporary, error)),
14062    };
14063    if !temporary_ready {
14064        copy_new(snapshot, &temporary)?;
14065        sync_parent(&temporary)?;
14066        if sha256_path(&temporary)? != expected_sha256 {
14067            return Err(FolderbaseError::MigrationVerificationFailed(temporary));
14068        }
14069    }
14070
14071    fs::hard_link(&temporary, destination).map_err(|error| {
14072        if error.kind() == std::io::ErrorKind::AlreadyExists {
14073            FolderbaseError::WouldOverwrite(destination.to_path_buf())
14074        } else {
14075            FolderbaseError::io(destination, error)
14076        }
14077    })?;
14078    if sha256_path(destination)? != expected_sha256 {
14079        let _ = fs::remove_file(destination);
14080        return Err(FolderbaseError::MigrationVerificationFailed(
14081            destination.to_path_buf(),
14082        ));
14083    }
14084    sync_parent(destination)?;
14085    fs::remove_file(&temporary).map_err(|error| FolderbaseError::io(&temporary, error))?;
14086    sync_parent(&temporary)
14087}
14088
14089#[cfg(test)]
14090#[allow(dead_code)]
14091fn write_bytes_new(path: &Path, content: &[u8]) -> Result<()> {
14092    let mut file = fs::OpenOptions::new()
14093        .write(true)
14094        .create_new(true)
14095        .open(path)
14096        .map_err(|source| {
14097            if source.kind() == std::io::ErrorKind::AlreadyExists {
14098                FolderbaseError::WouldOverwrite(path.to_path_buf())
14099            } else {
14100                FolderbaseError::io(path, source)
14101            }
14102        })?;
14103    file.write_all(content)
14104        .and_then(|()| file.sync_all())
14105        .map_err(|source| FolderbaseError::io(path, source))?;
14106    sync_parent(path)
14107}
14108
14109fn write_json_new(path: &Path, value: &impl Serialize) -> Result<()> {
14110    write_json_new_with_hook(path, value, || {})
14111}
14112
14113fn write_json_new_with_hook(
14114    path: &Path,
14115    value: &impl Serialize,
14116    mut checkpoint: impl FnMut(),
14117) -> Result<()> {
14118    let content =
14119        serde_json::to_vec_pretty(value).map_err(|source| FolderbaseError::json(path, source))?;
14120    let parent = path.parent().ok_or_else(|| {
14121        invalid_journal(
14122            path,
14123            "new JSON record path does not have a parent directory",
14124        )
14125    })?;
14126    let temporary = parent.join(format!(".record-{}.tmp", Uuid::now_v7()));
14127    let write_result = (|| -> Result<()> {
14128        let mut file = fs::OpenOptions::new()
14129            .write(true)
14130            .create_new(true)
14131            .open(&temporary)
14132            .map_err(|source| FolderbaseError::io(&temporary, source))?;
14133        file.write_all(&content)
14134            .and_then(|()| file.write_all(b"\n"))
14135            .and_then(|()| file.sync_all())
14136            .map_err(|source| FolderbaseError::io(&temporary, source))?;
14137        drop(file);
14138        checkpoint();
14139        fs::hard_link(&temporary, path).map_err(|source| {
14140            if source.kind() == std::io::ErrorKind::AlreadyExists {
14141                FolderbaseError::WouldOverwrite(path.to_path_buf())
14142            } else {
14143                FolderbaseError::io(path, source)
14144            }
14145        })?;
14146        sync_directory(parent)?;
14147        fs::remove_file(&temporary).map_err(|source| FolderbaseError::io(&temporary, source))?;
14148        sync_directory(parent)
14149    })();
14150    if write_result.is_err() {
14151        let _ = fs::remove_file(&temporary);
14152    }
14153    write_result
14154}
14155
14156fn persist_plan(plan: &MigrationPlan) -> Result<()> {
14157    let path = safe_join(&plan.root, &migration_plan_relative(&plan.id))?;
14158    let content =
14159        serde_json::to_vec_pretty(plan).map_err(|source| FolderbaseError::json(&path, source))?;
14160    let parent = path.parent().ok_or_else(|| {
14161        invalid_journal(
14162            &path,
14163            "migration plan path does not have a parent directory",
14164        )
14165    })?;
14166    let temporary = parent.join(format!("plan.{}.tmp", Uuid::now_v7()));
14167    let write_result = (|| -> Result<()> {
14168        let mut file = fs::OpenOptions::new()
14169            .write(true)
14170            .create_new(true)
14171            .open(&temporary)
14172            .map_err(|source| FolderbaseError::io(&temporary, source))?;
14173        file.write_all(&content)
14174            .and_then(|()| file.write_all(b"\n"))
14175            .and_then(|()| file.sync_all())
14176            .map_err(|source| FolderbaseError::io(&temporary, source))?;
14177        fs::rename(&temporary, &path).map_err(|source| FolderbaseError::io(&path, source))?;
14178        sync_directory(parent)
14179    })();
14180    if write_result.is_err() {
14181        let _ = fs::remove_file(&temporary);
14182    }
14183    write_result
14184}
14185
14186fn persist_plan_in(filesystem: &MigrationFilesystem, plan: &MigrationPlan) -> Result<()> {
14187    validate_plan(
14188        filesystem.display_root(),
14189        &plan.id,
14190        &filesystem.display(&migration_plan_relative(&plan.id)),
14191        plan,
14192    )?;
14193    let mut content = serde_json::to_vec_pretty(plan)
14194        .map_err(|source| FolderbaseError::json(filesystem.display_root(), source))?;
14195    content.push(b'\n');
14196    filesystem.replace(&migration_plan_relative(&plan.id), &content)
14197}
14198
14199#[cfg(test)]
14200#[allow(dead_code)]
14201fn persist_journal(path: &Path, journal: &MigrationJournal) -> Result<()> {
14202    let content =
14203        serde_json::to_vec_pretty(journal).map_err(|source| FolderbaseError::json(path, source))?;
14204    let parent = path.parent().ok_or_else(|| {
14205        invalid_journal(
14206            path,
14207            "migration journal path does not have a parent directory",
14208        )
14209    })?;
14210    let temporary = parent.join(format!("result.{}.tmp", Uuid::now_v7()));
14211    let write_result = (|| -> Result<()> {
14212        let mut file = fs::OpenOptions::new()
14213            .write(true)
14214            .create_new(true)
14215            .open(&temporary)
14216            .map_err(|source| FolderbaseError::io(&temporary, source))?;
14217        file.write_all(&content)
14218            .and_then(|()| file.write_all(b"\n"))
14219            .and_then(|()| file.sync_all())
14220            .map_err(|source| FolderbaseError::io(&temporary, source))?;
14221        fs::rename(&temporary, path).map_err(|source| FolderbaseError::io(path, source))?;
14222        sync_directory(parent)
14223    })();
14224    if write_result.is_err() {
14225        let _ = fs::remove_file(&temporary);
14226    }
14227    write_result
14228}
14229
14230fn migration_journal_relative(migration_id: &str) -> PathBuf {
14231    PathBuf::from(MIGRATIONS_DIR)
14232        .join(migration_id)
14233        .join("result.json")
14234}
14235
14236fn journal_bytes(path: &Path, journal: &MigrationJournal) -> Result<Vec<u8>> {
14237    let mut content =
14238        serde_json::to_vec_pretty(journal).map_err(|source| FolderbaseError::json(path, source))?;
14239    content.push(b'\n');
14240    Ok(content)
14241}
14242
14243fn persist_journal_in(filesystem: &MigrationFilesystem, journal: &MigrationJournal) -> Result<()> {
14244    let relative = migration_journal_relative(&journal.id);
14245    let bytes = journal_bytes(&filesystem.display(&relative), journal)?;
14246    filesystem.replace(&relative, &bytes)
14247}
14248
14249fn sync_parent(path: &Path) -> Result<()> {
14250    if let Some(parent) = path.parent() {
14251        sync_directory(parent)
14252    } else {
14253        Ok(())
14254    }
14255}
14256
14257#[cfg(not(windows))]
14258fn sync_directory(path: &Path) -> Result<()> {
14259    let directory = fs::File::open(path).map_err(|source| FolderbaseError::io(path, source))?;
14260    directory
14261        .sync_all()
14262        .map_err(|source| FolderbaseError::io(path, source))
14263}
14264
14265#[cfg(windows)]
14266fn sync_directory(_path: &Path) -> Result<()> {
14267    // Windows does not provide the POSIX directory-fsync contract, and
14268    // FlushFileBuffers rejects directory handles with ERROR_ACCESS_DENIED.
14269    // Migration publication still flushes each staged regular file before
14270    // its namespace transition.
14271    Ok(())
14272}
14273
14274#[cfg(test)]
14275#[allow(dead_code)]
14276fn cleanup_staging(root: &Path, migration_id: &str) {
14277    let staging_relative = PathBuf::from(MIGRATIONS_DIR)
14278        .join(migration_id)
14279        .join("staging");
14280    let Ok(staging) = safe_join(root, &staging_relative) else {
14281        return;
14282    };
14283    if let Ok(entries) = fs::read_dir(&staging) {
14284        for entry in entries.flatten() {
14285            if entry.file_type().is_ok_and(|file_type| file_type.is_file()) {
14286                let _ = fs::remove_file(entry.path());
14287            }
14288        }
14289    }
14290    let _ = fs::remove_dir(staging);
14291}
14292
14293fn cleanup_staging_in(filesystem: &MigrationFilesystem, migration_id: &str) {
14294    let staging_relative = PathBuf::from(MIGRATIONS_DIR)
14295        .join(migration_id)
14296        .join("staging");
14297    if let Ok(names) = filesystem.closed_regular_file_names(&staging_relative, 65_536) {
14298        for name in names {
14299            let _ = filesystem.remove_file_if_present(&staging_relative.join(name));
14300        }
14301    }
14302    let _ = filesystem.remove_empty_directory_if_present(&staging_relative);
14303}
14304
14305#[cfg(test)]
14306#[path = "migration_transaction_red_tests.rs"]
14307mod migration_transaction_red_tests;
14308
14309#[cfg(test)]
14310mod tests {
14311    use std::{sync::mpsc, thread};
14312
14313    use tempfile::TempDir;
14314
14315    use super::*;
14316
14317    const LEGACY_MANIFEST: &[u8] = br#"{
14318  "$schema": "https://folderbase.ai/protocol/0.1/folderbase.schema.json",
14319  "protocol_version": "0.1.0",
14320  "folderbase": {
14321    "id": "folderbase_019f9b75-4f42-7f65-a012-2bfecdd8c475",
14322    "name": "Legacy Migration Test",
14323    "kind": "project",
14324    "status": "active",
14325    "created_at": "2026-07-26T00:00:00Z",
14326    "entry": "FOLDERBASE.md"
14327  },
14328  "policies": {
14329    "availability": "keep_local",
14330    "structural_changes": "approve",
14331    "archive": "approve",
14332    "cloud_sync": "disabled"
14333  }
14334}
14335"#;
14336
14337    #[test]
14338    fn typed_ignore_policy_proposal_rejects_content_above_the_capture_bound_without_mutation() {
14339        assert_ignore_policy_proposal_rejected(
14340            &"a".repeat(crate::MAX_FOLDERBASEIGNORE_BYTES as usize + 1),
14341        );
14342    }
14343
14344    #[test]
14345    fn typed_ignore_policy_approval_rejects_content_above_the_capture_bound_without_mutation() {
14346        assert_ignore_policy_approval_rejected(
14347            &"a".repeat(crate::MAX_FOLDERBASEIGNORE_BYTES as usize + 1),
14348        );
14349    }
14350
14351    #[test]
14352    fn typed_ignore_policy_apply_rejects_content_above_the_capture_bound_without_mutation() {
14353        assert_ignore_policy_apply_rejected(
14354            &"a".repeat(crate::MAX_FOLDERBASEIGNORE_BYTES as usize + 1),
14355        );
14356    }
14357
14358    #[test]
14359    fn typed_ignore_policy_proposal_rejects_invalid_gitignore_syntax_without_mutation() {
14360        assert_ignore_policy_proposal_rejected("{a,b\n");
14361    }
14362
14363    #[test]
14364    fn typed_ignore_policy_approval_rejects_invalid_gitignore_syntax_without_mutation() {
14365        assert_ignore_policy_approval_rejected("{a,b\n");
14366    }
14367
14368    #[test]
14369    fn typed_ignore_policy_apply_rejects_invalid_gitignore_syntax_without_mutation() {
14370        assert_ignore_policy_apply_rejected("{a,b\n");
14371    }
14372
14373    fn assert_ignore_policy_proposal_rejected(content: &str) {
14374        let root = initialized_structural_folderbase_fixture();
14375        let policy_path = root.path().join(".folderbaseignore");
14376        fs::write(&policy_path, b"node_modules/\n").unwrap();
14377        let before = snapshot_regular_files(root.path());
14378
14379        let error = match MigrationPlan::propose_structural(
14380            root.path(),
14381            vec![MigrationOperation::update_ignore_policy(content)],
14382        ) {
14383            Err(error) => error,
14384            Ok(_) => panic!("capture-incompatible policy must fail during proposal"),
14385        };
14386
14387        assert_invalid_ignore_policy(error);
14388        assert_eq!(snapshot_regular_files(root.path()), before);
14389    }
14390
14391    fn assert_ignore_policy_approval_rejected(content: &str) {
14392        let root = initialized_structural_folderbase_fixture();
14393        let policy_path = root.path().join(".folderbaseignore");
14394        fs::write(&policy_path, b"node_modules/\n").unwrap();
14395        let mut plan = MigrationPlan::propose_structural(
14396            root.path(),
14397            vec![MigrationOperation::update_ignore_policy("Derived/\n")],
14398        )
14399        .unwrap();
14400        set_ignore_policy_content(&mut plan.operations[0], content);
14401        let migration_directory = root.path().join(MIGRATIONS_DIR).join(&plan.id);
14402        let plan_path = migration_directory.join("plan.json");
14403        fs::write(
14404            &plan_path,
14405            serde_json::to_vec_pretty(&plan).expect("tampered proposal"),
14406        )
14407        .unwrap();
14408        let policy_before = fs::read(&policy_path).unwrap();
14409        let plan_before = fs::read(&plan_path).unwrap();
14410
14411        let error = match approve_migration(plan) {
14412            Err(error) => error,
14413            Ok(_) => panic!("capture-incompatible policy must not be approved"),
14414        };
14415
14416        assert_invalid_ignore_policy(error);
14417        assert_eq!(fs::read(&policy_path).unwrap(), policy_before);
14418        assert_eq!(fs::read(&plan_path).unwrap(), plan_before);
14419        assert!(!migration_directory.join("snapshots").exists());
14420    }
14421
14422    fn assert_ignore_policy_apply_rejected(content: &str) {
14423        let root = initialized_structural_folderbase_fixture();
14424        let policy_path = root.path().join(".folderbaseignore");
14425        fs::write(&policy_path, b"node_modules/\n").unwrap();
14426        let plan = MigrationPlan::propose_structural(
14427            root.path(),
14428            vec![MigrationOperation::update_ignore_policy("Derived/\n")],
14429        )
14430        .unwrap();
14431        let migration_id = plan.id.clone();
14432        let mut approved = approve_migration(plan).unwrap();
14433        set_ignore_policy_content(&mut approved.plan.operations[0], content);
14434        let result_sha256 = sha256_bytes(content.as_bytes());
14435        match &mut approved.plan.operations[0] {
14436            MigrationOperation::UpdateIgnorePolicy {
14437                expected_result_sha256,
14438                ..
14439            } => *expected_result_sha256 = result_sha256,
14440            operation => panic!("unexpected operation: {operation:?}"),
14441        }
14442        approved.approval_digest = plan_digest(&approved.plan).unwrap();
14443        approved.plan.approval_digest = Some(approved.approval_digest.clone());
14444        persist_plan(&approved.plan).unwrap();
14445        let migration_directory = root.path().join(MIGRATIONS_DIR).join(migration_id);
14446        let plan_path = migration_directory.join("plan.json");
14447        let policy_before = fs::read(&policy_path).unwrap();
14448        let plan_before = fs::read(&plan_path).unwrap();
14449
14450        let error = match apply_migration(approved) {
14451            Err(error) => error,
14452            Ok(_) => panic!("capture-incompatible policy must not be applied"),
14453        };
14454
14455        assert_invalid_ignore_policy(error);
14456        assert_eq!(fs::read(&policy_path).unwrap(), policy_before);
14457        assert_eq!(fs::read(&plan_path).unwrap(), plan_before);
14458        assert!(!migration_directory.join("result.json").exists());
14459    }
14460
14461    fn set_ignore_policy_content(operation: &mut MigrationOperation, content: &str) {
14462        match operation {
14463            MigrationOperation::UpdateIgnorePolicy {
14464                content: proposed, ..
14465            } => proposed.clone_from(&content.to_owned()),
14466            operation => panic!("unexpected operation: {operation:?}"),
14467        }
14468    }
14469
14470    fn assert_invalid_ignore_policy(error: FolderbaseError) {
14471        assert!(
14472            matches!(
14473                error,
14474                FolderbaseError::InvalidRecord {
14475                    ref message,
14476                    ..
14477                } if message.contains("ignore policy")
14478            ),
14479            "{error:?}"
14480        );
14481    }
14482
14483    fn snapshot_regular_files(root: &Path) -> BTreeMap<PathBuf, Vec<u8>> {
14484        fn collect(root: &Path, directory: &Path, files: &mut BTreeMap<PathBuf, Vec<u8>>) {
14485            for entry in fs::read_dir(directory).unwrap() {
14486                let entry = entry.unwrap();
14487                let path = entry.path();
14488                let metadata = fs::symlink_metadata(&path).unwrap();
14489                if metadata.is_dir() && !metadata.file_type().is_symlink() {
14490                    collect(root, &path, files);
14491                } else if metadata.is_file() && !metadata.file_type().is_symlink() {
14492                    files.insert(
14493                        path.strip_prefix(root).unwrap().to_path_buf(),
14494                        fs::read(path).unwrap(),
14495                    );
14496                }
14497            }
14498        }
14499
14500        let mut files = BTreeMap::new();
14501        collect(root, root, &mut files);
14502        files
14503    }
14504
14505    #[test]
14506    fn protocol_upgrade_serializes_behind_existing_folderbase_migration_apply() {
14507        let root = legacy_structural_folderbase_fixture();
14508        fs::create_dir(root.path().join("Archive")).unwrap();
14509        fs::write(root.path().join("notes.md"), b"source\n").unwrap();
14510        let upgrade = crate::protocol_upgrade::plan_protocol_upgrade(root.path()).unwrap();
14511        let migration = MigrationPlan::propose_structural(
14512            root.path(),
14513            vec![MigrationOperation::move_object(
14514                "notes.md",
14515                "Archive/notes.md",
14516            )],
14517        )
14518        .unwrap();
14519        let approved = approve_migration(migration).unwrap();
14520        let (paused_sender, paused_receiver) = mpsc::sync_channel(0);
14521        let (resume_sender, resume_receiver) = mpsc::sync_channel(0);
14522
14523        let apply = thread::spawn(move || {
14524            apply_migration_with_hook(approved, |checkpoint| {
14525                if checkpoint == ApplyCheckpoint::JournalPrepared {
14526                    paused_sender.send(()).unwrap();
14527                    resume_receiver.recv().unwrap();
14528                }
14529            })
14530        });
14531        if paused_receiver.recv().is_err() {
14532            panic!(
14533                "migration stopped before the lock checkpoint: {:?}",
14534                apply.join().unwrap()
14535            );
14536        }
14537
14538        let lock_path = root.path().join(".folderbase/locks/transactions.lock");
14539        let transaction_is_locked = fs::OpenOptions::new()
14540            .read(true)
14541            .write(true)
14542            .open(&lock_path)
14543            .and_then(|file| match file.try_lock() {
14544                Err(std::fs::TryLockError::WouldBlock) => Ok(()),
14545                Err(std::fs::TryLockError::Error(source)) => Err(source),
14546                Ok(()) => {
14547                    let _ = file.unlock();
14548                    Err(io::Error::other(
14549                        "migration did not hold the transaction lock",
14550                    ))
14551                }
14552            })
14553            .is_ok();
14554
14555        resume_sender.send(()).unwrap();
14556        assert_eq!(
14557            apply.join().unwrap().unwrap().state,
14558            MigrationState::Verified
14559        );
14560        assert!(
14561            transaction_is_locked,
14562            "an existing-Folderbase migration must exclude protocol activation for its full apply"
14563        );
14564        crate::protocol_upgrade::apply_protocol_upgrade(&upgrade, upgrade.plan_digest()).unwrap();
14565    }
14566
14567    #[cfg(unix)]
14568    #[test]
14569    fn migration_apply_never_publishes_a_lock_into_a_replacement_root_after_detection() {
14570        let root = legacy_structural_folderbase_fixture();
14571        fs::create_dir(root.path().join("Archive")).unwrap();
14572        fs::write(root.path().join("notes.md"), b"source\n").unwrap();
14573        let migration = MigrationPlan::propose_structural(
14574            root.path(),
14575            vec![MigrationOperation::move_object(
14576                "notes.md",
14577                "Archive/notes.md",
14578            )],
14579        )
14580        .unwrap();
14581        let approved = approve_migration(migration).unwrap();
14582        let visible_root = root.path().to_path_buf();
14583        let detached_root =
14584            visible_root.with_file_name(format!(".folderbase-detached-{}", Uuid::now_v7()));
14585
14586        let result = apply_migration_with_hook(approved, |checkpoint| {
14587            if checkpoint == ApplyCheckpoint::ExistingFolderbaseDetected {
14588                fs::rename(&visible_root, &detached_root).unwrap();
14589                fs::create_dir(&visible_root).unwrap();
14590                fs::create_dir(visible_root.join(".folderbase")).unwrap();
14591            }
14592        });
14593        let foreign_state_is_empty = fs::read_dir(visible_root.join(".folderbase"))
14594            .unwrap()
14595            .next()
14596            .is_none();
14597        fs::remove_dir_all(&visible_root).unwrap();
14598        fs::rename(&detached_root, &visible_root).unwrap();
14599
14600        assert!(
14601            result.is_err(),
14602            "the replaced root must lose apply authority"
14603        );
14604        assert!(
14605            foreign_state_is_empty,
14606            "migration detection must not publish protocol state into a foreign replacement root"
14607        );
14608    }
14609
14610    #[cfg(unix)]
14611    #[test]
14612    fn migration_apply_never_mutates_a_replacement_root_after_authority_is_bound() {
14613        let root = legacy_structural_folderbase_fixture();
14614        fs::create_dir(root.path().join("Archive")).unwrap();
14615        fs::write(root.path().join("notes.md"), b"source\n").unwrap();
14616        let plan = MigrationPlan::propose_structural(
14617            root.path(),
14618            vec![MigrationOperation::move_object(
14619                "notes.md",
14620                "Archive/notes.md",
14621            )],
14622        )
14623        .unwrap();
14624        let approved = approve_migration(plan).unwrap();
14625        let visible_root = root.path().to_path_buf();
14626        let detached_root =
14627            visible_root.with_file_name(format!(".folderbase-detached-{}", Uuid::now_v7()));
14628
14629        let result = apply_migration_with_hook(approved, |checkpoint| {
14630            if checkpoint == ApplyCheckpoint::MutationAuthorityBound {
14631                fs::rename(&visible_root, &detached_root).unwrap();
14632                copy_directory_tree(&detached_root, &visible_root);
14633            }
14634        });
14635        let foreign_source = fs::read(visible_root.join("notes.md")).ok();
14636        let foreign_destination = fs::read(visible_root.join("Archive/notes.md")).ok();
14637        fs::remove_dir_all(&visible_root).unwrap();
14638        fs::rename(&detached_root, &visible_root).unwrap();
14639
14640        assert_eq!(result.unwrap().state, MigrationState::Verified);
14641        assert_eq!(
14642            foreign_source.as_deref(),
14643            Some(b"source\n".as_slice()),
14644            "apply must not remove a file from the foreign replacement"
14645        );
14646        assert_eq!(
14647            foreign_destination, None,
14648            "apply must not publish a file into the foreign replacement"
14649        );
14650    }
14651
14652    #[cfg(unix)]
14653    fn copy_directory_tree(source: &Path, destination: &Path) {
14654        fs::create_dir(destination).unwrap();
14655        for entry in fs::read_dir(source).unwrap() {
14656            let entry = entry.unwrap();
14657            let source_path = entry.path();
14658            let destination_path = destination.join(entry.file_name());
14659            let file_type = entry.file_type().unwrap();
14660            if file_type.is_dir() {
14661                copy_directory_tree(&source_path, &destination_path);
14662            } else if file_type.is_file() {
14663                fs::copy(&source_path, &destination_path).unwrap();
14664            } else {
14665                panic!("race fixture contains an unsupported filesystem object");
14666            }
14667        }
14668    }
14669
14670    #[allow(dead_code)]
14671    fn migration_fixture() -> TempDir {
14672        let root = tempfile::tempdir().unwrap();
14673        fs::create_dir(root.path().join("Client-Shared")).unwrap();
14674        fs::write(root.path().join("README.md"), "source\n").unwrap();
14675        fs::write(root.path().join("Client-Shared/Overview.md"), "client\n").unwrap();
14676        root
14677    }
14678
14679    fn initialized_structural_folderbase_fixture() -> TempDir {
14680        let root = tempfile::tempdir().unwrap();
14681        let initialization = crate::initialization::plan_initialization(
14682            root.path(),
14683            InitializationOptions {
14684                name: Some("Structural Recovery Test Folderbase".to_owned()),
14685                kind: FolderbaseKind::Project,
14686                create_agent_adapters: true,
14687            },
14688        )
14689        .unwrap();
14690        crate::initialization::initialize(&initialization).unwrap();
14691        root
14692    }
14693
14694    fn legacy_structural_folderbase_fixture() -> TempDir {
14695        let root = initialized_structural_folderbase_fixture();
14696        fs::write(
14697            root.path().join(".folderbase/manifest.json"),
14698            LEGACY_MANIFEST,
14699        )
14700        .unwrap();
14701        fs::write(
14702            root.path().join("FOLDERBASE.md"),
14703            b"# Legacy Folderbase\n\n## Purpose\nTest migration serialization.\n\n## Current state\nReady.\n\n## Navigate\nUse ordinary files.\n\n## Operating rules\nPreserve bytes.\n\n## Unresolved work\nNone.\n",
14704        )
14705        .unwrap();
14706        fs::write(root.path().join(".folderbaseignore"), b"node_modules/\n").unwrap();
14707        root
14708    }
14709
14710    #[allow(dead_code)]
14711    fn typed_answers(analysis: &MigrationAnalysis) -> Vec<MigrationAnswer> {
14712        analysis
14713            .questions
14714            .iter()
14715            .map(|question| MigrationAnswer {
14716                question_id: question.id.clone(),
14717                answer: question.recommended_option_id.clone(),
14718                exceptions: Vec::new(),
14719            })
14720            .collect()
14721    }
14722}