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 pub fn approval_digest(&self) -> Option<&str> {
334 self.approval_digest.as_deref()
335 }
336
337 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 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 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 ¤t[..*begin],
1464 managed,
1465 ¤t[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#[derive(Debug)]
1562pub struct ApprovedMigration {
1563 plan: MigrationPlan,
1564 approval_digest: String,
1565}
1566
1567impl ApprovedMigration {
1568 pub fn approval_digest(&self) -> &str {
1570 &self.approval_digest
1571 }
1572
1573 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#[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 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
1691pub 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
1959pub 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
2150pub 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
2689pub 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 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(¤t, &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, ¤t)?;
4534 let retained_parents =
4535 transaction
4536 .program
4537 .retain_step_parents(filesystem, operation_index, ¤t)?;
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 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, ¤t)?;
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, ¤t)?;
5396 let retained_parents =
5397 transaction
5398 .program
5399 .retain_step_parents(filesystem, operation_index, ¤t)?;
5400 let validate_authority = |transaction: &PreparedTransactionV1| {
5401 validate_transaction_v1_environment(filesystem, transaction, ¤t)?;
5402 transaction
5403 .program
5404 .validate_step_parents(filesystem, operation_index, ¤t)
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, ¤t)?;
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, ¤t)
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 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, ¤t, 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
9749impl 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 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 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
9989pub 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, ¤t_display)
11232 .map_err(|error| FolderbaseError::io(¤t_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 drop(final_destination);
11368 drop(destination.identity);
11369 drop(source.identity);
11370 }
11371 #[cfg(not(windows))]
11372 {
11373 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 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(¤t)
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 ¤t_analysis.files,
13782 ¤t_analysis.reconstructable_trees,
13783 ¤t_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(¤t_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(¤t_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(¤t)? != 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(¤t)? != 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 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}