Skip to main content

folderbase_core/
local_versions.rs

1//! Immutable local content versions and the append-only object journal.
2//!
3//! The journal is the durable history of accepted operations. Object metadata
4//! is a current-state projection that can be rebuilt from that history. Version
5//! records and content blobs are installed with no-clobber semantics and are
6//! never rewritten.
7
8use std::{
9    collections::BTreeMap,
10    fmt::Write as _,
11    fs::{self, File, OpenOptions},
12    io::{Read, Write},
13    path::{Component, Path, PathBuf},
14};
15
16use chrono::Utc;
17use serde::{Deserialize, Serialize};
18use serde_json::Value;
19use sha2::{Digest, Sha256};
20use uuid::Uuid;
21
22use crate::{
23    FolderbaseError, Result,
24    folderbase_state::FolderbaseState,
25    workspace::{
26        canonical_folderbase_root, has_nested_folderbase_marker, is_reserved_workspace_component,
27        refuse_generic_workspace_mutation_path, resolve_existing_workspace_file,
28    },
29};
30
31const OBJECT_SCHEMA: &str = "https://folderbase.ai/protocol/0.1/object.schema.json";
32const OBJECTS_DIRECTORY: &str = ".folderbase/objects";
33const VERSION_RECORDS_DIRECTORY: &str = ".folderbase/versions/records";
34const BLOBS_DIRECTORY: &str = ".folderbase/versions/blobs/sha256";
35const JOURNAL_PATH: &str = ".folderbase/journal/objects.ndjson";
36const JOURNAL_QUARANTINE_DIRECTORY: &str = ".folderbase/journal/quarantine";
37const TRANSACTIONS_DIRECTORY: &str = ".folderbase/transactions";
38const LOCKS_DIRECTORY: &str = ".folderbase/locks";
39const TRANSACTION_LOCK_PATH: &str = ".folderbase/locks/transactions.lock";
40const COPY_BUFFER_BYTES: usize = 64 * 1024;
41const MAX_CAPTURE_PROJECTION_RECORD_BYTES: u64 = 1024 * 1024;
42const PATH_IDENTITIES_DIRECTORY: &str = ".folderbase/local/path-identities";
43const HISTORY_TRANSFER_INTENTS_DIRECTORY: &str = ".folderbase/history-transfers/intents";
44const HISTORY_TRANSFER_OUTGOING_DIRECTORY: &str = ".folderbase/history-transfers/outgoing";
45const HISTORY_TRANSFER_INCOMING_DIRECTORY: &str = ".folderbase/history-transfers/incoming";
46const HISTORY_TRANSFER_STAGING_DIRECTORY: &str = ".folderbase/history-transfers/staging";
47
48/// A stable object identity that does not depend on the object's current path.
49#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
50#[serde(transparent)]
51pub struct ObjectId(String);
52
53impl ObjectId {
54    pub fn as_str(&self) -> &str {
55        &self.0
56    }
57
58    pub(crate) fn new() -> Self {
59        Self(format!("obj_{}", Uuid::now_v7()))
60    }
61
62    fn validate(&self, record_path: &Path) -> Result<()> {
63        validate_prefixed_uuid(&self.0, "obj_", record_path)
64    }
65
66    pub fn parse(value: impl Into<String>) -> Result<Self> {
67        let value = Self(value.into());
68        value.validate(Path::new("object-id"))?;
69        Ok(value)
70    }
71}
72
73impl std::fmt::Display for ObjectId {
74    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
75        formatter.write_str(&self.0)
76    }
77}
78
79/// The identity of one immutable capture of an object's bytes.
80#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
81#[serde(transparent)]
82pub struct VersionId(String);
83
84impl VersionId {
85    pub fn as_str(&self) -> &str {
86        &self.0
87    }
88
89    pub(crate) fn new() -> Self {
90        Self(format!("version_{}", Uuid::now_v7()))
91    }
92
93    fn validate(&self, record_path: &Path) -> Result<()> {
94        validate_prefixed_uuid(&self.0, "version_", record_path)
95    }
96
97    pub fn parse(value: impl Into<String>) -> Result<Self> {
98        let value = Self(value.into());
99        value.validate(Path::new("version-id"))?;
100        Ok(value)
101    }
102}
103
104impl std::fmt::Display for VersionId {
105    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
106        formatter.write_str(&self.0)
107    }
108}
109
110#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
111pub struct ObjectLifecycle {
112    pub status: String,
113    #[serde(flatten)]
114    pub extensions: BTreeMap<String, Value>,
115}
116
117#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
118pub struct ObjectProvenance {
119    pub created_at: String,
120    pub source: String,
121    #[serde(flatten)]
122    pub extensions: BTreeMap<String, Value>,
123}
124
125/// Current materialization metadata for a tracked object.
126///
127/// Unknown top-level and nested fields survive a read/modify/write cycle.
128#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
129pub struct LocalObjectRecord {
130    #[serde(rename = "$schema")]
131    pub schema: String,
132    pub id: ObjectId,
133    #[serde(rename = "type")]
134    pub object_type: String,
135    pub path: String,
136    pub lifecycle: ObjectLifecycle,
137    pub provenance: ObjectProvenance,
138    pub current_version: VersionId,
139    pub versions: Vec<VersionId>,
140    #[serde(flatten)]
141    pub extensions: BTreeMap<String, Value>,
142}
143
144#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
145pub struct ContentDigest {
146    pub algorithm: String,
147    pub digest: String,
148    pub bytes: u64,
149}
150
151/// Immutable metadata for one captured version.
152#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
153pub struct LocalVersionRecord {
154    pub id: VersionId,
155    pub object_id: ObjectId,
156    pub content: ContentDigest,
157    pub captured_at: String,
158    #[serde(flatten)]
159    pub extensions: BTreeMap<String, Value>,
160}
161
162#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
163pub enum JournalAction {
164    #[serde(rename = "object.tracked")]
165    ObjectTracked,
166    #[serde(rename = "object.relocated")]
167    ObjectRelocated,
168    #[serde(rename = "version.captured")]
169    VersionCaptured,
170    #[serde(rename = "version.restored")]
171    VersionRestored,
172}
173
174/// One append-only journal line.
175#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
176pub struct ObjectJournalEvent {
177    pub id: String,
178    pub at: String,
179    pub action: JournalAction,
180    pub object_id: ObjectId,
181    pub path: String,
182    #[serde(skip_serializing_if = "Option::is_none")]
183    pub previous_path: Option<String>,
184    #[serde(skip_serializing_if = "Option::is_none")]
185    pub version_id: Option<VersionId>,
186    #[serde(skip_serializing_if = "Option::is_none")]
187    pub content: Option<ContentDigest>,
188}
189
190#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
191pub struct CaptureResult {
192    pub object: LocalObjectRecord,
193    pub version: LocalVersionRecord,
194    pub object_created: bool,
195    pub version_created: bool,
196}
197
198#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
199pub struct RestoreResult {
200    pub object_id: ObjectId,
201    pub version_id: VersionId,
202    pub path: PathBuf,
203    pub content: ContentDigest,
204}
205
206#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
207#[serde(rename_all = "snake_case")]
208pub enum HistoryTransferState {
209    Proposed,
210    Approved,
211    Applying,
212    DestinationVerified,
213    SourceReleased,
214    Verified,
215    Conflicted,
216}
217
218#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
219pub struct HistoryTransferPlan {
220    protocol_version: String,
221    id: String,
222    source_root: PathBuf,
223    destination_root: PathBuf,
224    source_folderbase_id: String,
225    destination_folderbase_id: String,
226    source_manifest_sha256: String,
227    destination_manifest_sha256: String,
228    object: LocalObjectRecord,
229    destination_path: String,
230    versions: Vec<LocalVersionRecord>,
231    state: HistoryTransferState,
232    #[serde(default, skip_serializing_if = "Option::is_none")]
233    approval_digest: Option<String>,
234}
235
236impl HistoryTransferPlan {
237    pub fn id(&self) -> &str {
238        &self.id
239    }
240
241    pub fn state(&self) -> HistoryTransferState {
242        self.state
243    }
244
245    pub fn source_folderbase_id(&self) -> &str {
246        &self.source_folderbase_id
247    }
248
249    pub fn destination_folderbase_id(&self) -> &str {
250        &self.destination_folderbase_id
251    }
252
253    pub fn object_id(&self) -> &ObjectId {
254        &self.object.id
255    }
256
257    pub fn version_ids(&self) -> impl Iterator<Item = &VersionId> {
258        self.versions.iter().map(|version| &version.id)
259    }
260}
261
262#[derive(Debug)]
263pub struct ApprovedHistoryTransfer {
264    plan: HistoryTransferPlan,
265    approval_digest: String,
266}
267
268#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
269pub struct HistoryTransferResult {
270    pub transfer_id: String,
271    pub source_folderbase_id: String,
272    pub destination_folderbase_id: String,
273    pub object_id: ObjectId,
274    pub state: HistoryTransferState,
275    pub version_ids: Vec<VersionId>,
276}
277
278#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
279struct HistoryTransferReceipt {
280    protocol_version: String,
281    transfer_id: String,
282    source_folderbase_id: String,
283    destination_folderbase_id: String,
284    object_id: ObjectId,
285    approval_digest: String,
286    version_ids: Vec<VersionId>,
287}
288
289#[derive(Debug, Clone, Copy, PartialEq, Eq)]
290enum HistoryTransferCheckpoint {
291    Applying,
292    DestinationStaged,
293    DestinationVerified,
294    SourceReceiptWritten,
295    SourceReleased,
296    IncomingReceiptWritten,
297    DestinationActivated,
298    Verified,
299}
300
301/// Durable intent for a projection change.
302///
303/// The immutable blob is installed before this record. Once this record is
304/// durable, every remaining step is idempotent: install the immutable version
305/// record, replace the derived object projection, append missing journal
306/// events, and remove the intent. A later write replays any intent left behind
307/// by an interrupted process.
308#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
309struct PendingTransaction {
310    protocol_version: String,
311    id: String,
312    version: Option<LocalVersionRecord>,
313    #[serde(default, skip_serializing_if = "Vec::is_empty")]
314    versions: Vec<LocalVersionRecord>,
315    object: LocalObjectRecord,
316    #[serde(default, skip_serializing_if = "Option::is_none")]
317    restore: Option<PendingRestore>,
318    #[serde(default, skip_serializing_if = "Option::is_none")]
319    replacement: Option<PendingReplacement>,
320    events: Vec<ObjectJournalEvent>,
321}
322
323#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
324struct PendingRestore {
325    version_id: VersionId,
326    destination: String,
327    content: ContentDigest,
328}
329
330#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
331struct PendingReplacement {
332    destination: String,
333    previous_content: ContentDigest,
334    content: ContentDigest,
335    readonly: bool,
336    #[serde(default, skip_serializing_if = "Option::is_none")]
337    unix_mode: Option<u32>,
338    #[serde(default, skip_serializing_if = "Option::is_none")]
339    file_identity: Option<FileSystemIdentity>,
340    #[serde(default, skip_serializing_if = "Option::is_none")]
341    parent_identity: Option<FileSystemIdentity>,
342}
343
344#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
345struct FileSystemIdentity {
346    device: u64,
347    inode: u64,
348}
349
350#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
351struct LocalPathIdentity {
352    object_id: ObjectId,
353    file_system: FileSystemIdentity,
354}
355
356#[derive(Debug, Clone)]
357pub(crate) struct VersionedReplaceResult {
358    pub object_id: ObjectId,
359    pub version_id: VersionId,
360    pub previous_content: ContentDigest,
361    pub content: ContentDigest,
362}
363
364pub(crate) struct StoreTransactionLock {
365    file: File,
366}
367
368struct FolderbaseIdentity {
369    id: String,
370    manifest_sha256: String,
371}
372
373impl Drop for StoreTransactionLock {
374    fn drop(&mut self) {
375        let _ = File::unlock(&self.file);
376    }
377}
378
379/// Filesystem-backed local version storage for one folderbase root.
380#[derive(Debug, Clone)]
381pub struct LocalVersionStore {
382    root: PathBuf,
383}
384
385impl LocalVersionStore {
386    /// Open a store rooted at an existing directory.
387    ///
388    /// Storage directories are created lazily by the first accepted write.
389    /// Reopening a store that already has a transaction directory replays
390    /// durable pending work and repairs an interrupted final journal append.
391    pub fn open(root: impl AsRef<Path>) -> Result<Self> {
392        let store = Self::open_read_only(root)?;
393        match fs::symlink_metadata(store.root.join(TRANSACTIONS_DIRECTORY)) {
394            Ok(metadata) if metadata.is_dir() && !metadata.file_type().is_symlink() => {
395                let _lock = store.acquire_transaction_lock()?;
396                store.ensure_store_layout()?;
397            }
398            Ok(_) => {
399                return Err(FolderbaseError::UnsafePath(
400                    store.root.join(TRANSACTIONS_DIRECTORY),
401                ));
402            }
403            Err(source) if source.kind() == std::io::ErrorKind::NotFound => {}
404            Err(source) => {
405                return Err(FolderbaseError::io(
406                    store.root.join(TRANSACTIONS_DIRECTORY),
407                    source,
408                ));
409            }
410        }
411        Ok(store)
412    }
413
414    /// Open without replaying or publishing state. Capture sealing uses this
415    /// after retaining its own no-follow state capability.
416    pub(crate) fn open_read_only(root: impl AsRef<Path>) -> Result<Self> {
417        let supplied = root.as_ref();
418        let root = canonical_folderbase_root(supplied)?;
419        Ok(Self { root })
420    }
421
422    pub fn root(&self) -> &Path {
423        &self.root
424    }
425
426    pub(crate) fn tracked_object_id(
427        &self,
428        relative_path: impl AsRef<Path>,
429    ) -> Result<Option<ObjectId>> {
430        let relative_path = safe_content_path(relative_path.as_ref())?;
431        self.find_object_by_path(&relative_path)
432            .map(|record| record.map(|record| record.id))
433    }
434
435    pub fn propose_history_transfer(
436        &self,
437        destination: &LocalVersionStore,
438        source_folderbase_id: &str,
439        destination_folderbase_id: &str,
440        object_id: &ObjectId,
441        destination_path: impl AsRef<Path>,
442    ) -> Result<HistoryTransferPlan> {
443        let source_identity = read_folderbase_identity(&self.root)?;
444        let destination_identity = read_folderbase_identity(&destination.root)?;
445        if source_identity.id != source_folderbase_id {
446            return Err(invalid_record(
447                self.root.join(".folderbase/manifest.json"),
448                "explicit source folderbase ID does not match the active manifest",
449            ));
450        }
451        if destination_identity.id != destination_folderbase_id {
452            return Err(invalid_record(
453                destination.root.join(".folderbase/manifest.json"),
454                "explicit destination folderbase ID does not match the active manifest",
455            ));
456        }
457        let nested_root = destination
458            .root
459            .strip_prefix(&self.root)
460            .map_err(|_| FolderbaseError::UnsafePath(destination.root.clone()))?;
461        let nested_root = safe_content_path(nested_root)?;
462        if !has_nested_folderbase_marker(&destination.root)? {
463            return Err(invalid_record(
464                &destination.root,
465                "history destination must be an active nested folderbase",
466            ));
467        }
468        let destination_path = safe_content_path(destination_path.as_ref())?;
469        let object = self.read_object_record_for_transfer(object_id)?;
470        if Path::new(&object.path) != nested_root.join(&destination_path) {
471            return Err(invalid_record(
472                self.object_record_path(object_id),
473                "tracked source path does not map to the requested nested-folderbase destination",
474            ));
475        }
476        let (materialized, canonical_destination_path) =
477            resolve_existing_workspace_file(&destination.root, &destination_path)?;
478        if canonical_destination_path != destination_path {
479            return Err(FolderbaseError::UnsafePath(destination_path));
480        }
481
482        if read_optional_file_nofollow(&destination.object_record_path(object_id))?.is_some()
483            || destination
484                .find_object_by_path(&canonical_destination_path)?
485                .is_some()
486        {
487            return Err(FolderbaseError::WouldOverwrite(
488                destination.object_record_path(object_id),
489            ));
490        }
491
492        let mut versions = Vec::with_capacity(object.versions.len());
493        for version_id in &object.versions {
494            let version = self.read_version_record(version_id)?;
495            if version.object_id != object.id {
496                return Err(invalid_record(
497                    self.version_record_path(version_id),
498                    "version belongs to a different object",
499                ));
500            }
501            verify_file_content(&self.blob_path(&version.content.digest), &version.content)?;
502            if let Some(bytes) =
503                read_optional_file_nofollow(&destination.version_record_path(version_id))?
504            {
505                let existing: LocalVersionRecord =
506                    serde_json::from_slice(&bytes).map_err(|source| {
507                        FolderbaseError::json(destination.version_record_path(version_id), source)
508                    })?;
509                if existing != version {
510                    return Err(FolderbaseError::WouldOverwrite(
511                        destination.version_record_path(version_id),
512                    ));
513                }
514            }
515            versions.push(version);
516        }
517        let current = versions
518            .iter()
519            .find(|version| version.id == object.current_version)
520            .ok_or_else(|| {
521                invalid_record(
522                    self.object_record_path(object_id),
523                    "current version is absent from transfer history",
524                )
525            })?;
526        verify_file_content(&materialized, &current.content)?;
527
528        let plan = HistoryTransferPlan {
529            protocol_version: "0.1.0".to_owned(),
530            id: format!("history_transfer_{}", Uuid::now_v7()),
531            source_root: self.root.clone(),
532            destination_root: destination.root.clone(),
533            source_folderbase_id: source_identity.id,
534            destination_folderbase_id: destination_identity.id,
535            source_manifest_sha256: source_identity.manifest_sha256,
536            destination_manifest_sha256: destination_identity.manifest_sha256,
537            object,
538            destination_path: relative_path_to_string(&destination_path)?,
539            versions,
540            state: HistoryTransferState::Proposed,
541            approval_digest: None,
542        };
543        ensure_directory_chain(&self.root, Path::new(HISTORY_TRANSFER_INTENTS_DIRECTORY))?;
544        write_json_new(&history_transfer_plan_path(&self.root, &plan.id), &plan)?;
545        Ok(plan)
546    }
547
548    fn read_object_record_for_transfer(&self, object_id: &ObjectId) -> Result<LocalObjectRecord> {
549        object_id.validate(&self.object_record_path(object_id))?;
550        let path = self.object_record_path(object_id);
551        let record: LocalObjectRecord = read_json(&path)?;
552        if record.id != *object_id
553            || record.versions.is_empty()
554            || !record.versions.contains(&record.current_version)
555        {
556            return Err(invalid_record(
557                path,
558                "object record is inconsistent for history transfer",
559            ));
560        }
561        safe_content_path(Path::new(&record.path))
562            .map_err(|_| invalid_record(path, "object record has an unsafe path"))?;
563        Ok(record)
564    }
565
566    /// Capture the current bytes of a regular file.
567    ///
568    /// Repeated captures at the same tracked path reuse the stable object ID.
569    /// Capturing unchanged bytes is idempotent and does not append a duplicate
570    /// version or journal event.
571    pub fn capture_file(&self, relative_path: impl AsRef<Path>) -> Result<CaptureResult> {
572        let relative_path = safe_content_path(relative_path.as_ref())?;
573        let _lock = self.acquire_transaction_lock()?;
574        self.ensure_store_layout()?;
575        let (materialized_path, relative_path) =
576            resolve_existing_workspace_file(&self.root, &relative_path)?;
577
578        let existing_object = self.find_object_by_path(&relative_path)?;
579        let object_created = existing_object.is_none();
580        let object_id = existing_object
581            .as_ref()
582            .map(|record| record.id.clone())
583            .unwrap_or_else(ObjectId::new);
584
585        let content = self.install_content_blob(&materialized_path)?;
586
587        if let Some(object) = existing_object.as_ref() {
588            let current = self.read_version(&object.current_version)?;
589            if current.content == content {
590                self.persist_canonical_object_path(object)?;
591                self.write_local_file_identity(&object.id, &materialized_path)?;
592                return Ok(CaptureResult {
593                    object: object.clone(),
594                    version: current,
595                    object_created: false,
596                    version_created: false,
597                });
598            }
599        }
600
601        let captured_at = Utc::now().to_rfc3339();
602        let version = LocalVersionRecord {
603            id: VersionId::new(),
604            object_id: object_id.clone(),
605            content: content.clone(),
606            captured_at: captured_at.clone(),
607            extensions: BTreeMap::new(),
608        };
609
610        let path_string = relative_path_to_string(&relative_path)?;
611        let object = match existing_object {
612            Some(mut record) => {
613                record.current_version = version.id.clone();
614                record.versions.push(version.id.clone());
615                record
616            }
617            None => LocalObjectRecord {
618                schema: OBJECT_SCHEMA.to_owned(),
619                id: object_id.clone(),
620                object_type: "file".to_owned(),
621                path: path_string.clone(),
622                lifecycle: ObjectLifecycle {
623                    status: "canonical".to_owned(),
624                    extensions: BTreeMap::new(),
625                },
626                provenance: ObjectProvenance {
627                    created_at: captured_at.clone(),
628                    source: "local".to_owned(),
629                    extensions: BTreeMap::new(),
630                },
631                current_version: version.id.clone(),
632                versions: vec![version.id.clone()],
633                extensions: BTreeMap::new(),
634            },
635        };
636
637        let mut events = Vec::with_capacity(if object_created { 2 } else { 1 });
638        if object_created {
639            events.push(ObjectJournalEvent {
640                id: format!("event_{}", Uuid::now_v7()),
641                at: captured_at.clone(),
642                action: JournalAction::ObjectTracked,
643                object_id: object_id.clone(),
644                path: path_string.clone(),
645                previous_path: None,
646                version_id: None,
647                content: None,
648            });
649        }
650        events.push(ObjectJournalEvent {
651            id: format!("event_{}", Uuid::now_v7()),
652            at: captured_at,
653            action: JournalAction::VersionCaptured,
654            object_id: object_id.clone(),
655            path: path_string,
656            previous_path: None,
657            version_id: Some(version.id.clone()),
658            content: Some(content),
659        });
660        self.commit_transaction(PendingTransaction {
661            protocol_version: "0.1.0".to_owned(),
662            id: format!("transaction_{}", Uuid::now_v7()),
663            version: Some(version.clone()),
664            versions: Vec::new(),
665            object: object.clone(),
666            restore: None,
667            replacement: None,
668            events,
669        })?;
670
671        Ok(CaptureResult {
672            object,
673            version,
674            object_created,
675            version_created: true,
676        })
677    }
678
679    pub(crate) fn replace_file_versioned(
680        &self,
681        relative_path: impl AsRef<Path>,
682        expected: &ContentDigest,
683        new_bytes: &[u8],
684    ) -> Result<VersionedReplaceResult> {
685        let relative_path = safe_content_path(relative_path.as_ref())?;
686        refuse_generic_workspace_mutation_path(&relative_path)?;
687        let _lock = self.acquire_transaction_lock()?;
688        self.ensure_store_layout()?;
689        let (materialized_path, relative_path) =
690            resolve_existing_workspace_file(&self.root, &relative_path)?;
691        refuse_generic_workspace_mutation_path(&relative_path)?;
692
693        let current_file = open_existing_nofollow(&materialized_path)?;
694        let metadata = current_file
695            .metadata()
696            .map_err(|source| FolderbaseError::io(&materialized_path, source))?;
697        let parent = materialized_path
698            .parent()
699            .ok_or_else(|| FolderbaseError::UnsafePath(materialized_path.clone()))?;
700        let parent_metadata =
701            fs::metadata(parent).map_err(|source| FolderbaseError::io(parent, source))?;
702        let current_content = hash_reader(current_file, &materialized_path)?;
703        if current_content != *expected {
704            return Err(FolderbaseError::WorkspaceContentChanged(relative_path));
705        }
706        let captured_current = self.install_content_blob(&materialized_path)?;
707        if captured_current != current_content {
708            return Err(FolderbaseError::WorkspaceContentChanged(relative_path));
709        }
710        let next_content = self.install_content_bytes(new_bytes)?;
711
712        let existing_object = self.find_object_by_path(&relative_path)?;
713        let object_created = existing_object.is_none();
714        let object_id = existing_object
715            .as_ref()
716            .map(|object| object.id.clone())
717            .unwrap_or_else(ObjectId::new);
718        let at = Utc::now().to_rfc3339();
719        let mut pending_versions = Vec::new();
720
721        let previous_version = match existing_object.as_ref() {
722            Some(object) => {
723                let current = self.read_version(&object.current_version)?;
724                if current.content == current_content {
725                    current
726                } else {
727                    let version = LocalVersionRecord {
728                        id: VersionId::new(),
729                        object_id: object_id.clone(),
730                        content: current_content.clone(),
731                        captured_at: at.clone(),
732                        extensions: BTreeMap::new(),
733                    };
734                    pending_versions.push(version.clone());
735                    version
736                }
737            }
738            None => {
739                let version = LocalVersionRecord {
740                    id: VersionId::new(),
741                    object_id: object_id.clone(),
742                    content: current_content.clone(),
743                    captured_at: at.clone(),
744                    extensions: BTreeMap::new(),
745                };
746                pending_versions.push(version.clone());
747                version
748            }
749        };
750
751        let next_version = if next_content == current_content {
752            previous_version.clone()
753        } else {
754            let version = LocalVersionRecord {
755                id: VersionId::new(),
756                object_id: object_id.clone(),
757                content: next_content.clone(),
758                captured_at: at.clone(),
759                extensions: BTreeMap::new(),
760            };
761            pending_versions.push(version.clone());
762            version
763        };
764
765        if pending_versions.is_empty() {
766            return Ok(VersionedReplaceResult {
767                object_id,
768                version_id: next_version.id,
769                previous_content: current_content,
770                content: next_content,
771            });
772        }
773
774        let path_string = relative_path_to_string(&relative_path)?;
775        let mut object = existing_object.unwrap_or_else(|| LocalObjectRecord {
776            schema: OBJECT_SCHEMA.to_owned(),
777            id: object_id.clone(),
778            object_type: "file".to_owned(),
779            path: path_string.clone(),
780            lifecycle: ObjectLifecycle {
781                status: "canonical".to_owned(),
782                extensions: BTreeMap::new(),
783            },
784            provenance: ObjectProvenance {
785                created_at: at.clone(),
786                source: "local".to_owned(),
787                extensions: BTreeMap::new(),
788            },
789            current_version: previous_version.id.clone(),
790            versions: Vec::new(),
791            extensions: BTreeMap::new(),
792        });
793        for version in &pending_versions {
794            if !object.versions.contains(&version.id) {
795                object.versions.push(version.id.clone());
796            }
797        }
798        object.current_version = next_version.id.clone();
799
800        let mut events = Vec::new();
801        if object_created {
802            events.push(ObjectJournalEvent {
803                id: format!("event_{}", Uuid::now_v7()),
804                at: at.clone(),
805                action: JournalAction::ObjectTracked,
806                object_id: object_id.clone(),
807                path: path_string.clone(),
808                previous_path: None,
809                version_id: None,
810                content: None,
811            });
812        }
813        events.extend(pending_versions.iter().map(|version| ObjectJournalEvent {
814            id: format!("event_{}", Uuid::now_v7()),
815            at: at.clone(),
816            action: JournalAction::VersionCaptured,
817            object_id: object_id.clone(),
818            path: path_string.clone(),
819            previous_path: None,
820            version_id: Some(version.id.clone()),
821            content: Some(version.content.clone()),
822        }));
823
824        #[cfg(unix)]
825        let unix_mode = {
826            use std::os::unix::fs::PermissionsExt;
827            Some(metadata.permissions().mode())
828        };
829        #[cfg(not(unix))]
830        let unix_mode = None;
831
832        self.commit_transaction(PendingTransaction {
833            protocol_version: "0.1.0".to_owned(),
834            id: format!("transaction_{}", Uuid::now_v7()),
835            version: None,
836            versions: pending_versions,
837            object,
838            restore: None,
839            replacement: (next_content != current_content).then(|| PendingReplacement {
840                destination: path_string,
841                previous_content: current_content.clone(),
842                content: next_content.clone(),
843                readonly: metadata.permissions().readonly(),
844                unix_mode,
845                file_identity: filesystem_identity(&metadata),
846                parent_identity: filesystem_identity(&parent_metadata),
847            }),
848            events,
849        })?;
850
851        Ok(VersionedReplaceResult {
852            object_id,
853            version_id: next_version.id,
854            previous_content: current_content,
855            content: next_content,
856        })
857    }
858
859    /// Rebind an object to a file that has already moved on disk.
860    ///
861    /// This does not move user content. It records the externally completed
862    /// path change while preserving object and version identity.
863    pub fn record_path_change(
864        &self,
865        object_id: &ObjectId,
866        new_relative_path: impl AsRef<Path>,
867    ) -> Result<LocalObjectRecord> {
868        let new_relative_path = safe_content_path(new_relative_path.as_ref())?;
869        let _lock = self.acquire_transaction_lock()?;
870        self.ensure_store_layout()?;
871        let (new_materialized_path, new_relative_path) =
872            resolve_existing_workspace_file(&self.root, &new_relative_path)?;
873
874        let mut object = self.read_object(object_id)?;
875        let new_path = relative_path_to_string(&new_relative_path)?;
876        if object.path == new_path {
877            return Ok(object);
878        }
879
880        let old_relative_path = safe_content_path(Path::new(&object.path))?;
881        match resolve_existing_workspace_file(&self.root, &old_relative_path) {
882            Ok((old_materialized_path, _)) if old_materialized_path != new_materialized_path => {
883                return Err(invalid_record(
884                    self.object_record_path(object_id),
885                    format!(
886                        "tracked path {} still exists; record a path change only after moving it",
887                        object.path
888                    ),
889                ));
890            }
891            Ok(_) => {}
892            Err(FolderbaseError::Io { source, .. })
893                if source.kind() == std::io::ErrorKind::NotFound => {}
894            Err(error) => return Err(error),
895        }
896
897        let current_version = self.read_version(&object.current_version)?;
898        let expected_identity = self.read_local_file_identity(object_id)?.ok_or_else(|| {
899            invalid_record(
900                self.path_identity_path(object_id),
901                "tracked object has no local file identity; capture it again before relocating",
902            )
903        })?;
904        let destination_file = open_existing_nofollow(&new_materialized_path)?;
905        let destination_metadata = destination_file
906            .metadata()
907            .map_err(|source| FolderbaseError::io(&new_materialized_path, source))?;
908        if filesystem_identity(&destination_metadata).as_ref() != Some(&expected_identity) {
909            return Err(FolderbaseError::WorkspaceContentChanged(new_relative_path));
910        }
911        let current_content = hash_reader(destination_file, &new_materialized_path)?;
912        if current_content != current_version.content {
913            return Err(FolderbaseError::WorkspaceContentChanged(new_relative_path));
914        }
915
916        if let Some(other) = self.find_object_by_path(&new_relative_path)?
917            && other.id != *object_id
918        {
919            return Err(invalid_record(
920                self.object_record_path(&other.id),
921                format!("path {new_path} is already assigned to {}", other.id),
922            ));
923        }
924
925        let previous_path = std::mem::replace(&mut object.path, new_path.clone());
926        self.commit_transaction(PendingTransaction {
927            protocol_version: "0.1.0".to_owned(),
928            id: format!("transaction_{}", Uuid::now_v7()),
929            version: None,
930            versions: Vec::new(),
931            object: object.clone(),
932            restore: None,
933            replacement: None,
934            events: vec![ObjectJournalEvent {
935                id: format!("event_{}", Uuid::now_v7()),
936                at: Utc::now().to_rfc3339(),
937                action: JournalAction::ObjectRelocated,
938                object_id: object_id.clone(),
939                path: new_path,
940                previous_path: Some(previous_path),
941                version_id: Some(object.current_version.clone()),
942                content: None,
943            }],
944        })?;
945        Ok(object)
946    }
947
948    /// Restore one immutable version to a new relative path.
949    ///
950    /// Existing destinations are never overwritten. The blob is verified
951    /// before and after installation, and the destination never shares an
952    /// inode with the immutable blob.
953    pub fn restore_version(
954        &self,
955        version_id: &VersionId,
956        destination: impl AsRef<Path>,
957    ) -> Result<RestoreResult> {
958        let destination = safe_content_path(destination.as_ref())?;
959        let _lock = self.acquire_transaction_lock()?;
960        self.ensure_store_layout()?;
961        let version = self.read_version(version_id)?;
962        let blob_path = self.blob_path(&version.content.digest);
963        verify_file_content(&blob_path, &version.content)?;
964
965        let (_, destination) = self.prepare_new_destination(&destination)?;
966        let path_string = relative_path_to_string(&destination)?;
967        let object = self.read_object(&version.object_id)?;
968        self.commit_transaction(PendingTransaction {
969            protocol_version: "0.1.0".to_owned(),
970            id: format!("transaction_{}", Uuid::now_v7()),
971            version: None,
972            versions: Vec::new(),
973            object,
974            restore: Some(PendingRestore {
975                version_id: version.id.clone(),
976                destination: path_string.clone(),
977                content: version.content.clone(),
978            }),
979            replacement: None,
980            events: vec![ObjectJournalEvent {
981                id: format!("event_{}", Uuid::now_v7()),
982                at: Utc::now().to_rfc3339(),
983                action: JournalAction::VersionRestored,
984                object_id: version.object_id.clone(),
985                path: path_string,
986                previous_path: None,
987                version_id: Some(version.id.clone()),
988                content: Some(version.content.clone()),
989            }],
990        })?;
991
992        Ok(RestoreResult {
993            object_id: version.object_id,
994            version_id: version.id,
995            path: destination,
996            content: version.content,
997        })
998    }
999
1000    pub fn read_object(&self, object_id: &ObjectId) -> Result<LocalObjectRecord> {
1001        let path = self.object_record_path(object_id);
1002        object_id.validate(&path)?;
1003        self.deny_if_transferred_out(object_id)?;
1004        let record: LocalObjectRecord = read_json(&path)?;
1005        self.validate_object_record(object_id, &record, &path)?;
1006        Ok(record)
1007    }
1008
1009    pub(crate) fn read_capture_object_projection_in(
1010        &self,
1011        state: &FolderbaseState,
1012        object_id: &ObjectId,
1013    ) -> Result<Option<LocalObjectRecord>> {
1014        let path = self.object_record_path(object_id);
1015        object_id.validate(&path)?;
1016        let Some(bytes) = state.read_bounded(
1017            &self.object_record_relative_path(object_id),
1018            MAX_CAPTURE_PROJECTION_RECORD_BYTES,
1019        )?
1020        else {
1021            return Ok(None);
1022        };
1023        let record: LocalObjectRecord = serde_json::from_slice(&bytes)
1024            .map_err(|source| FolderbaseError::json(&path, source))?;
1025        self.validate_object_record(object_id, &record, &path)?;
1026        Ok(Some(record))
1027    }
1028
1029    fn validate_object_record(
1030        &self,
1031        object_id: &ObjectId,
1032        record: &LocalObjectRecord,
1033        path: &Path,
1034    ) -> Result<()> {
1035        let relative_path = self.validate_object_record_membership(object_id, record, path)?;
1036        self.ensure_path_within_current_folderbase_boundary(&relative_path)
1037    }
1038
1039    fn validate_object_record_membership(
1040        &self,
1041        object_id: &ObjectId,
1042        record: &LocalObjectRecord,
1043        path: &Path,
1044    ) -> Result<PathBuf> {
1045        object_id.validate(path)?;
1046        record.id.validate(path)?;
1047        if record.id != *object_id {
1048            return Err(invalid_record(
1049                path.to_path_buf(),
1050                "object ID does not match its filename",
1051            ));
1052        }
1053        let relative_path = safe_content_path(Path::new(&record.path)).map_err(|_| {
1054            invalid_record(
1055                path.to_path_buf(),
1056                "object path is not a safe relative path",
1057            )
1058        })?;
1059        self.ensure_path_within_current_folderbase_boundary(&relative_path)?;
1060        if record.versions.is_empty() || !record.versions.contains(&record.current_version) {
1061            return Err(invalid_record(
1062                path.to_path_buf(),
1063                "current version is absent from the object version history",
1064            ));
1065        }
1066        Ok(relative_path)
1067    }
1068
1069    pub fn read_version(&self, version_id: &VersionId) -> Result<LocalVersionRecord> {
1070        let record = self.read_version_record(version_id)?;
1071        let object = self.read_object(&record.object_id)?;
1072        if !object.versions.contains(version_id) {
1073            return Err(invalid_record(
1074                self.version_record_path(version_id),
1075                "version is absent from its object's version history",
1076            ));
1077        }
1078        Ok(record)
1079    }
1080
1081    pub(crate) fn read_version_record(&self, version_id: &VersionId) -> Result<LocalVersionRecord> {
1082        let path = self.version_record_path(version_id);
1083        version_id.validate(&path)?;
1084        let record: LocalVersionRecord = read_json(&path)?;
1085        self.validate_version_record(version_id, &record, &path)?;
1086        Ok(record)
1087    }
1088
1089    fn validate_version_record(
1090        &self,
1091        version_id: &VersionId,
1092        record: &LocalVersionRecord,
1093        path: &Path,
1094    ) -> Result<()> {
1095        version_id.validate(path)?;
1096        record.id.validate(path)?;
1097        record.object_id.validate(path)?;
1098        if record.id != *version_id {
1099            return Err(invalid_record(
1100                path.to_path_buf(),
1101                "version ID does not match its filename",
1102            ));
1103        }
1104        validate_content_digest(&record.content, path)
1105    }
1106
1107    pub(crate) fn validate_chunk_transfer_membership(
1108        &self,
1109        version_id: &VersionId,
1110        version: &LocalVersionRecord,
1111        object: &LocalObjectRecord,
1112    ) -> Result<PathBuf> {
1113        let version_path = self.version_record_path(version_id);
1114        self.validate_version_record(version_id, version, &version_path)?;
1115        let object_path = self.object_record_path(&version.object_id);
1116        let relative_path =
1117            self.validate_object_record_membership(&version.object_id, object, &object_path)?;
1118        if !object.versions.contains(version_id) {
1119            return Err(invalid_record(
1120                version_path,
1121                "version is absent from its object's version history",
1122            ));
1123        }
1124        Ok(relative_path)
1125    }
1126
1127    /// Read and validate every complete journal line.
1128    ///
1129    /// A final unterminated line is included when it is valid JSON. An invalid
1130    /// unterminated tail is treated as an interrupted append and ignored here;
1131    /// the next write quarantines it before replaying pending transactions.
1132    pub fn journal_events(&self) -> Result<Vec<ObjectJournalEvent>> {
1133        let _lock = self.acquire_transaction_lock()?;
1134        self.ensure_store_layout()?;
1135        let path = self.root.join(JOURNAL_PATH);
1136        let bytes = match read_optional_file_nofollow(&path)? {
1137            Some(bytes) => bytes,
1138            None => return Ok(Vec::new()),
1139        };
1140        let events = parse_journal_bytes(&path, &bytes, true)?;
1141        let mut checked_objects = std::collections::BTreeSet::new();
1142        for event in &events {
1143            self.ensure_path_within_current_folderbase_boundary(Path::new(&event.path))?;
1144            if let Some(previous_path) = &event.previous_path {
1145                self.ensure_path_within_current_folderbase_boundary(Path::new(previous_path))?;
1146            }
1147            if checked_objects.insert(event.object_id.clone()) {
1148                self.read_object(&event.object_id)?;
1149            }
1150        }
1151        Ok(events)
1152    }
1153
1154    pub(crate) fn ensure_store_layout(&self) -> Result<()> {
1155        for relative in [
1156            OBJECTS_DIRECTORY,
1157            VERSION_RECORDS_DIRECTORY,
1158            BLOBS_DIRECTORY,
1159            ".folderbase/journal",
1160            JOURNAL_QUARANTINE_DIRECTORY,
1161            TRANSACTIONS_DIRECTORY,
1162            LOCKS_DIRECTORY,
1163            PATH_IDENTITIES_DIRECTORY,
1164        ] {
1165            ensure_directory_chain(&self.root, Path::new(relative))?;
1166        }
1167        self.repair_incomplete_journal_tail()?;
1168        self.recover_pending_transactions()?;
1169        Ok(())
1170    }
1171
1172    pub(crate) fn acquire_transaction_lock(&self) -> Result<StoreTransactionLock> {
1173        let state = FolderbaseState::open(&self.root)?;
1174        self.acquire_transaction_lock_in(&state)
1175    }
1176
1177    pub(crate) fn acquire_transaction_lock_in(
1178        &self,
1179        state: &FolderbaseState,
1180    ) -> Result<StoreTransactionLock> {
1181        Self::acquire_transaction_lock_for_state(&self.root, state)
1182    }
1183
1184    /// Acquire the shared transaction lease through an already-retained
1185    /// `.folderbase` state capability.
1186    ///
1187    /// Migration uses this before an ordinary folder has published a manifest,
1188    /// so acquiring the lease cannot depend on opening a `LocalVersionStore`.
1189    pub(crate) fn acquire_transaction_lock_for_state(
1190        display_root: &Path,
1191        state: &FolderbaseState,
1192    ) -> Result<StoreTransactionLock> {
1193        let lock = Self::acquire_transaction_lock_file(display_root, state)?;
1194        if state
1195            .read_bounded_if_present(
1196                Path::new(".folderbase/transactions/protocol-upgrades/active.json"),
1197                16 * 1024 * 1024,
1198            )?
1199            .is_some()
1200        {
1201            return Err(FolderbaseError::ProtocolUpgradeBlocked(
1202                "Folderbase protocol upgrade recovery",
1203            ));
1204        }
1205        Ok(lock)
1206    }
1207
1208    pub(crate) fn acquire_transaction_lock_in_allowing_protocol_upgrade(
1209        &self,
1210        state: &FolderbaseState,
1211    ) -> Result<StoreTransactionLock> {
1212        Self::acquire_transaction_lock_file(&self.root, state)
1213    }
1214
1215    fn acquire_transaction_lock_file(
1216        display_root: &Path,
1217        state: &FolderbaseState,
1218    ) -> Result<StoreTransactionLock> {
1219        state.ensure_private_dir(Path::new(LOCKS_DIRECTORY))?;
1220        let lock_path = display_root.join(TRANSACTION_LOCK_PATH);
1221        match state.publish_new(Path::new(TRANSACTION_LOCK_PATH), b"") {
1222            Ok(()) | Err(FolderbaseError::WouldOverwrite(_)) => {}
1223            Err(error) => return Err(error),
1224        }
1225        let file = state.open_lock_file(Path::new(TRANSACTION_LOCK_PATH))?;
1226        File::lock(&file).map_err(|source| FolderbaseError::io(&lock_path, source))?;
1227        Ok(StoreTransactionLock { file })
1228    }
1229
1230    fn prepare_new_destination(&self, relative_path: &Path) -> Result<(PathBuf, PathBuf)> {
1231        let path = resolve_without_symlinks(&self.root, relative_path, true)?;
1232        let name = relative_path
1233            .file_name()
1234            .ok_or_else(|| FolderbaseError::UnsafePath(relative_path.to_path_buf()))?;
1235        let parent = path
1236            .parent()
1237            .ok_or_else(|| FolderbaseError::UnsafePath(path.clone()))?;
1238        let canonical_parent = parent
1239            .canonicalize()
1240            .map_err(|source| FolderbaseError::io(parent, source))?;
1241        let canonical_relative_parent = canonical_parent
1242            .strip_prefix(&self.root)
1243            .map_err(|_| FolderbaseError::UnsafePath(canonical_parent.clone()))?;
1244        let canonical_relative = safe_content_path(&canonical_relative_parent.join(name))?;
1245        let canonical_path = self.root.join(&canonical_relative);
1246        match fs::symlink_metadata(&canonical_path) {
1247            Ok(_) => Err(FolderbaseError::WouldOverwrite(canonical_path)),
1248            Err(source) if source.kind() == std::io::ErrorKind::NotFound => {
1249                Ok((canonical_path, canonical_relative))
1250            }
1251            Err(source) => Err(FolderbaseError::io(canonical_path, source)),
1252        }
1253    }
1254
1255    fn install_content_blob(&self, source: &Path) -> Result<ContentDigest> {
1256        let mut input = open_existing_nofollow(source)?;
1257        let source_before = input
1258            .metadata()
1259            .map_err(|source_error| FolderbaseError::io(source, source_error))?;
1260        let blob_directory = self.root.join(BLOBS_DIRECTORY);
1261        let staged_path = unique_staged_path(&blob_directory, "blob");
1262        let mut staged = open_new(&staged_path)?;
1263        let mut hasher = Sha256::new();
1264        let mut bytes = 0_u64;
1265        let mut buffer = [0_u8; COPY_BUFFER_BYTES];
1266
1267        let copy_result = (|| -> Result<()> {
1268            loop {
1269                let read = input
1270                    .read(&mut buffer)
1271                    .map_err(|source_error| FolderbaseError::io(source, source_error))?;
1272                if read == 0 {
1273                    break;
1274                }
1275                staged
1276                    .write_all(&buffer[..read])
1277                    .map_err(|source_error| FolderbaseError::io(&staged_path, source_error))?;
1278                hasher.update(&buffer[..read]);
1279                bytes = bytes.checked_add(read as u64).ok_or_else(|| {
1280                    invalid_record(source, "content length exceeds supported range")
1281                })?;
1282            }
1283            staged
1284                .sync_all()
1285                .map_err(|source_error| FolderbaseError::io(&staged_path, source_error))?;
1286            Ok(())
1287        })();
1288        drop(staged);
1289        if let Err(error) = copy_result {
1290            let _ = fs::remove_file(&staged_path);
1291            return Err(error);
1292        }
1293
1294        let source_after_file = match open_existing_nofollow(source) {
1295            Ok(file) => file,
1296            Err(error) => {
1297                let _ = fs::remove_file(&staged_path);
1298                return Err(error);
1299            }
1300        };
1301        let source_after = source_after_file
1302            .metadata()
1303            .map_err(|source_error| FolderbaseError::io(source, source_error))?;
1304        if source_before.len() != source_after.len()
1305            || source_before.modified().ok() != source_after.modified().ok()
1306            || filesystem_identity(&source_before) != filesystem_identity(&source_after)
1307            || source_after.len() != bytes
1308        {
1309            let _ = fs::remove_file(&staged_path);
1310            return Err(invalid_record(
1311                source,
1312                "content changed while the version was being captured",
1313            ));
1314        }
1315
1316        let digest = digest_hex(hasher.finalize().as_slice());
1317        let content = ContentDigest {
1318            algorithm: "sha256".to_owned(),
1319            digest,
1320            bytes,
1321        };
1322        let blob_path = self.blob_path(&content.digest);
1323        match install_no_clobber(&staged_path, &blob_path) {
1324            Ok(()) => sync_parent_directory(&blob_path)?,
1325            Err(source_error) if source_error.kind() == std::io::ErrorKind::AlreadyExists => {
1326                fs::remove_file(&staged_path)
1327                    .map_err(|remove_error| FolderbaseError::io(&staged_path, remove_error))?;
1328                verify_file_content(&blob_path, &content)?;
1329            }
1330            Err(source_error) => {
1331                let _ = fs::remove_file(&staged_path);
1332                return Err(FolderbaseError::io(blob_path, source_error));
1333            }
1334        }
1335        Ok(content)
1336    }
1337
1338    /// Install bytes from a capability-opened ordinary file into the existing
1339    /// content-addressed blob store.
1340    ///
1341    /// The capture producer owns source-identity checks before and after this
1342    /// call. This method owns only append-only blob installation and
1343    /// verification.
1344    pub(crate) fn install_content_reader(
1345        &self,
1346        reader: impl Read,
1347        source_label: &Path,
1348        maximum_bytes: u64,
1349    ) -> Result<ContentDigest> {
1350        let state = FolderbaseState::open(&self.root)?;
1351        self.install_content_reader_in(&state, reader, source_label, maximum_bytes)
1352    }
1353
1354    pub(crate) fn install_content_reader_in(
1355        &self,
1356        state: &FolderbaseState,
1357        reader: impl Read,
1358        source_label: &Path,
1359        maximum_bytes: u64,
1360    ) -> Result<ContentDigest> {
1361        let published = state.publish_reader_sha256(
1362            Path::new(BLOBS_DIRECTORY),
1363            reader,
1364            source_label,
1365            maximum_bytes,
1366        )?;
1367        Ok(ContentDigest {
1368            algorithm: "sha256".to_owned(),
1369            digest: published.digest,
1370            bytes: published.bytes,
1371        })
1372    }
1373
1374    pub(crate) fn install_content_bytes(&self, bytes: &[u8]) -> Result<ContentDigest> {
1375        self.install_content_reader(
1376            std::io::Cursor::new(bytes),
1377            Path::new("in-memory content"),
1378            bytes.len() as u64,
1379        )
1380    }
1381
1382    pub(crate) fn install_content_bytes_in(
1383        &self,
1384        state: &FolderbaseState,
1385        bytes: &[u8],
1386    ) -> Result<ContentDigest> {
1387        self.install_content_reader_in(
1388            state,
1389            std::io::Cursor::new(bytes),
1390            Path::new("in-memory content"),
1391            bytes.len() as u64,
1392        )
1393    }
1394
1395    pub(crate) fn install_or_verify_version_record(
1396        &self,
1397        record: &LocalVersionRecord,
1398    ) -> Result<()> {
1399        let state = FolderbaseState::open(&self.root)?;
1400        self.install_or_verify_version_record_in(&state, record)
1401    }
1402
1403    pub(crate) fn install_or_verify_version_record_in(
1404        &self,
1405        state: &FolderbaseState,
1406        record: &LocalVersionRecord,
1407    ) -> Result<()> {
1408        let path = self.version_record_path(&record.id);
1409        let relative = Path::new(VERSION_RECORDS_DIRECTORY).join(format!("{}.json", record.id));
1410        let encoded = json_bytes(&path, record)?;
1411        match state.publish_new(&relative, &encoded) {
1412            Ok(()) => Ok(()),
1413            Err(FolderbaseError::WouldOverwrite(_)) => {
1414                let existing = state
1415                    .read_bounded(&relative, MAX_CAPTURE_PROJECTION_RECORD_BYTES)?
1416                    .ok_or_else(|| invalid_record(&path, "immutable version record disappeared"))?;
1417                if existing == encoded {
1418                    Ok(())
1419                } else {
1420                    Err(invalid_record(
1421                        path,
1422                        "immutable version record differs from the pending transaction",
1423                    ))
1424                }
1425            }
1426            Err(error) => Err(error),
1427        }
1428    }
1429
1430    fn write_object_projection(&self, record: &LocalObjectRecord) -> Result<()> {
1431        let state = FolderbaseState::open(&self.root)?;
1432        self.write_object_projection_in(&state, record)
1433    }
1434
1435    fn write_object_projection_in(
1436        &self,
1437        state: &FolderbaseState,
1438        record: &LocalObjectRecord,
1439    ) -> Result<()> {
1440        let path = self.object_record_path(&record.id);
1441        let encoded = json_bytes(&path, record)?;
1442        state.replace(&self.object_record_relative_path(&record.id), &encoded)
1443    }
1444
1445    /// Install one derived regular-file object projection after its containing
1446    /// Folderbase Version has become Local Head.
1447    pub(crate) fn write_capture_object_projection_in(
1448        &self,
1449        state: &FolderbaseState,
1450        record: &LocalObjectRecord,
1451    ) -> Result<()> {
1452        self.validate_object_record_membership(
1453            &record.id,
1454            record,
1455            &self.object_record_path(&record.id),
1456        )?;
1457        self.write_object_projection_in(state, record)?;
1458        Ok(())
1459    }
1460
1461    /// Verify a referenced immutable Object Version without consulting a
1462    /// mutable object projection.
1463    pub(crate) fn verify_capture_object_version_in(
1464        &self,
1465        state: &FolderbaseState,
1466        object_id: &ObjectId,
1467        version_id: &VersionId,
1468        expected: &ContentDigest,
1469    ) -> Result<LocalVersionRecord> {
1470        let record = self.read_capture_version_record_in(state, version_id)?;
1471        if record.object_id != *object_id || record.content != *expected {
1472            return Err(invalid_record(
1473                self.version_record_path(version_id),
1474                "Object Version does not match the sealed Folderbase Version reference",
1475            ));
1476        }
1477        state.verify_sha256_blob(
1478            Path::new(BLOBS_DIRECTORY),
1479            &record.content.digest,
1480            record.content.bytes,
1481        )?;
1482        Ok(record)
1483    }
1484
1485    pub(crate) fn verify_capture_version_record_in(
1486        &self,
1487        state: &FolderbaseState,
1488        version_id: &VersionId,
1489        expected: &ContentDigest,
1490    ) -> Result<LocalVersionRecord> {
1491        let record = self.read_capture_version_record_in(state, version_id)?;
1492        if record.content != *expected {
1493            return Err(invalid_record(
1494                self.version_record_path(version_id),
1495                "Object Version bytes do not match the sealed Folderbase Version reference",
1496            ));
1497        }
1498        state.verify_sha256_blob(
1499            Path::new(BLOBS_DIRECTORY),
1500            &record.content.digest,
1501            record.content.bytes,
1502        )?;
1503        Ok(record)
1504    }
1505
1506    pub(crate) fn verify_capture_record_integrity_in(
1507        &self,
1508        state: &FolderbaseState,
1509        object_id: &ObjectId,
1510        version_id: &VersionId,
1511    ) -> Result<LocalVersionRecord> {
1512        let record = self.read_capture_version_record_in(state, version_id)?;
1513        if record.object_id != *object_id {
1514            return Err(invalid_record(
1515                self.version_record_path(version_id),
1516                "Object Version belongs to a different stable Object",
1517            ));
1518        }
1519        state.verify_sha256_blob(
1520            Path::new(BLOBS_DIRECTORY),
1521            &record.content.digest,
1522            record.content.bytes,
1523        )?;
1524        Ok(record)
1525    }
1526
1527    fn read_capture_version_record_in(
1528        &self,
1529        state: &FolderbaseState,
1530        version_id: &VersionId,
1531    ) -> Result<LocalVersionRecord> {
1532        let path = self.version_record_path(version_id);
1533        version_id.validate(&path)?;
1534        let relative = Path::new(VERSION_RECORDS_DIRECTORY).join(format!("{version_id}.json"));
1535        let bytes = state
1536            .read_bounded(&relative, MAX_CAPTURE_PROJECTION_RECORD_BYTES)?
1537            .ok_or_else(|| FolderbaseError::io(&path, std::io::ErrorKind::NotFound.into()))?;
1538        let record: LocalVersionRecord = serde_json::from_slice(&bytes)
1539            .map_err(|source| FolderbaseError::json(&path, source))?;
1540        self.validate_version_record(version_id, &record, &path)?;
1541        Ok(record)
1542    }
1543
1544    fn install_or_verify_restore(&self, restore: &PendingRestore) -> Result<()> {
1545        let destination = safe_content_path(Path::new(&restore.destination))?;
1546        let destination_path = resolve_without_symlinks(&self.root, &destination, true)?;
1547        let blob_path = self.blob_path(&restore.content.digest);
1548        verify_file_content(&blob_path, &restore.content)?;
1549
1550        match fs::symlink_metadata(&destination_path) {
1551            Ok(metadata) if metadata.is_file() && !metadata.file_type().is_symlink() => {
1552                verify_file_content(&destination_path, &restore.content)
1553            }
1554            Ok(_) => Err(FolderbaseError::WouldOverwrite(destination_path)),
1555            Err(source) if source.kind() == std::io::ErrorKind::NotFound => {
1556                copy_verified_new(&blob_path, &destination_path, &restore.content)?;
1557                verify_file_content(&destination_path, &restore.content)
1558            }
1559            Err(source) => Err(FolderbaseError::io(destination_path, source)),
1560        }
1561    }
1562
1563    fn install_or_verify_replacement(&self, replacement: &PendingReplacement) -> Result<()> {
1564        let destination = safe_content_path(Path::new(&replacement.destination))?;
1565        let destination_path = resolve_without_symlinks(&self.root, &destination, false)?;
1566        let metadata = fs::symlink_metadata(&destination_path)
1567            .map_err(|source| FolderbaseError::io(&destination_path, source))?;
1568        if !metadata.is_file() || metadata.file_type().is_symlink() {
1569            return Err(FolderbaseError::UnsafePath(destination_path));
1570        }
1571        let parent = destination_path
1572            .parent()
1573            .ok_or_else(|| FolderbaseError::UnsafePath(destination_path.clone()))?;
1574        let parent_metadata =
1575            fs::metadata(parent).map_err(|source| FolderbaseError::io(parent, source))?;
1576        if replacement
1577            .parent_identity
1578            .as_ref()
1579            .is_some_and(|expected| {
1580                filesystem_identity(&parent_metadata).as_ref() != Some(expected)
1581            })
1582        {
1583            return Err(FolderbaseError::WorkspaceContentChanged(destination));
1584        }
1585
1586        let current = hash_reader(
1587            open_existing_nofollow(&destination_path)?,
1588            &destination_path,
1589        )?;
1590        if current == replacement.content {
1591            return Ok(());
1592        }
1593        if current != replacement.previous_content {
1594            return Err(FolderbaseError::WorkspaceContentChanged(destination));
1595        }
1596        if replacement
1597            .file_identity
1598            .as_ref()
1599            .is_some_and(|expected| filesystem_identity(&metadata).as_ref() != Some(expected))
1600        {
1601            return Err(FolderbaseError::WorkspaceContentChanged(destination));
1602        }
1603
1604        let blob_path = self.blob_path(&replacement.content.digest);
1605        verify_file_content(&blob_path, &replacement.content)?;
1606        replace_verified(
1607            &blob_path,
1608            &destination_path,
1609            &replacement.content,
1610            replacement,
1611        )?;
1612        verify_file_content(&destination_path, &replacement.content)
1613    }
1614
1615    fn commit_transaction(&self, transaction: PendingTransaction) -> Result<()> {
1616        validate_pending_transaction(&transaction, Path::new("pending-transaction"))?;
1617        let path = self.pending_transaction_path(&transaction.id);
1618        write_json_new(&path, &transaction)?;
1619        maybe_fail_workspace_checkpoint(&transaction, "intent-durable", &path)?;
1620        self.replay_transaction(&path, &transaction)
1621    }
1622
1623    fn recover_pending_transactions(&self) -> Result<()> {
1624        let directory = self.root.join(TRANSACTIONS_DIRECTORY);
1625        let mut paths = fs::read_dir(&directory)
1626            .map_err(|source| FolderbaseError::io(&directory, source))?
1627            .map(|entry| {
1628                entry
1629                    .map(|entry| entry.path())
1630                    .map_err(|source| FolderbaseError::io(&directory, source))
1631            })
1632            .collect::<Result<Vec<_>>>()?;
1633        paths.sort();
1634
1635        for path in paths {
1636            let metadata =
1637                fs::symlink_metadata(&path).map_err(|source| FolderbaseError::io(&path, source))?;
1638            if path.extension().and_then(|value| value.to_str()) != Some("json") {
1639                continue;
1640            }
1641            if !metadata.is_file() || metadata.file_type().is_symlink() {
1642                return Err(invalid_record(
1643                    path,
1644                    "pending transaction is not a regular file",
1645                ));
1646            }
1647            let transaction: PendingTransaction = read_json(&path)?;
1648            validate_pending_transaction(&transaction, &path)?;
1649            if self.pending_transaction_path(&transaction.id) != path {
1650                return Err(invalid_record(
1651                    path,
1652                    "pending transaction ID does not match its filename",
1653                ));
1654            }
1655            self.replay_transaction(&path, &transaction)?;
1656        }
1657        Ok(())
1658    }
1659
1660    fn replay_transaction(&self, path: &Path, transaction: &PendingTransaction) -> Result<()> {
1661        if transaction.restore.is_none() {
1662            let recorded_path = Path::new(&transaction.object.path);
1663            let (materialized_path, canonical_relative) =
1664                resolve_existing_workspace_file(&self.root, recorded_path)?;
1665            if relative_path_to_string(&canonical_relative)? != transaction.object.path {
1666                return Err(invalid_record(
1667                    path,
1668                    "pending object path no longer matches the filesystem spelling",
1669                ));
1670            }
1671            if transaction.replacement.is_none() {
1672                let expected_content = match &transaction.version {
1673                    Some(version) => version.content.clone(),
1674                    None => {
1675                        self.read_version(&transaction.object.current_version)?
1676                            .content
1677                    }
1678                };
1679                let current_content = hash_reader(
1680                    open_existing_nofollow(&materialized_path)?,
1681                    &materialized_path,
1682                )?;
1683                if current_content != expected_content {
1684                    return Err(FolderbaseError::WorkspaceContentChanged(canonical_relative));
1685                }
1686            }
1687        }
1688
1689        if let Some(version) = &transaction.version {
1690            let blob_path = self.blob_path(&version.content.digest);
1691            verify_file_content(&blob_path, &version.content)?;
1692            self.install_or_verify_version_record(version)?;
1693        }
1694        for version in &transaction.versions {
1695            let blob_path = self.blob_path(&version.content.digest);
1696            verify_file_content(&blob_path, &version.content)?;
1697            self.install_or_verify_version_record(version)?;
1698        }
1699        maybe_fail_workspace_checkpoint(transaction, "versions-durable", path)?;
1700        let current = self.read_version_record(&transaction.object.current_version)?;
1701        if current.object_id != transaction.object.id {
1702            return Err(invalid_record(
1703                path,
1704                "pending projection current version belongs to a different object",
1705            ));
1706        }
1707
1708        if let Some(replacement) = &transaction.replacement {
1709            self.install_or_verify_replacement(replacement)?;
1710            maybe_fail_workspace_checkpoint(transaction, "content-replaced", path)?;
1711            self.write_materialized_object_projection(&transaction.object)?;
1712            maybe_fail_workspace_checkpoint(transaction, "projection-durable", path)?;
1713        } else if let Some(restore) = &transaction.restore {
1714            let restored_version = self.read_version(&restore.version_id)?;
1715            if restored_version.object_id != transaction.object.id
1716                || restored_version.content != restore.content
1717            {
1718                return Err(invalid_record(
1719                    path,
1720                    "pending restore does not match its immutable version",
1721                ));
1722            }
1723            self.install_or_verify_restore(restore)?;
1724            maybe_fail_workspace_checkpoint(transaction, "restore-published", path)?;
1725        } else {
1726            self.write_materialized_object_projection(&transaction.object)?;
1727        }
1728        self.append_journal_events(&transaction.events)?;
1729        maybe_fail_workspace_checkpoint(transaction, "journal-durable", path)?;
1730        fs::remove_file(path).map_err(|source| FolderbaseError::io(path, source))?;
1731        sync_parent_directory(path)
1732    }
1733
1734    fn append_journal_events(&self, events: &[ObjectJournalEvent]) -> Result<()> {
1735        let path = self.root.join(JOURNAL_PATH);
1736        self.repair_incomplete_journal_tail()?;
1737        let existing = match read_optional_file_nofollow(&path)? {
1738            Some(bytes) => parse_journal_bytes(&path, &bytes, false)?,
1739            None => Vec::new(),
1740        };
1741        let mut event_ids = existing
1742            .into_iter()
1743            .map(|event| event.id)
1744            .collect::<std::collections::BTreeSet<_>>();
1745
1746        let mut journal = OpenOptions::new();
1747        journal.create(true).append(true);
1748        #[cfg(unix)]
1749        {
1750            use std::os::unix::fs::OpenOptionsExt;
1751            journal.mode(0o600).custom_flags(libc::O_NOFOLLOW);
1752        }
1753        let mut journal = journal
1754            .open(&path)
1755            .map_err(|source| FolderbaseError::io(&path, source))?;
1756        let mut appended = false;
1757        for event in events {
1758            validate_journal_event(event, &path, 0)?;
1759            if !event_ids.insert(event.id.clone()) {
1760                continue;
1761            }
1762            let mut encoded =
1763                serde_json::to_vec(event).map_err(|source| FolderbaseError::json(&path, source))?;
1764            encoded.push(b'\n');
1765            journal
1766                .write_all(&encoded)
1767                .map_err(|source| FolderbaseError::io(&path, source))?;
1768            appended = true;
1769        }
1770        if appended {
1771            journal
1772                .sync_data()
1773                .map_err(|source| FolderbaseError::io(&path, source))?;
1774            sync_parent_directory(&path)?;
1775        }
1776        Ok(())
1777    }
1778
1779    fn repair_incomplete_journal_tail(&self) -> Result<()> {
1780        let path = self.root.join(JOURNAL_PATH);
1781        let bytes = match read_optional_file_nofollow(&path)? {
1782            Some(bytes) => bytes,
1783            None => return Ok(()),
1784        };
1785        if bytes.is_empty() || bytes.ends_with(b"\n") {
1786            return Ok(());
1787        }
1788
1789        let prefix_length = bytes
1790            .iter()
1791            .rposition(|byte| *byte == b'\n')
1792            .map_or(0, |index| index + 1);
1793        let tail = &bytes[prefix_length..];
1794        match serde_json::from_slice::<ObjectJournalEvent>(tail) {
1795            Ok(event) => {
1796                validate_journal_event(&event, &path, 0)?;
1797                let mut repaired = bytes;
1798                repaired.push(b'\n');
1799                write_bytes_replace(&path, &repaired)
1800            }
1801            Err(_) => {
1802                let quarantine = self
1803                    .root
1804                    .join(JOURNAL_QUARANTINE_DIRECTORY)
1805                    .join(format!("objects-tail-{}.ndjson", Uuid::now_v7()));
1806                write_bytes_new(&quarantine, tail)?;
1807                write_bytes_replace(&path, &bytes[..prefix_length])
1808            }
1809        }
1810    }
1811
1812    fn pending_transaction_path(&self, transaction_id: &str) -> PathBuf {
1813        self.root
1814            .join(TRANSACTIONS_DIRECTORY)
1815            .join(format!("{transaction_id}.json"))
1816    }
1817
1818    fn find_object_by_path(&self, relative_path: &Path) -> Result<Option<LocalObjectRecord>> {
1819        let directory = self.root.join(OBJECTS_DIRECTORY);
1820        let requested_path = relative_path_to_string(relative_path)?;
1821        let entries = match fs::read_dir(&directory) {
1822            Ok(entries) => entries,
1823            Err(source) if source.kind() == std::io::ErrorKind::NotFound => return Ok(None),
1824            Err(source) => return Err(FolderbaseError::io(directory, source)),
1825        };
1826        let mut found = None;
1827        for entry in entries {
1828            let entry = entry.map_err(|source| FolderbaseError::io(&directory, source))?;
1829            let file_type = entry
1830                .file_type()
1831                .map_err(|source| FolderbaseError::io(entry.path(), source))?;
1832            if entry.path().extension().and_then(|value| value.to_str()) != Some("json") {
1833                continue;
1834            }
1835            if !file_type.is_file() || file_type.is_symlink() {
1836                return Err(invalid_record(
1837                    entry.path(),
1838                    "object record is not a regular file",
1839                ));
1840            }
1841            let mut record: LocalObjectRecord = read_json(&entry.path())?;
1842            record.id.validate(&entry.path())?;
1843            let stored_path = safe_content_path(Path::new(&record.path)).map_err(|_| {
1844                invalid_record(entry.path(), "object path is not a safe relative path")
1845            })?;
1846            let is_match = if stored_path == relative_path {
1847                true
1848            } else {
1849                match resolve_existing_workspace_file(&self.root, &stored_path) {
1850                    Ok((_, canonical_path)) => canonical_path == relative_path,
1851                    Err(FolderbaseError::Io { source, .. })
1852                        if source.kind() == std::io::ErrorKind::NotFound =>
1853                    {
1854                        if paths_equal_ignoring_ascii_case(&stored_path, relative_path) {
1855                            return Err(invalid_record(
1856                                entry.path(),
1857                                "stored object path alias no longer resolves to its canonical file",
1858                            ));
1859                        }
1860                        false
1861                    }
1862                    Err(FolderbaseError::UnsafePath(_))
1863                        if !paths_equal_ignoring_ascii_case(&stored_path, relative_path) =>
1864                    {
1865                        false
1866                    }
1867                    Err(error) => return Err(error),
1868                }
1869            };
1870            if is_match {
1871                self.deny_if_transferred_out(&record.id)?;
1872                if found.is_some() {
1873                    return Err(invalid_record(
1874                        &directory,
1875                        format!("multiple object records claim path {requested_path}"),
1876                    ));
1877                }
1878                record.path.clone_from(&requested_path);
1879                found = Some(record);
1880            }
1881        }
1882        Ok(found)
1883    }
1884
1885    fn persist_canonical_object_path(&self, object: &LocalObjectRecord) -> Result<()> {
1886        let persisted = self.read_object(&object.id)?;
1887        if persisted.path == object.path {
1888            return Ok(());
1889        }
1890        let mut expected_persisted = object.clone();
1891        expected_persisted.path.clone_from(&persisted.path);
1892        if persisted != expected_persisted {
1893            return Err(invalid_record(
1894                self.object_record_path(&object.id),
1895                "object record changed while canonicalizing its path",
1896            ));
1897        }
1898
1899        self.commit_transaction(PendingTransaction {
1900            protocol_version: "0.1.0".to_owned(),
1901            id: format!("transaction_{}", Uuid::now_v7()),
1902            version: None,
1903            versions: Vec::new(),
1904            object: object.clone(),
1905            restore: None,
1906            replacement: None,
1907            events: vec![ObjectJournalEvent {
1908                id: format!("event_{}", Uuid::now_v7()),
1909                at: Utc::now().to_rfc3339(),
1910                action: JournalAction::ObjectRelocated,
1911                object_id: object.id.clone(),
1912                path: object.path.clone(),
1913                previous_path: Some(persisted.path),
1914                version_id: Some(object.current_version.clone()),
1915                content: None,
1916            }],
1917        })
1918    }
1919
1920    fn ensure_path_within_current_folderbase_boundary(&self, relative_path: &Path) -> Result<()> {
1921        let mut resolved = self.root.clone();
1922        let mut components = relative_path.components().peekable();
1923        while let Some(component) = components.next() {
1924            let Component::Normal(name) = component else {
1925                return Err(FolderbaseError::UnsafePath(relative_path.to_path_buf()));
1926            };
1927            let requested = resolved.join(name);
1928            // Even when the requested spelling exists, a second
1929            // case-insensitive alias can point at a newly established nested
1930            // folderbase. Treat that ambiguity as unsafe instead of allowing a
1931            // stale stored spelling to select the ordinary sibling.
1932            let case_folded_child = find_case_folded_child(&resolved, name)?;
1933            let (path, metadata) = match fs::symlink_metadata(&requested) {
1934                Ok(metadata) => (requested, metadata),
1935                Err(source) if source.kind() == std::io::ErrorKind::NotFound => {
1936                    let Some(alias) = case_folded_child else {
1937                        return Ok(());
1938                    };
1939                    let metadata = fs::symlink_metadata(&alias)
1940                        .map_err(|source| FolderbaseError::io(&alias, source))?;
1941                    (alias, metadata)
1942                }
1943                Err(source) => return Err(FolderbaseError::io(requested, source)),
1944            };
1945            if metadata.file_type().is_symlink() {
1946                return Err(FolderbaseError::UnsafePath(path));
1947            }
1948            if metadata.is_dir() && has_nested_folderbase_marker(&path)? {
1949                return Err(FolderbaseError::UnsafePath(relative_path.to_path_buf()));
1950            }
1951            if components.peek().is_some() && !metadata.is_dir() {
1952                return Err(FolderbaseError::UnsafePath(relative_path.to_path_buf()));
1953            }
1954            resolved = path;
1955        }
1956        Ok(())
1957    }
1958
1959    fn object_record_path(&self, object_id: &ObjectId) -> PathBuf {
1960        self.root.join(self.object_record_relative_path(object_id))
1961    }
1962
1963    fn path_identity_path(&self, object_id: &ObjectId) -> PathBuf {
1964        self.root
1965            .join(PATH_IDENTITIES_DIRECTORY)
1966            .join(format!("{object_id}.json"))
1967    }
1968
1969    fn write_materialized_object_projection(&self, object: &LocalObjectRecord) -> Result<()> {
1970        self.write_object_projection(object)?;
1971        self.write_local_file_identity(&object.id, &self.root.join(&object.path))
1972    }
1973
1974    fn write_local_file_identity(&self, object_id: &ObjectId, path: &Path) -> Result<()> {
1975        let state = FolderbaseState::open(&self.root)?;
1976        self.write_local_file_identity_in(&state, object_id, path)
1977    }
1978
1979    fn write_local_file_identity_in(
1980        &self,
1981        state: &FolderbaseState,
1982        object_id: &ObjectId,
1983        path: &Path,
1984    ) -> Result<()> {
1985        let file = open_existing_nofollow(path)?;
1986        let metadata = file
1987            .metadata()
1988            .map_err(|source| FolderbaseError::io(path, source))?;
1989        let Some(file_system) = filesystem_identity(&metadata) else {
1990            return Ok(());
1991        };
1992        let path = self.path_identity_path(object_id);
1993        let encoded = json_bytes(
1994            &path,
1995            &LocalPathIdentity {
1996                object_id: object_id.clone(),
1997                file_system,
1998            },
1999        )?;
2000        state.replace(
2001            &Path::new(PATH_IDENTITIES_DIRECTORY).join(format!("{object_id}.json")),
2002            &encoded,
2003        )
2004    }
2005
2006    fn read_local_file_identity(&self, object_id: &ObjectId) -> Result<Option<FileSystemIdentity>> {
2007        let path = self.path_identity_path(object_id);
2008        let Some(bytes) = read_optional_file_nofollow(&path)? else {
2009            return Ok(None);
2010        };
2011        let binding: LocalPathIdentity = serde_json::from_slice(&bytes)
2012            .map_err(|source| FolderbaseError::json(&path, source))?;
2013        if binding.object_id != *object_id {
2014            return Err(invalid_record(
2015                path,
2016                "local path identity belongs to a different object",
2017            ));
2018        }
2019        Ok(Some(binding.file_system))
2020    }
2021
2022    fn version_record_path(&self, version_id: &VersionId) -> PathBuf {
2023        self.root
2024            .join(self.version_record_relative_path(version_id))
2025    }
2026
2027    fn blob_path(&self, digest: &str) -> PathBuf {
2028        self.root.join(self.blob_relative_path(digest))
2029    }
2030
2031    pub(crate) fn version_record_relative_path(&self, version_id: &VersionId) -> PathBuf {
2032        PathBuf::from(VERSION_RECORDS_DIRECTORY).join(format!("{version_id}.json"))
2033    }
2034
2035    pub(crate) fn object_record_relative_path(&self, object_id: &ObjectId) -> PathBuf {
2036        PathBuf::from(OBJECTS_DIRECTORY).join(format!("{object_id}.json"))
2037    }
2038
2039    pub(crate) fn blob_relative_path(&self, digest: &str) -> PathBuf {
2040        PathBuf::from(BLOBS_DIRECTORY).join(digest)
2041    }
2042
2043    fn deny_if_transferred_out(&self, object_id: &ObjectId) -> Result<()> {
2044        let path = outgoing_history_transfer_path(&self.root, object_id);
2045        let Some(bytes) = read_optional_file_nofollow(&path)? else {
2046            return Ok(());
2047        };
2048        validate_chunk_transfer_receipt_bytes(
2049            &bytes,
2050            &path,
2051            object_id,
2052            &read_folderbase_identity(&self.root)?.id,
2053        )
2054    }
2055}
2056
2057impl HistoryTransferPlan {
2058    pub fn reopen(source_root: impl AsRef<Path>, transfer_id: &str) -> Result<Self> {
2059        let source_root = canonical_folderbase_root(source_root.as_ref())?;
2060        load_history_transfer_plan(&source_root, transfer_id)
2061    }
2062}
2063
2064impl HistoryTransferResult {
2065    pub fn recover(source_root: impl AsRef<Path>, transfer_id: &str) -> Result<Self> {
2066        let source_root = canonical_folderbase_root(source_root.as_ref())?;
2067        let plan = load_history_transfer_plan(&source_root, transfer_id)?;
2068        match plan.state {
2069            HistoryTransferState::Approved
2070            | HistoryTransferState::Applying
2071            | HistoryTransferState::DestinationVerified
2072            | HistoryTransferState::SourceReleased => {
2073                replay_history_transfer_with_hook(plan, |_| {})
2074            }
2075            HistoryTransferState::Verified => {
2076                let destination = LocalVersionStore::open(&plan.destination_root)?;
2077                verify_history_transfer_ownership_boundaries(&plan)?;
2078                verify_history_transfer_receipts(&plan)?;
2079                verify_incoming_history(&destination, &plan)?;
2080                cleanup_history_transfer_staging(&destination.root, &plan.id)?;
2081                Ok(history_transfer_result(&plan))
2082            }
2083            HistoryTransferState::Proposed | HistoryTransferState::Conflicted => {
2084                Err(FolderbaseError::InvalidMigrationState {
2085                    expected: "approved",
2086                    actual: history_transfer_state_name(plan.state).to_owned(),
2087                })
2088            }
2089        }
2090    }
2091}
2092
2093pub fn approve_history_transfer(plan: HistoryTransferPlan) -> Result<ApprovedHistoryTransfer> {
2094    if plan.state != HistoryTransferState::Proposed || plan.approval_digest.is_some() {
2095        return Err(FolderbaseError::InvalidMigrationState {
2096            expected: "proposed",
2097            actual: history_transfer_state_name(plan.state).to_owned(),
2098        });
2099    }
2100    let mut stored = load_history_transfer_plan(&plan.source_root, &plan.id)?;
2101    if stored != plan {
2102        return Err(FolderbaseError::MigrationApprovalMismatch);
2103    }
2104    verify_history_transfer_preconditions(&stored)?;
2105    let approval_digest = history_transfer_digest(&stored)?;
2106    stored.state = HistoryTransferState::Approved;
2107    stored.approval_digest = Some(approval_digest.clone());
2108    persist_history_transfer_plan(&stored)?;
2109    Ok(ApprovedHistoryTransfer {
2110        plan: stored,
2111        approval_digest,
2112    })
2113}
2114
2115pub fn apply_history_transfer(approved: ApprovedHistoryTransfer) -> Result<HistoryTransferResult> {
2116    apply_history_transfer_with_hook(approved, |_| {})
2117}
2118
2119fn apply_history_transfer_with_hook(
2120    approved: ApprovedHistoryTransfer,
2121    checkpoint: impl FnMut(HistoryTransferCheckpoint),
2122) -> Result<HistoryTransferResult> {
2123    if history_transfer_digest(&approved.plan)? != approved.approval_digest {
2124        return Err(FolderbaseError::MigrationApprovalMismatch);
2125    }
2126    let stored = load_history_transfer_plan(&approved.plan.source_root, &approved.plan.id)?;
2127    if stored.state != HistoryTransferState::Approved
2128        || stored.approval_digest.as_deref() != Some(approved.approval_digest.as_str())
2129        || stored != approved.plan
2130    {
2131        return Err(FolderbaseError::MigrationApprovalMismatch);
2132    }
2133    replay_history_transfer_with_hook(stored, checkpoint)
2134}
2135
2136fn replay_history_transfer_with_hook(
2137    mut plan: HistoryTransferPlan,
2138    mut checkpoint: impl FnMut(HistoryTransferCheckpoint),
2139) -> Result<HistoryTransferResult> {
2140    let source = LocalVersionStore::open(&plan.source_root)
2141        .map_err(|error| mark_released_history_transfer_conflicted(&mut plan, error))?;
2142    let destination = LocalVersionStore::open(&plan.destination_root)
2143        .map_err(|error| mark_released_history_transfer_conflicted(&mut plan, error))?;
2144    if plan.state == HistoryTransferState::SourceReleased {
2145        verify_released_history_transfer(&destination, &plan)
2146            .map_err(|error| mark_history_transfer_conflicted(&mut plan, error))?;
2147    } else {
2148        verify_history_transfer_preconditions_for_stores(&source, &destination, &plan)?;
2149    }
2150    let (_first_lock, _second_lock) = if source.root <= destination.root {
2151        (
2152            source.acquire_transaction_lock()?,
2153            destination.acquire_transaction_lock()?,
2154        )
2155    } else {
2156        (
2157            destination.acquire_transaction_lock()?,
2158            source.acquire_transaction_lock()?,
2159        )
2160    };
2161
2162    if plan.state == HistoryTransferState::SourceReleased {
2163        verify_released_history_transfer(&destination, &plan)
2164            .map_err(|error| mark_history_transfer_conflicted(&mut plan, error))?;
2165    } else {
2166        verify_history_transfer_preconditions_for_stores(&source, &destination, &plan)?;
2167    }
2168    if plan.state == HistoryTransferState::Approved {
2169        plan.state = HistoryTransferState::Applying;
2170        persist_history_transfer_plan(&plan)?;
2171        checkpoint(HistoryTransferCheckpoint::Applying);
2172    }
2173    if plan.state == HistoryTransferState::Applying {
2174        stage_history_transfer(&source, &destination, &plan)?;
2175        verify_staged_history(&destination, &plan)?;
2176        checkpoint(HistoryTransferCheckpoint::DestinationStaged);
2177        plan.state = HistoryTransferState::DestinationVerified;
2178        persist_history_transfer_plan(&plan)?;
2179        checkpoint(HistoryTransferCheckpoint::DestinationVerified);
2180    }
2181    if plan.state == HistoryTransferState::DestinationVerified {
2182        let release = (|| -> Result<()> {
2183            verify_staged_history(&destination, &plan)?;
2184            verify_destination_available_for_transfer(&destination, &plan, false)?;
2185            ensure_directory_chain(&source.root, Path::new(HISTORY_TRANSFER_OUTGOING_DIRECTORY))?;
2186            install_or_verify_history_transfer_receipt(
2187                &outgoing_history_transfer_path(&source.root, &plan.object.id),
2188                &history_transfer_receipt(&plan)?,
2189            )
2190        })();
2191        if let Err(error) = release {
2192            return Err(mark_history_transfer_conflicted(&mut plan, error));
2193        }
2194        checkpoint(HistoryTransferCheckpoint::SourceReceiptWritten);
2195        plan.state = HistoryTransferState::SourceReleased;
2196        persist_history_transfer_plan(&plan)?;
2197        checkpoint(HistoryTransferCheckpoint::SourceReleased);
2198    }
2199    if plan.state == HistoryTransferState::SourceReleased {
2200        let activation = (|| -> Result<()> {
2201            verify_history_transfer_ownership_boundaries(&plan)?;
2202            verify_staged_history(&destination, &plan)?;
2203            verify_destination_available_for_transfer(&destination, &plan, true)?;
2204            ensure_directory_chain(
2205                &destination.root,
2206                Path::new(HISTORY_TRANSFER_INCOMING_DIRECTORY),
2207            )?;
2208            install_or_verify_history_transfer_receipt(
2209                &incoming_history_transfer_path(&destination.root, &plan.object.id),
2210                &history_transfer_receipt(&plan)?,
2211            )?;
2212            checkpoint(HistoryTransferCheckpoint::IncomingReceiptWritten);
2213            activate_incoming_history(&destination, &plan)?;
2214            verify_incoming_history(&destination, &plan)
2215        })();
2216        if let Err(error) = activation {
2217            return Err(mark_history_transfer_conflicted(&mut plan, error));
2218        }
2219        checkpoint(HistoryTransferCheckpoint::DestinationActivated);
2220        plan.state = HistoryTransferState::Verified;
2221        persist_history_transfer_plan(&plan)?;
2222        checkpoint(HistoryTransferCheckpoint::Verified);
2223    }
2224    if plan.state != HistoryTransferState::Verified {
2225        return Err(FolderbaseError::InvalidMigrationState {
2226            expected: "verified",
2227            actual: history_transfer_state_name(plan.state).to_owned(),
2228        });
2229    }
2230    verify_history_transfer_ownership_boundaries(&plan)?;
2231    verify_history_transfer_receipts(&plan)?;
2232    verify_incoming_history(&destination, &plan)?;
2233    cleanup_history_transfer_staging(&destination.root, &plan.id)?;
2234    Ok(history_transfer_result(&plan))
2235}
2236
2237fn verify_released_history_transfer(
2238    destination: &LocalVersionStore,
2239    plan: &HistoryTransferPlan,
2240) -> Result<()> {
2241    verify_history_transfer_ownership_boundaries(plan)?;
2242    verify_staged_history(destination, plan)
2243}
2244
2245fn stage_history_transfer(
2246    source: &LocalVersionStore,
2247    destination: &LocalVersionStore,
2248    plan: &HistoryTransferPlan,
2249) -> Result<()> {
2250    let staging = history_transfer_staging_root(&destination.root, &plan.id);
2251    ensure_directory_chain(
2252        &destination.root,
2253        &PathBuf::from(HISTORY_TRANSFER_STAGING_DIRECTORY)
2254            .join(&plan.id)
2255            .join("objects"),
2256    )?;
2257    ensure_directory_chain(
2258        &destination.root,
2259        &PathBuf::from(HISTORY_TRANSFER_STAGING_DIRECTORY)
2260            .join(&plan.id)
2261            .join("versions/records"),
2262    )?;
2263    ensure_directory_chain(
2264        &destination.root,
2265        &PathBuf::from(HISTORY_TRANSFER_STAGING_DIRECTORY)
2266            .join(&plan.id)
2267            .join("versions/blobs/sha256"),
2268    )?;
2269    for version in &plan.versions {
2270        install_or_verify_content_file(
2271            &source.blob_path(&version.content.digest),
2272            &staging
2273                .join("versions/blobs/sha256")
2274                .join(&version.content.digest),
2275            &version.content,
2276        )?;
2277        install_or_verify_json(
2278            &staging
2279                .join("versions/records")
2280                .join(format!("{}.json", version.id)),
2281            version,
2282        )?;
2283    }
2284    let mut object = plan.object.clone();
2285    object.path.clone_from(&plan.destination_path);
2286    install_or_verify_json(
2287        &staging.join("objects").join(format!("{}.json", object.id)),
2288        &object,
2289    )
2290}
2291
2292fn verify_staged_history(
2293    destination: &LocalVersionStore,
2294    plan: &HistoryTransferPlan,
2295) -> Result<()> {
2296    let staging = history_transfer_staging_root(&destination.root, &plan.id);
2297    for version in &plan.versions {
2298        let path = staging
2299            .join("versions/records")
2300            .join(format!("{}.json", version.id));
2301        let installed: LocalVersionRecord = read_json(&path)?;
2302        if installed != *version {
2303            return Err(invalid_record(path, "staged version record changed"));
2304        }
2305        verify_file_content(
2306            &staging
2307                .join("versions/blobs/sha256")
2308                .join(&version.content.digest),
2309            &version.content,
2310        )?;
2311    }
2312    let mut expected = plan.object.clone();
2313    expected.path.clone_from(&plan.destination_path);
2314    let path = staging
2315        .join("objects")
2316        .join(format!("{}.json", expected.id));
2317    let installed: LocalObjectRecord = read_json(&path)?;
2318    if installed != expected {
2319        return Err(invalid_record(path, "staged object projection changed"));
2320    }
2321    Ok(())
2322}
2323
2324fn activate_incoming_history(
2325    destination: &LocalVersionStore,
2326    plan: &HistoryTransferPlan,
2327) -> Result<()> {
2328    destination.ensure_store_layout()?;
2329    let staging = history_transfer_staging_root(&destination.root, &plan.id);
2330    for version in &plan.versions {
2331        install_or_verify_content_file(
2332            &staging
2333                .join("versions/blobs/sha256")
2334                .join(&version.content.digest),
2335            &destination.blob_path(&version.content.digest),
2336            &version.content,
2337        )?;
2338        destination.install_or_verify_version_record(version)?;
2339    }
2340    let object = expected_history_transfer_object(plan);
2341    let object_path = destination.object_record_path(&object.id);
2342    match read_optional_file_nofollow(&object_path)? {
2343        Some(_) => {
2344            let installed: LocalObjectRecord = read_json(&object_path)?;
2345            verify_object_preserves_transferred_history(&installed, plan, &object_path)?;
2346        }
2347        None => install_or_verify_json(&object_path, &object)?,
2348    }
2349    destination.write_local_file_identity(&object.id, &destination.root.join(&object.path))
2350}
2351
2352fn verify_incoming_history(
2353    destination: &LocalVersionStore,
2354    plan: &HistoryTransferPlan,
2355) -> Result<()> {
2356    let object = destination.read_object(&plan.object.id)?;
2357    verify_object_preserves_transferred_history(
2358        &object,
2359        plan,
2360        &destination.object_record_path(&plan.object.id),
2361    )?;
2362    for version in &plan.versions {
2363        if destination.read_version(&version.id)? != *version {
2364            return Err(invalid_record(
2365                destination.version_record_path(&version.id),
2366                "incoming version does not match the approved transfer",
2367            ));
2368        }
2369        verify_file_content(
2370            &destination.blob_path(&version.content.digest),
2371            &version.content,
2372        )?;
2373    }
2374    Ok(())
2375}
2376
2377fn expected_history_transfer_object(plan: &HistoryTransferPlan) -> LocalObjectRecord {
2378    let mut expected = plan.object.clone();
2379    expected.path.clone_from(&plan.destination_path);
2380    expected
2381}
2382
2383fn verify_object_preserves_transferred_history(
2384    object: &LocalObjectRecord,
2385    plan: &HistoryTransferPlan,
2386    path: &Path,
2387) -> Result<()> {
2388    if object.id != plan.object.id
2389        || object.path != plan.destination_path
2390        || !object.versions.starts_with(&plan.object.versions)
2391        || !object.versions.contains(&object.current_version)
2392    {
2393        return Err(invalid_record(
2394            path,
2395            "incoming object no longer preserves the approved transferred history",
2396        ));
2397    }
2398    Ok(())
2399}
2400
2401fn verify_destination_available_for_transfer(
2402    destination: &LocalVersionStore,
2403    plan: &HistoryTransferPlan,
2404    allow_activated_replay: bool,
2405) -> Result<()> {
2406    let object_path = destination.object_record_path(&plan.object.id);
2407    if read_optional_file_nofollow(&object_path)?.is_some() {
2408        if !allow_activated_replay {
2409            return Err(FolderbaseError::WouldOverwrite(object_path));
2410        }
2411        let object: LocalObjectRecord = read_json(&object_path)?;
2412        verify_object_preserves_transferred_history(&object, plan, &object_path)?;
2413    }
2414
2415    if let Some(claimant) = destination.find_object_by_path(Path::new(&plan.destination_path))? {
2416        if !allow_activated_replay || claimant.id != plan.object.id {
2417            return Err(FolderbaseError::WouldOverwrite(
2418                destination.object_record_path(&claimant.id),
2419            ));
2420        }
2421        verify_object_preserves_transferred_history(
2422            &claimant,
2423            plan,
2424            &destination.object_record_path(&claimant.id),
2425        )?;
2426    }
2427
2428    for version in &plan.versions {
2429        let version_path = destination.version_record_path(&version.id);
2430        if read_optional_file_nofollow(&version_path)?.is_some()
2431            && destination.read_version_record(&version.id)? != *version
2432        {
2433            return Err(FolderbaseError::WouldOverwrite(version_path));
2434        }
2435        let blob_path = destination.blob_path(&version.content.digest);
2436        if read_optional_file_nofollow(&blob_path)?.is_some() {
2437            verify_file_content(&blob_path, &version.content)?;
2438        }
2439    }
2440    Ok(())
2441}
2442
2443fn verify_history_transfer_preconditions(plan: &HistoryTransferPlan) -> Result<()> {
2444    let source = LocalVersionStore::open(&plan.source_root)?;
2445    let destination = LocalVersionStore::open(&plan.destination_root)?;
2446    verify_history_transfer_preconditions_for_stores(&source, &destination, plan)
2447}
2448
2449fn verify_history_transfer_preconditions_for_stores(
2450    source: &LocalVersionStore,
2451    destination: &LocalVersionStore,
2452    plan: &HistoryTransferPlan,
2453) -> Result<()> {
2454    verify_history_transfer_boundary_preconditions(plan)?;
2455    let source_identity = read_folderbase_identity(&source.root)?;
2456    let destination_identity = read_folderbase_identity(&destination.root)?;
2457    if source_identity.id != plan.source_folderbase_id
2458        || destination_identity.id != plan.destination_folderbase_id
2459        || source_identity.manifest_sha256 != plan.source_manifest_sha256
2460        || destination_identity.manifest_sha256 != plan.destination_manifest_sha256
2461    {
2462        return Err(FolderbaseError::PlanPreconditionChanged(
2463            plan.source_root.clone(),
2464        ));
2465    }
2466    if !has_nested_folderbase_marker(&destination.root)? {
2467        return Err(FolderbaseError::UnsafePath(destination.root.clone()));
2468    }
2469    let object = source.read_object_record_for_transfer(&plan.object.id)?;
2470    if object != plan.object {
2471        return Err(FolderbaseError::PlanPreconditionChanged(
2472            source.object_record_path(&plan.object.id),
2473        ));
2474    }
2475    for expected in &plan.versions {
2476        let version = source.read_version_record(&expected.id)?;
2477        if version != *expected {
2478            return Err(FolderbaseError::PlanPreconditionChanged(
2479                source.version_record_path(&expected.id),
2480            ));
2481        }
2482        verify_file_content(
2483            &source.blob_path(&expected.content.digest),
2484            &expected.content,
2485        )?;
2486    }
2487    let current = plan
2488        .versions
2489        .iter()
2490        .find(|version| version.id == plan.object.current_version)
2491        .ok_or_else(|| {
2492            invalid_record(
2493                source.object_record_path(&plan.object.id),
2494                "current version is absent from approved history",
2495            )
2496        })?;
2497    let (materialized, canonical_path) =
2498        resolve_existing_workspace_file(&destination.root, Path::new(&plan.destination_path))?;
2499    if canonical_path != Path::new(&plan.destination_path) {
2500        return Err(FolderbaseError::UnsafePath(canonical_path));
2501    }
2502    verify_file_content(&materialized, &current.content)
2503}
2504
2505fn verify_history_transfer_boundary_preconditions(plan: &HistoryTransferPlan) -> Result<()> {
2506    verify_history_transfer_ownership_boundaries(plan)?;
2507    let source_identity = read_folderbase_identity(&plan.source_root)?;
2508    let destination_identity = read_folderbase_identity(&plan.destination_root)?;
2509    if source_identity.manifest_sha256 != plan.source_manifest_sha256
2510        || destination_identity.manifest_sha256 != plan.destination_manifest_sha256
2511    {
2512        return Err(FolderbaseError::PlanPreconditionChanged(
2513            plan.source_root.clone(),
2514        ));
2515    }
2516    let current = plan
2517        .versions
2518        .iter()
2519        .find(|version| version.id == plan.object.current_version)
2520        .ok_or_else(|| {
2521            invalid_record(
2522                history_transfer_plan_path(&plan.source_root, &plan.id),
2523                "current version is absent from approved history",
2524            )
2525        })?;
2526    let (materialized, canonical_path) =
2527        resolve_existing_workspace_file(&plan.destination_root, Path::new(&plan.destination_path))?;
2528    if canonical_path != Path::new(&plan.destination_path) {
2529        return Err(FolderbaseError::UnsafePath(canonical_path));
2530    }
2531    verify_file_content(&materialized, &current.content)
2532}
2533
2534fn verify_history_transfer_ownership_boundaries(plan: &HistoryTransferPlan) -> Result<()> {
2535    validate_history_transfer_plan(
2536        plan,
2537        &history_transfer_plan_path(&plan.source_root, &plan.id),
2538    )?;
2539    let source_identity = read_folderbase_identity(&plan.source_root)?;
2540    let destination_identity = read_folderbase_identity(&plan.destination_root)?;
2541    if source_identity.id != plan.source_folderbase_id
2542        || destination_identity.id != plan.destination_folderbase_id
2543    {
2544        return Err(FolderbaseError::PlanPreconditionChanged(
2545            plan.source_root.clone(),
2546        ));
2547    }
2548    if !has_nested_folderbase_marker(&plan.destination_root)? {
2549        return Err(FolderbaseError::UnsafePath(plan.destination_root.clone()));
2550    }
2551    let nested_root = plan
2552        .destination_root
2553        .strip_prefix(&plan.source_root)
2554        .map_err(|_| FolderbaseError::UnsafePath(plan.destination_root.clone()))?;
2555    if Path::new(&plan.object.path)
2556        != safe_content_path(nested_root)?.join(Path::new(&plan.destination_path))
2557    {
2558        return Err(invalid_record(
2559            history_transfer_plan_path(&plan.source_root, &plan.id),
2560            "approved source and destination paths no longer map to one materialized object",
2561        ));
2562    }
2563    Ok(())
2564}
2565
2566fn verify_history_transfer_receipts(plan: &HistoryTransferPlan) -> Result<()> {
2567    let expected = history_transfer_receipt(plan)?;
2568    for path in [
2569        outgoing_history_transfer_path(&plan.source_root, &plan.object.id),
2570        incoming_history_transfer_path(&plan.destination_root, &plan.object.id),
2571    ] {
2572        let installed: HistoryTransferReceipt = read_json(&path)?;
2573        validate_history_transfer_receipt(&installed, &path)?;
2574        if installed != expected {
2575            return Err(invalid_record(
2576                path,
2577                "history-transfer receipt does not match the approved transfer",
2578            ));
2579        }
2580    }
2581    Ok(())
2582}
2583
2584fn load_history_transfer_plan(root: &Path, transfer_id: &str) -> Result<HistoryTransferPlan> {
2585    validate_prefixed_uuid(transfer_id, "history_transfer_", root)?;
2586    let path = history_transfer_plan_path(root, transfer_id);
2587    let plan: HistoryTransferPlan = read_json(&path)?;
2588    validate_history_transfer_plan(&plan, &path)?;
2589    if plan.id != transfer_id || plan.source_root != root {
2590        return Err(invalid_record(
2591            path,
2592            "history-transfer plan ID or source root is inconsistent",
2593        ));
2594    }
2595    Ok(plan)
2596}
2597
2598fn validate_history_transfer_plan(plan: &HistoryTransferPlan, path: &Path) -> Result<()> {
2599    if plan.protocol_version != "0.1.0"
2600        || plan.source_root == plan.destination_root
2601        || plan
2602            .destination_root
2603            .strip_prefix(&plan.source_root)
2604            .is_err()
2605        || plan.object.versions.is_empty()
2606        || plan.object.versions.len() != plan.versions.len()
2607        || plan
2608            .object
2609            .versions
2610            .iter()
2611            .zip(&plan.versions)
2612            .any(|(id, version)| id != &version.id || version.object_id != plan.object.id)
2613        || !plan.object.versions.contains(&plan.object.current_version)
2614        || safe_content_path(Path::new(&plan.destination_path)).is_err()
2615    {
2616        return Err(invalid_record(
2617            path,
2618            "history-transfer plan metadata is inconsistent",
2619        ));
2620    }
2621    validate_prefixed_uuid(&plan.id, "history_transfer_", path)?;
2622    validate_prefixed_uuid(&plan.source_folderbase_id, "folderbase_", path)?;
2623    validate_prefixed_uuid(&plan.destination_folderbase_id, "folderbase_", path)?;
2624    let approval_is_consistent = match plan.state {
2625        HistoryTransferState::Proposed => plan.approval_digest.is_none(),
2626        HistoryTransferState::Approved
2627        | HistoryTransferState::Applying
2628        | HistoryTransferState::DestinationVerified
2629        | HistoryTransferState::SourceReleased
2630        | HistoryTransferState::Verified
2631        | HistoryTransferState::Conflicted => plan.approval_digest.is_some(),
2632    };
2633    if !approval_is_consistent {
2634        return Err(invalid_record(
2635            path,
2636            "history-transfer approval metadata is inconsistent with its state",
2637        ));
2638    }
2639    if let Some(approval_digest) = &plan.approval_digest
2640        && history_transfer_digest(plan)? != *approval_digest
2641    {
2642        return Err(FolderbaseError::MigrationApprovalMismatch);
2643    }
2644    Ok(())
2645}
2646
2647fn history_transfer_digest(plan: &HistoryTransferPlan) -> Result<String> {
2648    let bytes = serde_json::to_vec(&(
2649        &plan.protocol_version,
2650        &plan.id,
2651        &plan.source_root,
2652        &plan.destination_root,
2653        &plan.source_folderbase_id,
2654        &plan.destination_folderbase_id,
2655        &plan.source_manifest_sha256,
2656        &plan.destination_manifest_sha256,
2657        &plan.object,
2658        &plan.destination_path,
2659        &plan.versions,
2660        HistoryTransferState::Approved,
2661    ))
2662    .map_err(|source| FolderbaseError::json(&plan.source_root, source))?;
2663    Ok(digest_hex(Sha256::digest(&bytes).as_slice()))
2664}
2665
2666fn persist_history_transfer_plan(plan: &HistoryTransferPlan) -> Result<()> {
2667    write_json_replace(
2668        &history_transfer_plan_path(&plan.source_root, &plan.id),
2669        plan,
2670    )
2671}
2672
2673fn history_transfer_receipt(plan: &HistoryTransferPlan) -> Result<HistoryTransferReceipt> {
2674    Ok(HistoryTransferReceipt {
2675        protocol_version: "0.1.0".to_owned(),
2676        transfer_id: plan.id.clone(),
2677        source_folderbase_id: plan.source_folderbase_id.clone(),
2678        destination_folderbase_id: plan.destination_folderbase_id.clone(),
2679        object_id: plan.object.id.clone(),
2680        approval_digest: plan
2681            .approval_digest
2682            .clone()
2683            .ok_or(FolderbaseError::MigrationApprovalMismatch)?,
2684        version_ids: plan.object.versions.clone(),
2685    })
2686}
2687
2688fn validate_history_transfer_receipt(receipt: &HistoryTransferReceipt, path: &Path) -> Result<()> {
2689    if receipt.protocol_version != "0.1.0" || receipt.version_ids.is_empty() {
2690        return Err(invalid_record(
2691            path,
2692            "history-transfer receipt metadata is inconsistent",
2693        ));
2694    }
2695    validate_prefixed_uuid(&receipt.transfer_id, "history_transfer_", path)?;
2696    validate_prefixed_uuid(&receipt.source_folderbase_id, "folderbase_", path)?;
2697    validate_prefixed_uuid(&receipt.destination_folderbase_id, "folderbase_", path)?;
2698    receipt.object_id.validate(path)?;
2699    for version_id in &receipt.version_ids {
2700        version_id.validate(path)?;
2701    }
2702    Ok(())
2703}
2704
2705fn install_or_verify_history_transfer_receipt(
2706    path: &Path,
2707    receipt: &HistoryTransferReceipt,
2708) -> Result<()> {
2709    validate_history_transfer_receipt(receipt, path)?;
2710    install_or_verify_json(path, receipt)
2711}
2712
2713fn install_or_verify_content_file(
2714    source: &Path,
2715    destination: &Path,
2716    expected: &ContentDigest,
2717) -> Result<()> {
2718    match read_optional_file_nofollow(destination)? {
2719        Some(_) => verify_file_content(destination, expected),
2720        None => copy_verified_new(source, destination, expected),
2721    }
2722}
2723
2724fn install_or_verify_json(path: &Path, value: &impl Serialize) -> Result<()> {
2725    let expected = json_bytes(path, value)?;
2726    match read_optional_file_nofollow(path)? {
2727        Some(existing) if existing == expected => Ok(()),
2728        Some(_) => Err(FolderbaseError::WouldOverwrite(path.to_path_buf())),
2729        None => write_bytes_new(path, &expected),
2730    }
2731}
2732
2733fn history_transfer_result(plan: &HistoryTransferPlan) -> HistoryTransferResult {
2734    HistoryTransferResult {
2735        transfer_id: plan.id.clone(),
2736        source_folderbase_id: plan.source_folderbase_id.clone(),
2737        destination_folderbase_id: plan.destination_folderbase_id.clone(),
2738        object_id: plan.object.id.clone(),
2739        state: plan.state,
2740        version_ids: plan.object.versions.clone(),
2741    }
2742}
2743
2744fn history_transfer_state_name(state: HistoryTransferState) -> &'static str {
2745    match state {
2746        HistoryTransferState::Proposed => "proposed",
2747        HistoryTransferState::Approved => "approved",
2748        HistoryTransferState::Applying => "applying",
2749        HistoryTransferState::DestinationVerified => "destination_verified",
2750        HistoryTransferState::SourceReleased => "source_released",
2751        HistoryTransferState::Verified => "verified",
2752        HistoryTransferState::Conflicted => "conflicted",
2753    }
2754}
2755
2756fn history_transfer_staging_root(root: &Path, transfer_id: &str) -> PathBuf {
2757    root.join(HISTORY_TRANSFER_STAGING_DIRECTORY)
2758        .join(transfer_id)
2759}
2760
2761fn outgoing_history_transfer_path(root: &Path, object_id: &ObjectId) -> PathBuf {
2762    root.join(HISTORY_TRANSFER_OUTGOING_DIRECTORY)
2763        .join(format!("{object_id}.json"))
2764}
2765
2766fn incoming_history_transfer_path(root: &Path, object_id: &ObjectId) -> PathBuf {
2767    root.join(HISTORY_TRANSFER_INCOMING_DIRECTORY)
2768        .join(format!("{object_id}.json"))
2769}
2770
2771fn cleanup_history_transfer_staging(root: &Path, transfer_id: &str) -> Result<()> {
2772    let staging = history_transfer_staging_root(root, transfer_id);
2773    match fs::remove_dir_all(&staging) {
2774        Ok(()) => sync_parent_directory(&staging),
2775        Err(source) if source.kind() == std::io::ErrorKind::NotFound => Ok(()),
2776        Err(source) => Err(FolderbaseError::io(staging, source)),
2777    }
2778}
2779
2780fn mark_history_transfer_conflicted(
2781    plan: &mut HistoryTransferPlan,
2782    error: FolderbaseError,
2783) -> FolderbaseError {
2784    plan.state = HistoryTransferState::Conflicted;
2785    match persist_history_transfer_plan(plan) {
2786        Ok(()) => error,
2787        Err(persistence_error) => persistence_error,
2788    }
2789}
2790
2791fn mark_released_history_transfer_conflicted(
2792    plan: &mut HistoryTransferPlan,
2793    error: FolderbaseError,
2794) -> FolderbaseError {
2795    if plan.state == HistoryTransferState::SourceReleased {
2796        mark_history_transfer_conflicted(plan, error)
2797    } else {
2798        error
2799    }
2800}
2801
2802fn validate_pending_transaction(transaction: &PendingTransaction, path: &Path) -> Result<()> {
2803    if transaction.protocol_version != "0.1.0"
2804        || !transaction.id.starts_with("transaction_")
2805        || Uuid::parse_str(
2806            transaction
2807                .id
2808                .strip_prefix("transaction_")
2809                .unwrap_or_default(),
2810        )
2811        .is_err()
2812        || transaction.events.is_empty()
2813    {
2814        return Err(invalid_record(
2815            path,
2816            "pending transaction has an invalid protocol version, ID, or empty event list",
2817        ));
2818    }
2819
2820    transaction.object.id.validate(path)?;
2821    safe_content_path(Path::new(&transaction.object.path))
2822        .map_err(|_| invalid_record(path, "pending transaction has an unsafe object path"))?;
2823    if transaction.object.versions.is_empty()
2824        || !transaction
2825            .object
2826            .versions
2827            .contains(&transaction.object.current_version)
2828    {
2829        return Err(invalid_record(
2830            path,
2831            "pending transaction projection has an invalid version history",
2832        ));
2833    }
2834
2835    if let Some(version) = &transaction.version {
2836        version.id.validate(path)?;
2837        version.object_id.validate(path)?;
2838        validate_content_digest(&version.content, path)?;
2839        if version.object_id != transaction.object.id
2840            || version.id != transaction.object.current_version
2841            || !transaction.object.versions.contains(&version.id)
2842        {
2843            return Err(invalid_record(
2844                path,
2845                "pending version does not match the object projection",
2846            ));
2847        }
2848    }
2849
2850    for version in &transaction.versions {
2851        version.id.validate(path)?;
2852        version.object_id.validate(path)?;
2853        validate_content_digest(&version.content, path)?;
2854        if version.object_id != transaction.object.id
2855            || !transaction.object.versions.contains(&version.id)
2856        {
2857            return Err(invalid_record(
2858                path,
2859                "pending version does not match the object projection",
2860            ));
2861        }
2862    }
2863
2864    if let Some(replacement) = &transaction.replacement {
2865        validate_content_digest(&replacement.previous_content, path)?;
2866        validate_content_digest(&replacement.content, path)?;
2867        safe_content_path(Path::new(&replacement.destination))
2868            .map_err(|_| invalid_record(path, "pending replacement has an unsafe destination"))?;
2869        let current = transaction
2870            .versions
2871            .iter()
2872            .chain(transaction.version.iter())
2873            .find(|version| version.id == transaction.object.current_version);
2874        if transaction.restore.is_some()
2875            || replacement.destination != transaction.object.path
2876            || replacement.previous_content == replacement.content
2877            || current.map(|version| &version.content) != Some(&replacement.content)
2878        {
2879            return Err(invalid_record(
2880                path,
2881                "pending replacement does not match the object projection",
2882            ));
2883        }
2884    }
2885
2886    if let Some(restore) = &transaction.restore {
2887        restore.version_id.validate(path)?;
2888        validate_content_digest(&restore.content, path)?;
2889        safe_content_path(Path::new(&restore.destination))
2890            .map_err(|_| invalid_record(path, "pending restore has an unsafe destination"))?;
2891        if transaction.version.is_some()
2892            || !transaction.versions.is_empty()
2893            || transaction.replacement.is_some()
2894            || transaction.events.len() != 1
2895        {
2896            return Err(invalid_record(
2897                path,
2898                "pending restore must contain one restore event and no new version",
2899            ));
2900        }
2901        let event = &transaction.events[0];
2902        if event.action != JournalAction::VersionRestored
2903            || event.version_id.as_ref() != Some(&restore.version_id)
2904            || event.content.as_ref() != Some(&restore.content)
2905            || event.path != restore.destination
2906            || event.previous_path.is_some()
2907        {
2908            return Err(invalid_record(
2909                path,
2910                "pending restore does not match its restore event",
2911            ));
2912        }
2913    }
2914
2915    for event in &transaction.events {
2916        validate_journal_event(event, path, 0)?;
2917        if event.object_id != transaction.object.id {
2918            return Err(invalid_record(
2919                path,
2920                "pending journal event belongs to a different object",
2921            ));
2922        }
2923    }
2924    Ok(())
2925}
2926
2927fn maybe_fail_workspace_checkpoint(
2928    transaction: &PendingTransaction,
2929    checkpoint: &str,
2930    _path: &Path,
2931) -> Result<()> {
2932    let applies_to_workspace_save = transaction.replacement.is_some();
2933    let applies_to_restore = transaction.restore.is_some() && checkpoint == "restore-published";
2934    if !applies_to_workspace_save && !applies_to_restore {
2935        return Ok(());
2936    }
2937    #[cfg(debug_assertions)]
2938    if std::env::var("FOLDERBASE_TEST_FAIL_AFTER_WORKSPACE_CHECKPOINT").as_deref() == Ok(checkpoint)
2939    {
2940        return Err(FolderbaseError::io(
2941            _path,
2942            std::io::Error::new(
2943                std::io::ErrorKind::Interrupted,
2944                format!("simulated interruption after {checkpoint}"),
2945            ),
2946        ));
2947    }
2948    Ok(())
2949}
2950
2951fn parse_journal_bytes(
2952    path: &Path,
2953    bytes: &[u8],
2954    tolerate_incomplete_tail: bool,
2955) -> Result<Vec<ObjectJournalEvent>> {
2956    let mut events = Vec::new();
2957    let mut start = 0;
2958    let mut line_number = 1;
2959
2960    for (index, byte) in bytes.iter().enumerate() {
2961        if *byte != b'\n' {
2962            continue;
2963        }
2964        let line = &bytes[start..index];
2965        if line.is_empty() {
2966            return Err(invalid_record(
2967                path,
2968                format!("journal line {line_number} is empty"),
2969            ));
2970        }
2971        let event: ObjectJournalEvent =
2972            serde_json::from_slice(line).map_err(|source| FolderbaseError::Json {
2973                path: path.to_path_buf(),
2974                source,
2975            })?;
2976        validate_journal_event(&event, path, line_number)?;
2977        events.push(event);
2978        start = index + 1;
2979        line_number += 1;
2980    }
2981
2982    if start < bytes.len() {
2983        match serde_json::from_slice::<ObjectJournalEvent>(&bytes[start..]) {
2984            Ok(event) => {
2985                validate_journal_event(&event, path, line_number)?;
2986                events.push(event);
2987            }
2988            Err(_) if tolerate_incomplete_tail => {}
2989            Err(source) => {
2990                return Err(FolderbaseError::Json {
2991                    path: path.to_path_buf(),
2992                    source,
2993                });
2994            }
2995        }
2996    }
2997    Ok(events)
2998}
2999
3000fn validate_journal_event(event: &ObjectJournalEvent, path: &Path, line: usize) -> Result<()> {
3001    if !event.id.starts_with("event_")
3002        || Uuid::parse_str(event.id.strip_prefix("event_").unwrap_or_default()).is_err()
3003    {
3004        return Err(invalid_record(
3005            path,
3006            journal_message(line, "has an invalid event ID"),
3007        ));
3008    }
3009    event.object_id.validate(path)?;
3010    if let Some(version_id) = &event.version_id {
3011        version_id.validate(path)?;
3012    }
3013    safe_content_path(Path::new(&event.path))
3014        .map_err(|_| invalid_record(path, journal_message(line, "has an unsafe content path")))?;
3015    if let Some(previous_path) = &event.previous_path {
3016        safe_content_path(Path::new(previous_path)).map_err(|_| {
3017            invalid_record(path, journal_message(line, "has an unsafe previous path"))
3018        })?;
3019    }
3020    if let Some(content) = &event.content {
3021        validate_content_digest(content, path)?;
3022    }
3023    Ok(())
3024}
3025
3026fn journal_message(line: usize, message: &str) -> String {
3027    if line == 0 {
3028        format!("journal event {message}")
3029    } else {
3030        format!("journal line {line} {message}")
3031    }
3032}
3033
3034pub(crate) fn safe_content_path(path: &Path) -> Result<PathBuf> {
3035    if path.as_os_str().is_empty() || path.is_absolute() || path.to_str().is_none() {
3036        return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
3037    }
3038
3039    let mut normalized = PathBuf::new();
3040    for component in path.components() {
3041        let Component::Normal(name) = component else {
3042            return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
3043        };
3044        if is_reserved_workspace_component(name) {
3045            return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
3046        }
3047        normalized.push(name);
3048    }
3049    if normalized.as_os_str().is_empty() {
3050        return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
3051    }
3052    Ok(normalized)
3053}
3054
3055fn relative_path_to_string(path: &Path) -> Result<String> {
3056    let safe = safe_content_path(path)?;
3057    safe.to_str()
3058        .map(ToOwned::to_owned)
3059        .ok_or_else(|| FolderbaseError::UnsafePath(path.to_path_buf()))
3060}
3061
3062fn paths_equal_ignoring_ascii_case(left: &Path, right: &Path) -> bool {
3063    left.to_str()
3064        .zip(right.to_str())
3065        .is_some_and(|(left, right)| left.eq_ignore_ascii_case(right))
3066}
3067
3068fn find_case_folded_child(parent: &Path, expected: &std::ffi::OsStr) -> Result<Option<PathBuf>> {
3069    let expected = expected
3070        .to_str()
3071        .ok_or_else(|| FolderbaseError::UnsafePath(parent.join(expected)))?;
3072    let entries = fs::read_dir(parent).map_err(|source| FolderbaseError::io(parent, source))?;
3073    let mut found = None;
3074    for entry in entries {
3075        let entry = entry.map_err(|source| FolderbaseError::io(parent, source))?;
3076        if entry
3077            .file_name()
3078            .to_str()
3079            .is_some_and(|name| name.eq_ignore_ascii_case(expected))
3080        {
3081            if found.is_some() {
3082                return Err(FolderbaseError::UnsafePath(parent.join(expected)));
3083            }
3084            found = Some(entry.path());
3085        }
3086    }
3087    Ok(found)
3088}
3089
3090fn resolve_without_symlinks(
3091    root: &Path,
3092    relative_path: &Path,
3093    create_parents: bool,
3094) -> Result<PathBuf> {
3095    let relative_path = safe_content_path(relative_path)?;
3096    let mut resolved = root.to_path_buf();
3097    let parent = relative_path.parent().unwrap_or_else(|| Path::new(""));
3098    for component in parent.components() {
3099        let Component::Normal(component) = component else {
3100            return Err(FolderbaseError::UnsafePath(relative_path));
3101        };
3102        resolved.push(component);
3103        match fs::symlink_metadata(&resolved) {
3104            Ok(metadata) if metadata.file_type().is_symlink() || !metadata.is_dir() => {
3105                return Err(FolderbaseError::UnsafePath(resolved));
3106            }
3107            Ok(_) => {}
3108            Err(source) if create_parents && source.kind() == std::io::ErrorKind::NotFound => {
3109                create_directory_durable(&resolved)?;
3110            }
3111            Err(source) => return Err(FolderbaseError::io(&resolved, source)),
3112        }
3113        if has_nested_folderbase_marker(&resolved)? {
3114            return Err(FolderbaseError::UnsafePath(relative_path));
3115        }
3116    }
3117    Ok(root.join(relative_path))
3118}
3119
3120fn ensure_directory_chain(root: &Path, relative_path: &Path) -> Result<()> {
3121    let mut current = root.to_path_buf();
3122    for component in relative_path.components() {
3123        let Component::Normal(component) = component else {
3124            return Err(FolderbaseError::UnsafePath(relative_path.to_path_buf()));
3125        };
3126        current.push(component);
3127        match fs::symlink_metadata(&current) {
3128            Ok(metadata) if metadata.file_type().is_symlink() || !metadata.is_dir() => {
3129                return Err(FolderbaseError::UnsafePath(current));
3130            }
3131            Ok(_) => {}
3132            Err(source) if source.kind() == std::io::ErrorKind::NotFound => {
3133                match create_private_directory_durable(&current) {
3134                    Ok(()) => {}
3135                    Err(FolderbaseError::Io { source, .. })
3136                        if source.kind() == std::io::ErrorKind::AlreadyExists =>
3137                    {
3138                        let metadata = fs::symlink_metadata(&current)
3139                            .map_err(|source| FolderbaseError::io(&current, source))?;
3140                        if metadata.file_type().is_symlink() || !metadata.is_dir() {
3141                            return Err(FolderbaseError::UnsafePath(current));
3142                        }
3143                    }
3144                    Err(error) => return Err(error),
3145                }
3146            }
3147            Err(source) => return Err(FolderbaseError::io(&current, source)),
3148        }
3149    }
3150    Ok(())
3151}
3152
3153fn validate_prefixed_uuid(value: &str, prefix: &str, record_path: &Path) -> Result<()> {
3154    let Some(uuid) = value.strip_prefix(prefix) else {
3155        return Err(invalid_record(
3156            record_path,
3157            format!("identifier must start with {prefix}"),
3158        ));
3159    };
3160    Uuid::parse_str(uuid)
3161        .map(|_| ())
3162        .map_err(|_| invalid_record(record_path, "identifier suffix is not a UUID"))
3163}
3164
3165fn read_folderbase_identity(root: &Path) -> Result<FolderbaseIdentity> {
3166    let path = root.join(".folderbase/manifest.json");
3167    let bytes = read_optional_file_nofollow(&path)?
3168        .ok_or_else(|| FolderbaseError::io(&path, std::io::ErrorKind::NotFound.into()))?;
3169    let id = folderbase_id_from_manifest_bytes(&bytes, &path)?;
3170    Ok(FolderbaseIdentity {
3171        id,
3172        manifest_sha256: digest_hex(Sha256::digest(&bytes).as_slice()),
3173    })
3174}
3175
3176pub(crate) fn folderbase_id_from_manifest_bytes(bytes: &[u8], path: &Path) -> Result<String> {
3177    let manifest: Value =
3178        serde_json::from_slice(bytes).map_err(|source| FolderbaseError::json(path, source))?;
3179    let id = manifest
3180        .get("folderbase")
3181        .and_then(|folderbase| folderbase.get("id"))
3182        .and_then(Value::as_str)
3183        .ok_or_else(|| invalid_record(path, "manifest is missing folderbase.id"))?
3184        .to_owned();
3185    validate_prefixed_uuid(&id, "folderbase_", path)?;
3186    Ok(id)
3187}
3188
3189pub(crate) fn validate_chunk_transfer_receipt_bytes(
3190    bytes: &[u8],
3191    path: &Path,
3192    object_id: &ObjectId,
3193    source_folderbase_id: &str,
3194) -> Result<()> {
3195    let receipt: HistoryTransferReceipt =
3196        serde_json::from_slice(bytes).map_err(|source| FolderbaseError::json(path, source))?;
3197    validate_history_transfer_receipt(&receipt, path)?;
3198    if receipt.object_id != *object_id || receipt.source_folderbase_id != source_folderbase_id {
3199        return Err(invalid_record(
3200            path,
3201            "outgoing history-transfer receipt does not match this folderbase or object",
3202        ));
3203    }
3204    Err(invalid_record(
3205        path,
3206        format!(
3207            "object history transferred to folderbase {}",
3208            receipt.destination_folderbase_id
3209        ),
3210    ))
3211}
3212
3213fn history_transfer_plan_path(root: &Path, transfer_id: &str) -> PathBuf {
3214    root.join(HISTORY_TRANSFER_INTENTS_DIRECTORY)
3215        .join(format!("{transfer_id}.json"))
3216}
3217
3218fn validate_content_digest(content: &ContentDigest, record_path: &Path) -> Result<()> {
3219    if content.algorithm != "sha256"
3220        || content.digest.len() != 64
3221        || !content
3222            .digest
3223            .bytes()
3224            .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
3225    {
3226        return Err(invalid_record(
3227            record_path,
3228            "content digest is not a lowercase SHA-256 digest",
3229        ));
3230    }
3231    Ok(())
3232}
3233
3234#[cfg(unix)]
3235fn filesystem_identity(metadata: &fs::Metadata) -> Option<FileSystemIdentity> {
3236    use std::os::unix::fs::MetadataExt;
3237
3238    Some(FileSystemIdentity {
3239        device: metadata.dev(),
3240        inode: metadata.ino(),
3241    })
3242}
3243
3244#[cfg(not(unix))]
3245fn filesystem_identity(_metadata: &fs::Metadata) -> Option<FileSystemIdentity> {
3246    None
3247}
3248
3249fn verify_file_content(path: &Path, expected: &ContentDigest) -> Result<()> {
3250    validate_content_digest(expected, path)?;
3251    let file = open_existing_nofollow(path)?;
3252    let actual = hash_reader(file, path)?;
3253    if actual != *expected {
3254        return Err(invalid_record(
3255            path,
3256            format!(
3257                "content integrity mismatch: expected {} bytes with digest {}, found {} bytes with digest {}",
3258                expected.bytes, expected.digest, actual.bytes, actual.digest
3259            ),
3260        ));
3261    }
3262    Ok(())
3263}
3264
3265fn hash_reader(mut reader: impl Read, path: &Path) -> Result<ContentDigest> {
3266    let mut hasher = Sha256::new();
3267    let mut bytes = 0_u64;
3268    let mut buffer = [0_u8; COPY_BUFFER_BYTES];
3269    loop {
3270        let read = reader
3271            .read(&mut buffer)
3272            .map_err(|source| FolderbaseError::io(path, source))?;
3273        if read == 0 {
3274            break;
3275        }
3276        hasher.update(&buffer[..read]);
3277        bytes = bytes
3278            .checked_add(read as u64)
3279            .ok_or_else(|| invalid_record(path, "content length exceeds supported range"))?;
3280    }
3281    Ok(ContentDigest {
3282        algorithm: "sha256".to_owned(),
3283        digest: digest_hex(hasher.finalize().as_slice()),
3284        bytes,
3285    })
3286}
3287
3288fn copy_verified_new(source: &Path, destination: &Path, expected: &ContentDigest) -> Result<()> {
3289    let parent = destination
3290        .parent()
3291        .ok_or_else(|| FolderbaseError::UnsafePath(destination.to_path_buf()))?;
3292    let mut input = open_existing_nofollow(source)?;
3293    let staged_path = unique_staged_path(parent, "restore");
3294    let mut staged = open_new(&staged_path)?;
3295    let mut hasher = Sha256::new();
3296    let mut bytes = 0_u64;
3297    let mut buffer = [0_u8; COPY_BUFFER_BYTES];
3298
3299    let copy_result = (|| -> Result<()> {
3300        loop {
3301            let read = input
3302                .read(&mut buffer)
3303                .map_err(|source_error| FolderbaseError::io(source, source_error))?;
3304            if read == 0 {
3305                break;
3306            }
3307            staged
3308                .write_all(&buffer[..read])
3309                .map_err(|source_error| FolderbaseError::io(&staged_path, source_error))?;
3310            hasher.update(&buffer[..read]);
3311            bytes = bytes
3312                .checked_add(read as u64)
3313                .ok_or_else(|| invalid_record(source, "content length exceeds supported range"))?;
3314        }
3315        staged
3316            .sync_all()
3317            .map_err(|source_error| FolderbaseError::io(&staged_path, source_error))?;
3318        Ok(())
3319    })();
3320    drop(staged);
3321    if let Err(error) = copy_result {
3322        let _ = fs::remove_file(&staged_path);
3323        return Err(error);
3324    }
3325
3326    let copied = ContentDigest {
3327        algorithm: "sha256".to_owned(),
3328        digest: digest_hex(hasher.finalize().as_slice()),
3329        bytes,
3330    };
3331    if copied != *expected {
3332        let _ = fs::remove_file(&staged_path);
3333        return Err(invalid_record(
3334            source,
3335            "blob changed while it was being restored",
3336        ));
3337    }
3338    match install_no_clobber(&staged_path, destination) {
3339        Ok(()) => sync_parent_directory(destination),
3340        Err(source_error) => {
3341            let _ = fs::remove_file(&staged_path);
3342            if source_error.kind() == std::io::ErrorKind::AlreadyExists {
3343                Err(FolderbaseError::WouldOverwrite(destination.to_path_buf()))
3344            } else {
3345                Err(FolderbaseError::io(destination, source_error))
3346            }
3347        }
3348    }
3349}
3350
3351fn replace_verified(
3352    source: &Path,
3353    destination: &Path,
3354    expected: &ContentDigest,
3355    replacement: &PendingReplacement,
3356) -> Result<()> {
3357    let parent = destination
3358        .parent()
3359        .ok_or_else(|| FolderbaseError::UnsafePath(destination.to_path_buf()))?;
3360    let parent_file = open_directory_nofollow(parent)?;
3361    let parent_identity = filesystem_identity(
3362        &parent_file
3363            .metadata()
3364            .map_err(|source_error| FolderbaseError::io(parent, source_error))?,
3365    );
3366    if replacement
3367        .parent_identity
3368        .as_ref()
3369        .is_some_and(|expected| parent_identity.as_ref() != Some(expected))
3370    {
3371        return Err(FolderbaseError::WorkspaceContentChanged(PathBuf::from(
3372            &replacement.destination,
3373        )));
3374    }
3375    let destination_file = open_existing_nofollow(destination)?;
3376    let destination_identity = filesystem_identity(
3377        &destination_file
3378            .metadata()
3379            .map_err(|source_error| FolderbaseError::io(destination, source_error))?,
3380    );
3381    if replacement
3382        .file_identity
3383        .as_ref()
3384        .is_some_and(|expected| destination_identity.as_ref() != Some(expected))
3385    {
3386        return Err(FolderbaseError::WorkspaceContentChanged(PathBuf::from(
3387            &replacement.destination,
3388        )));
3389    }
3390    let mut input = open_existing_nofollow(source)?;
3391    let staged_path = unique_staged_path(parent, "workspace-save");
3392    let mut staged = open_new(&staged_path)?;
3393    let mut hasher = Sha256::new();
3394    let mut bytes = 0_u64;
3395    let mut buffer = [0_u8; COPY_BUFFER_BYTES];
3396
3397    let copy_result = (|| -> Result<()> {
3398        loop {
3399            let read = input
3400                .read(&mut buffer)
3401                .map_err(|source_error| FolderbaseError::io(source, source_error))?;
3402            if read == 0 {
3403                break;
3404            }
3405            staged
3406                .write_all(&buffer[..read])
3407                .map_err(|source_error| FolderbaseError::io(&staged_path, source_error))?;
3408            hasher.update(&buffer[..read]);
3409            bytes = bytes
3410                .checked_add(read as u64)
3411                .ok_or_else(|| invalid_record(source, "content length exceeds supported range"))?;
3412        }
3413
3414        #[cfg(unix)]
3415        if let Some(mode) = replacement.unix_mode {
3416            use std::os::unix::fs::PermissionsExt;
3417            staged
3418                .set_permissions(fs::Permissions::from_mode(mode))
3419                .map_err(|source_error| FolderbaseError::io(&staged_path, source_error))?;
3420        }
3421        #[cfg(not(unix))]
3422        {
3423            let mut permissions = staged
3424                .metadata()
3425                .map_err(|source_error| FolderbaseError::io(&staged_path, source_error))?
3426                .permissions();
3427            permissions.set_readonly(replacement.readonly);
3428            staged
3429                .set_permissions(permissions)
3430                .map_err(|source_error| FolderbaseError::io(&staged_path, source_error))?;
3431        }
3432
3433        copy_ordinary_file_metadata(&destination_file, &staged, destination)?;
3434        staged
3435            .sync_all()
3436            .map_err(|source_error| FolderbaseError::io(&staged_path, source_error))?;
3437        Ok(())
3438    })();
3439    drop(staged);
3440    if let Err(error) = copy_result {
3441        let _ = fs::remove_file(&staged_path);
3442        return Err(error);
3443    }
3444
3445    let copied = ContentDigest {
3446        algorithm: "sha256".to_owned(),
3447        digest: digest_hex(hasher.finalize().as_slice()),
3448        bytes,
3449    };
3450    if copied != *expected {
3451        let _ = fs::remove_file(&staged_path);
3452        return Err(invalid_record(
3453            source,
3454            "blob changed while workspace content was being staged",
3455        ));
3456    }
3457
3458    let final_check = (|| -> Result<()> {
3459        let current_parent_identity = filesystem_identity(
3460            &fs::metadata(parent)
3461                .map_err(|source_error| FolderbaseError::io(parent, source_error))?,
3462        );
3463        if current_parent_identity != parent_identity {
3464            return Err(FolderbaseError::WorkspaceContentChanged(PathBuf::from(
3465                &replacement.destination,
3466            )));
3467        }
3468
3469        let current_file = open_existing_nofollow(destination)?;
3470        let current_identity = filesystem_identity(
3471            &current_file
3472                .metadata()
3473                .map_err(|source_error| FolderbaseError::io(destination, source_error))?,
3474        );
3475        if current_identity != destination_identity {
3476            return Err(FolderbaseError::WorkspaceContentChanged(PathBuf::from(
3477                &replacement.destination,
3478            )));
3479        }
3480        let current_content = hash_reader(current_file, destination)?;
3481        if current_content != replacement.previous_content {
3482            return Err(FolderbaseError::WorkspaceContentChanged(PathBuf::from(
3483                &replacement.destination,
3484            )));
3485        }
3486        Ok(())
3487    })();
3488    if let Err(error) = final_check {
3489        let _ = fs::remove_file(&staged_path);
3490        return Err(error);
3491    }
3492
3493    // POSIX rename is atomic but is not an atomic compare-and-swap. The
3494    // identity and digest check above is intentionally adjacent to the
3495    // replace; File Provider/NSFileCoordinator is still required to close the
3496    // final check-to-rename window against an uncooperative external writer.
3497    fs::rename(&staged_path, destination).map_err(|source_error| {
3498        let _ = fs::remove_file(&staged_path);
3499        FolderbaseError::io(destination, source_error)
3500    })?;
3501    sync_parent_directory(destination)?;
3502    verify_file_content(destination, expected)
3503}
3504
3505fn open_existing_nofollow(path: &Path) -> Result<File> {
3506    let path_metadata =
3507        fs::symlink_metadata(path).map_err(|source| FolderbaseError::io(path, source))?;
3508    if path_metadata.file_type().is_symlink() || !path_metadata.is_file() {
3509        return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
3510    }
3511
3512    let mut options = OpenOptions::new();
3513    options.read(true);
3514    #[cfg(unix)]
3515    {
3516        use std::os::unix::fs::OpenOptionsExt;
3517        options.custom_flags(libc::O_NOFOLLOW);
3518    }
3519    let file = options
3520        .open(path)
3521        .map_err(|source| FolderbaseError::io(path, source))?;
3522    let opened_metadata = file
3523        .metadata()
3524        .map_err(|source| FolderbaseError::io(path, source))?;
3525    if !opened_metadata.is_file()
3526        || filesystem_identity(&path_metadata) != filesystem_identity(&opened_metadata)
3527    {
3528        return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
3529    }
3530    Ok(file)
3531}
3532
3533fn read_optional_file_nofollow(path: &Path) -> Result<Option<Vec<u8>>> {
3534    let mut file = match open_existing_nofollow(path) {
3535        Ok(file) => file,
3536        Err(FolderbaseError::Io { source, .. })
3537            if source.kind() == std::io::ErrorKind::NotFound =>
3538        {
3539            return Ok(None);
3540        }
3541        Err(error) => return Err(error),
3542    };
3543    let mut bytes = Vec::new();
3544    file.read_to_end(&mut bytes)
3545        .map_err(|source| FolderbaseError::io(path, source))?;
3546    Ok(Some(bytes))
3547}
3548
3549fn open_directory_nofollow(path: &Path) -> Result<File> {
3550    let mut options = OpenOptions::new();
3551    options.read(true);
3552    #[cfg(unix)]
3553    {
3554        use std::os::unix::fs::OpenOptionsExt;
3555        options.custom_flags(libc::O_DIRECTORY | libc::O_NOFOLLOW);
3556    }
3557    let file = options
3558        .open(path)
3559        .map_err(|source| FolderbaseError::io(path, source))?;
3560    if !file
3561        .metadata()
3562        .map_err(|source| FolderbaseError::io(path, source))?
3563        .is_dir()
3564    {
3565        return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
3566    }
3567    Ok(file)
3568}
3569
3570#[cfg(target_os = "macos")]
3571fn copy_ordinary_file_metadata(source: &File, destination: &File, path: &Path) -> Result<()> {
3572    use std::os::fd::AsRawFd;
3573
3574    // Keep Finder metadata, extended attributes, and ACLs when atomically
3575    // replacing ordinary user content. COPYFILE_STAT is intentionally omitted:
3576    // an accepted edit must receive a new modification time.
3577    let flags = libc::COPYFILE_ACL | libc::COPYFILE_XATTR;
3578    if unsafe {
3579        libc::fcopyfile(
3580            source.as_raw_fd(),
3581            destination.as_raw_fd(),
3582            std::ptr::null_mut(),
3583            flags,
3584        )
3585    } != 0
3586    {
3587        return Err(FolderbaseError::io(path, std::io::Error::last_os_error()));
3588    }
3589    Ok(())
3590}
3591
3592#[cfg(not(target_os = "macos"))]
3593fn copy_ordinary_file_metadata(_source: &File, _destination: &File, _path: &Path) -> Result<()> {
3594    Ok(())
3595}
3596
3597fn read_json<T: for<'de> Deserialize<'de>>(path: &Path) -> Result<T> {
3598    let bytes = read_optional_file_nofollow(path)?.ok_or_else(|| {
3599        FolderbaseError::io(path, std::io::Error::from(std::io::ErrorKind::NotFound))
3600    })?;
3601    serde_json::from_slice(&bytes).map_err(|source| FolderbaseError::json(path, source))
3602}
3603
3604fn write_json_new(path: &Path, value: &impl Serialize) -> Result<()> {
3605    let bytes = json_bytes(path, value)?;
3606    write_bytes_new(path, &bytes)
3607}
3608
3609fn write_json_replace(path: &Path, value: &impl Serialize) -> Result<()> {
3610    let bytes = json_bytes(path, value)?;
3611    write_bytes_replace(path, &bytes)
3612}
3613
3614fn write_bytes_new(path: &Path, bytes: &[u8]) -> Result<()> {
3615    let parent = path
3616        .parent()
3617        .ok_or_else(|| FolderbaseError::UnsafePath(path.to_path_buf()))?;
3618    let staged_path = unique_staged_path(parent, "record");
3619    write_staged(&staged_path, bytes)?;
3620    match install_no_clobber(&staged_path, path) {
3621        Ok(()) => sync_parent_directory(path),
3622        Err(source) => {
3623            let _ = fs::remove_file(&staged_path);
3624            if source.kind() == std::io::ErrorKind::AlreadyExists {
3625                Err(FolderbaseError::WouldOverwrite(path.to_path_buf()))
3626            } else {
3627                Err(FolderbaseError::io(path, source))
3628            }
3629        }
3630    }
3631}
3632
3633fn write_bytes_replace(path: &Path, bytes: &[u8]) -> Result<()> {
3634    let parent = path
3635        .parent()
3636        .ok_or_else(|| FolderbaseError::UnsafePath(path.to_path_buf()))?;
3637    let staged_path = unique_staged_path(parent, "projection");
3638    write_staged(&staged_path, bytes)?;
3639    fs::rename(&staged_path, path).map_err(|source| {
3640        let _ = fs::remove_file(&staged_path);
3641        FolderbaseError::io(path, source)
3642    })?;
3643    sync_parent_directory(path)
3644}
3645
3646fn json_bytes(path: &Path, value: &impl Serialize) -> Result<Vec<u8>> {
3647    let mut bytes =
3648        serde_json::to_vec_pretty(value).map_err(|source| FolderbaseError::json(path, source))?;
3649    bytes.push(b'\n');
3650    Ok(bytes)
3651}
3652
3653fn write_staged(path: &Path, bytes: &[u8]) -> Result<()> {
3654    let mut file = open_new(path)?;
3655    let result = file.write_all(bytes).and_then(|()| file.sync_all());
3656    drop(file);
3657    if let Err(source) = result {
3658        let _ = fs::remove_file(path);
3659        return Err(FolderbaseError::io(path, source));
3660    }
3661    Ok(())
3662}
3663
3664fn open_new(path: &Path) -> Result<File> {
3665    let mut options = OpenOptions::new();
3666    options.write(true).create_new(true);
3667    #[cfg(unix)]
3668    {
3669        use std::os::unix::fs::OpenOptionsExt;
3670        options.mode(0o600).custom_flags(libc::O_NOFOLLOW);
3671    }
3672    options
3673        .open(path)
3674        .map_err(|source| FolderbaseError::io(path, source))
3675}
3676
3677fn create_private_directory_durable(path: &Path) -> Result<()> {
3678    let builder = fs::DirBuilder::new();
3679    #[cfg(unix)]
3680    let builder = {
3681        use std::os::unix::fs::DirBuilderExt;
3682        let mut builder = builder;
3683        builder.mode(0o700);
3684        builder
3685    };
3686    builder
3687        .create(path)
3688        .map_err(|source| FolderbaseError::io(path, source))?;
3689    sync_parent_directory(path)
3690}
3691
3692fn create_directory_durable(path: &Path) -> Result<()> {
3693    fs::create_dir(path).map_err(|source| FolderbaseError::io(path, source))?;
3694    sync_parent_directory(path)
3695}
3696
3697/// Install a staged file without ever replacing an existing destination.
3698fn install_no_clobber(staged: &Path, destination: &Path) -> std::io::Result<()> {
3699    fs::hard_link(staged, destination)?;
3700    fs::remove_file(staged)
3701}
3702
3703fn unique_staged_path(directory: &Path, label: &str) -> PathBuf {
3704    directory.join(format!(".{label}-{}.tmp", Uuid::now_v7()))
3705}
3706
3707#[cfg(unix)]
3708fn sync_parent_directory(path: &Path) -> Result<()> {
3709    let parent = path
3710        .parent()
3711        .ok_or_else(|| FolderbaseError::UnsafePath(path.to_path_buf()))?;
3712    File::open(parent)
3713        .and_then(|directory| directory.sync_all())
3714        .map_err(|source| FolderbaseError::io(parent, source))
3715}
3716
3717#[cfg(not(unix))]
3718fn sync_parent_directory(_path: &Path) -> Result<()> {
3719    Ok(())
3720}
3721
3722fn digest_hex(bytes: &[u8]) -> String {
3723    let mut output = String::with_capacity(bytes.len() * 2);
3724    for byte in bytes {
3725        let _ = write!(&mut output, "{byte:02x}");
3726    }
3727    output
3728}
3729
3730fn invalid_record(path: impl Into<PathBuf>, message: impl Into<String>) -> FolderbaseError {
3731    FolderbaseError::InvalidRecord {
3732        path: path.into(),
3733        message: message.into(),
3734    }
3735}
3736
3737#[cfg(test)]
3738mod tests {
3739    use std::{
3740        fs::OpenOptions,
3741        panic::{AssertUnwindSafe, catch_unwind},
3742    };
3743
3744    use tempfile::TempDir;
3745
3746    use super::*;
3747    use crate::{
3748        FolderbaseKind, InitializationOptions,
3749        initialization::{initialize, plan_initialization},
3750    };
3751
3752    #[test]
3753    fn generic_versioned_replace_refuses_the_exact_root_ignore_policy_before_writes() {
3754        for policy_path in [".folderbaseignore", ".FOLDERBASEIGNORE"] {
3755            let fixture = tempfile::tempdir().expect("temporary version store");
3756            fs::write(fixture.path().join(policy_path), b"node_modules/\n").expect("ignore policy");
3757            let store = LocalVersionStore::open(fixture.path()).expect("version store");
3758            let expected = ContentDigest {
3759                algorithm: "sha256".to_owned(),
3760                digest: "4d56952b0fb13bf8f9b6c13a6d4c34a075bac3af447636a1df4335d7576e2f97"
3761                    .to_owned(),
3762                bytes: 14,
3763            };
3764
3765            let error = store
3766                .replace_file_versioned(policy_path, &expected, b"target/\n")
3767                .expect_err("generic local-version replacement cannot change capture policy");
3768
3769            assert!(matches!(
3770                error,
3771                FolderbaseError::UnsafePath(path) if path == Path::new(policy_path)
3772            ));
3773            assert_eq!(
3774                fs::read(fixture.path().join(policy_path)).unwrap(),
3775                b"node_modules/\n"
3776            );
3777            assert!(
3778                !fixture.path().join(".folderbase").exists(),
3779                "policy refusal must precede lazy version-state creation"
3780            );
3781        }
3782    }
3783
3784    #[test]
3785    fn transaction_lock_is_exclusive_across_independent_handles() {
3786        let fixture = tempfile::tempdir().expect("temporary lock store");
3787        fs::create_dir_all(fixture.path().join(LOCKS_DIRECTORY)).expect("lock directory");
3788        let path = fixture.path().join(TRANSACTION_LOCK_PATH);
3789        let first = OpenOptions::new()
3790            .read(true)
3791            .write(true)
3792            .create(true)
3793            .truncate(false)
3794            .open(&path)
3795            .expect("first handle");
3796        let second = OpenOptions::new()
3797            .read(true)
3798            .write(true)
3799            .open(&path)
3800            .expect("second handle");
3801        File::lock(&first).expect("first exclusive lock");
3802        assert!(matches!(
3803            File::try_lock(&second).expect_err("second handle must contend"),
3804            std::fs::TryLockError::WouldBlock
3805        ));
3806        File::unlock(&first).expect("unlock");
3807        File::lock(&second).expect("second handle acquires after release");
3808        File::unlock(&second).expect("final unlock");
3809    }
3810
3811    #[test]
3812    fn every_history_transfer_checkpoint_reopens_and_recovers() {
3813        for fault in [
3814            HistoryTransferCheckpoint::Applying,
3815            HistoryTransferCheckpoint::DestinationStaged,
3816            HistoryTransferCheckpoint::DestinationVerified,
3817            HistoryTransferCheckpoint::SourceReceiptWritten,
3818            HistoryTransferCheckpoint::SourceReleased,
3819            HistoryTransferCheckpoint::IncomingReceiptWritten,
3820            HistoryTransferCheckpoint::DestinationActivated,
3821            HistoryTransferCheckpoint::Verified,
3822        ] {
3823            let (fixture, parent_store, child_store, parent_id, child_id, object_id) =
3824                history_transfer_fixture();
3825            let plan = parent_store
3826                .propose_history_transfer(
3827                    &child_store,
3828                    &parent_id,
3829                    &child_id,
3830                    &object_id,
3831                    "private.txt",
3832                )
3833                .unwrap();
3834            let transfer_id = plan.id().to_owned();
3835            let approved = approve_history_transfer(plan).unwrap();
3836
3837            let interrupted = catch_unwind(AssertUnwindSafe(|| {
3838                apply_history_transfer_with_hook(approved, |checkpoint| {
3839                    if checkpoint == fault {
3840                        panic!("simulated process termination");
3841                    }
3842                })
3843            }));
3844            assert!(interrupted.is_err());
3845            if fault == HistoryTransferCheckpoint::IncomingReceiptWritten {
3846                assert!(incoming_history_transfer_path(child_store.root(), &object_id).exists());
3847                assert!(child_store.read_object(&object_id).is_err());
3848            }
3849
3850            let recovered = HistoryTransferResult::recover(fixture.path(), &transfer_id).unwrap();
3851            assert_eq!(recovered.state, HistoryTransferState::Verified);
3852            assert_eq!(recovered.object_id, object_id);
3853            assert_eq!(
3854                child_store.read_object(&object_id).unwrap().path,
3855                "private.txt"
3856            );
3857            assert!(parent_store.read_object(&object_id).is_err());
3858            assert_eq!(
3859                HistoryTransferResult::recover(fixture.path(), &transfer_id)
3860                    .unwrap()
3861                    .state,
3862                HistoryTransferState::Verified
3863            );
3864            assert!(!history_transfer_staging_root(child_store.root(), &transfer_id).exists());
3865        }
3866    }
3867
3868    #[test]
3869    fn source_released_recovery_preserves_workspace_and_manifest_changes() {
3870        let (fixture, parent_store, child_store, parent_id, child_id, object_id) =
3871            history_transfer_fixture();
3872        let plan = parent_store
3873            .propose_history_transfer(
3874                &child_store,
3875                &parent_id,
3876                &child_id,
3877                &object_id,
3878                "private.txt",
3879            )
3880            .unwrap();
3881        let transfer_id = plan.id().to_owned();
3882        let approved = approve_history_transfer(plan).unwrap();
3883        let interrupted = catch_unwind(AssertUnwindSafe(|| {
3884            apply_history_transfer_with_hook(approved, |checkpoint| {
3885                if checkpoint == HistoryTransferCheckpoint::SourceReleased {
3886                    panic!("simulated process termination");
3887                }
3888            })
3889        }));
3890        assert!(interrupted.is_err());
3891
3892        fs::write(
3893            fixture.path().join("Client/private.txt"),
3894            "user edit after source release\n",
3895        )
3896        .unwrap();
3897        for manifest in [
3898            fixture.path().join(".folderbase/manifest.json"),
3899            fixture.path().join("Client/.folderbase/manifest.json"),
3900        ] {
3901            let mut bytes = fs::read(&manifest).unwrap();
3902            bytes.push(b'\n');
3903            fs::write(manifest, bytes).unwrap();
3904        }
3905
3906        let recovered = HistoryTransferResult::recover(fixture.path(), &transfer_id).unwrap();
3907
3908        assert_eq!(recovered.state, HistoryTransferState::Verified);
3909        assert_eq!(
3910            fs::read(fixture.path().join("Client/private.txt")).unwrap(),
3911            b"user edit after source release\n"
3912        );
3913        assert_eq!(child_store.read_object(&object_id).unwrap().id, object_id);
3914        assert!(parent_store.read_object(&object_id).is_err());
3915    }
3916
3917    #[test]
3918    fn source_released_destination_capture_enters_durable_conflict() {
3919        let (fixture, parent_store, child_store, parent_id, child_id, object_id) =
3920            history_transfer_fixture();
3921        let plan = parent_store
3922            .propose_history_transfer(
3923                &child_store,
3924                &parent_id,
3925                &child_id,
3926                &object_id,
3927                "private.txt",
3928            )
3929            .unwrap();
3930        let transfer_id = plan.id().to_owned();
3931        let approved = approve_history_transfer(plan).unwrap();
3932        let interrupted = catch_unwind(AssertUnwindSafe(|| {
3933            apply_history_transfer_with_hook(approved, |checkpoint| {
3934                if checkpoint == HistoryTransferCheckpoint::SourceReleased {
3935                    panic!("simulated process termination");
3936                }
3937            })
3938        }));
3939        assert!(interrupted.is_err());
3940
3941        fs::write(
3942            fixture.path().join("Client/private.txt"),
3943            "captured child edit\n",
3944        )
3945        .unwrap();
3946        let child_capture = child_store.capture_file("private.txt").unwrap();
3947        let error = HistoryTransferResult::recover(fixture.path(), &transfer_id).unwrap_err();
3948
3949        assert!(matches!(error, FolderbaseError::WouldOverwrite(_)));
3950        assert_eq!(
3951            HistoryTransferPlan::reopen(fixture.path(), &transfer_id)
3952                .unwrap()
3953                .state,
3954            HistoryTransferState::Conflicted
3955        );
3956        assert_eq!(
3957            child_store
3958                .read_object(&child_capture.object.id)
3959                .unwrap()
3960                .id,
3961            child_capture.object.id
3962        );
3963        assert_eq!(
3964            fs::read(fixture.path().join("Client/private.txt")).unwrap(),
3965            b"captured child edit\n"
3966        );
3967    }
3968
3969    #[test]
3970    fn source_released_staging_tamper_enters_durable_conflict() {
3971        let (fixture, parent_store, child_store, parent_id, child_id, object_id) =
3972            history_transfer_fixture();
3973        let plan = parent_store
3974            .propose_history_transfer(
3975                &child_store,
3976                &parent_id,
3977                &child_id,
3978                &object_id,
3979                "private.txt",
3980            )
3981            .unwrap();
3982        let transfer_id = plan.id().to_owned();
3983        let approved = approve_history_transfer(plan).unwrap();
3984        let interrupted = catch_unwind(AssertUnwindSafe(|| {
3985            apply_history_transfer_with_hook(approved, |checkpoint| {
3986                if checkpoint == HistoryTransferCheckpoint::SourceReleased {
3987                    panic!("simulated process termination");
3988                }
3989            })
3990        }));
3991        assert!(interrupted.is_err());
3992
3993        let staged_object = history_transfer_staging_root(child_store.root(), &transfer_id)
3994            .join("objects")
3995            .join(format!("{object_id}.json"));
3996        fs::write(staged_object, b"{}\n").unwrap();
3997
3998        assert!(HistoryTransferResult::recover(fixture.path(), &transfer_id).is_err());
3999        assert_eq!(
4000            HistoryTransferPlan::reopen(fixture.path(), &transfer_id)
4001                .unwrap()
4002                .state,
4003            HistoryTransferState::Conflicted
4004        );
4005        assert!(parent_store.read_object(&object_id).is_err());
4006        assert!(child_store.read_object(&object_id).is_err());
4007    }
4008
4009    #[test]
4010    fn verified_recovery_reports_staging_cleanup_failure_and_retries() {
4011        let (fixture, parent_store, child_store, parent_id, child_id, object_id) =
4012            history_transfer_fixture();
4013        let plan = parent_store
4014            .propose_history_transfer(
4015                &child_store,
4016                &parent_id,
4017                &child_id,
4018                &object_id,
4019                "private.txt",
4020            )
4021            .unwrap();
4022        let transfer_id = plan.id().to_owned();
4023        apply_history_transfer(approve_history_transfer(plan).unwrap()).unwrap();
4024        let staging = history_transfer_staging_root(child_store.root(), &transfer_id);
4025        fs::write(&staging, b"not a removable staging directory").unwrap();
4026
4027        let cleanup_error =
4028            HistoryTransferResult::recover(fixture.path(), &transfer_id).unwrap_err();
4029
4030        assert!(matches!(cleanup_error, FolderbaseError::Io { .. }));
4031        assert!(staging.is_file());
4032        assert_eq!(
4033            HistoryTransferPlan::reopen(fixture.path(), &transfer_id)
4034                .unwrap()
4035                .state,
4036            HistoryTransferState::Verified
4037        );
4038        fs::remove_file(&staging).unwrap();
4039        assert_eq!(
4040            HistoryTransferResult::recover(fixture.path(), &transfer_id)
4041                .unwrap()
4042                .state,
4043            HistoryTransferState::Verified
4044        );
4045    }
4046
4047    fn history_transfer_fixture() -> (
4048        TempDir,
4049        LocalVersionStore,
4050        LocalVersionStore,
4051        String,
4052        String,
4053        ObjectId,
4054    ) {
4055        let fixture = tempfile::tempdir().unwrap();
4056        let parent = initialize(
4057            &plan_initialization(
4058                fixture.path(),
4059                InitializationOptions {
4060                    name: Some("Parent".to_owned()),
4061                    kind: FolderbaseKind::Organization,
4062                    create_agent_adapters: false,
4063                },
4064            )
4065            .unwrap(),
4066        )
4067        .unwrap();
4068        fs::create_dir(fixture.path().join("Client")).unwrap();
4069        fs::write(fixture.path().join("Client/private.txt"), "history\n").unwrap();
4070        let parent_store = LocalVersionStore::open(fixture.path()).unwrap();
4071        let captured = parent_store.capture_file("Client/private.txt").unwrap();
4072
4073        let child_fixture = tempfile::tempdir().unwrap();
4074        let child = initialize(
4075            &plan_initialization(
4076                child_fixture.path(),
4077                InitializationOptions {
4078                    name: Some("Child".to_owned()),
4079                    kind: FolderbaseKind::Project,
4080                    create_agent_adapters: false,
4081                },
4082            )
4083            .unwrap(),
4084        )
4085        .unwrap();
4086        fs::create_dir_all(fixture.path().join("Client/.folderbase")).unwrap();
4087        fs::copy(
4088            child_fixture.path().join(".folderbase/manifest.json"),
4089            fixture.path().join("Client/.folderbase/manifest.json"),
4090        )
4091        .unwrap();
4092        let child_store = LocalVersionStore::open(fixture.path().join("Client")).unwrap();
4093        (
4094            fixture,
4095            parent_store,
4096            child_store,
4097            parent.folderbase_id,
4098            child.folderbase_id,
4099            captured.object.id,
4100        )
4101    }
4102}