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