feat(state): FileSystem trait, LiveFs, StateStore<F> with read/write/append (#7)

Chunk M1-W1-E of M1 plan. Lands the I/O surface for state.toml.

Public surface:

- pub trait FileSystem with three primitives: read_string,
  write_temp_then_rename, fsync_dir. Splitting rename and dir-fsync
  lets a future MockFs simulate "crashed between rename and fsync"
  in chunk M1-W1-F.
- pub struct LiveFs — production impl backed by std::fs and
  tempfile::NamedTempFile.
- pub struct StateStore<F: FileSystem = LiveFs> with:
    fn new(path) (default LiveFs)
    fn with_fs(fs, path) (test injection)
    fn path() -> &Path
    fn read() -> Result<State, StateError>
    fn write_atomic(&State) -> Result<(), StateError>
    fn append_history(HistoryEntry)
    fn append_failure(FailureRef)
    fn record_reconciliation(ReconciliationEntry)

Atomic write per PRD §7.4: temp file in same dir + sync_all + rename
+ fsync of parent directory entry. The two-step decomposition (write
+ fsync_dir) keeps the parent fsync separately mockable.

read() rejects future schema_version with
StateError::UnsupportedSchemaVersion. Migration framework lands in
chunk M1-W1-F.

append_*() are read-modify-write_atomic — file is rewritten in full
but [managed], [adopted], and [reserved] sections retain their values
on round-trip. Byte-level surgical preservation of unknown sections
outside [reserved] is deferred (would require toml_edit; the
[reserved] BTreeMap covers the documented forward-compat namespace).

Cargo.toml: tempfile is now a real (non-dev) dependency because
LiveFs uses NamedTempFile in production.

Tests (LiveFs against tempdir):
- full_state_round_trip
- unknown_fields_preserved_in_reserved
- read_missing_file_yields_not_found
- read_unsupported_schema_version
- write_fails_when_parent_missing
- history_append_does_not_rewrite_managed (asserts managed/adopted/
  reserved unchanged in value, history grows)
- append_failure_grows_failures_array
- record_reconciliation_appends_entry

What's NOT in this chunk:
- Migration framework (chunk M1-W1-F).
- MockFs feature-gate + crash-during-write tests (chunk M1-W1-F).
- Property tests via proptest (chunk M1-W1-F).
- contract: state_host_mismatch_detected (engine-side concern; the
  StateError variant is defined but not raised here — the engine
  compares state.host to hostname() at preflight).

Verification:
- cargo test -p pearlite-state  (8 passed; 0 failed)
- cargo clippy --workspace --all-targets -- -D warnings  (zero warnings)
- cargo fmt --all --check
- scripts/ci/check-spdx.sh
- pearlite-audit check .  (1 check, 0 violations)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: UnbreakableMJ

crates/pearlite-state/Cargo.toml

@@ -18,5 +18,7 @@ time = { workspace = true }
 uuid = { workspace = true }
 thiserror = { workspace = true }
 schemars = { workspace = true }
-# toml_edit lands in chunk M1-W1-E with the atomic-write implementation
-# that needs it for unknown-field preservation.
+tempfile = { workspace = true }
+
+[dev-dependencies]
+tempfile = { workspace = true }

crates/pearlite-state/src/io.rs

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Mohamed Hammad
+
+//! Filesystem trait + production [`LiveFs`] implementation for atomic
+//! `state.toml` writes per PRD §7.4.
+
+use std::fs::File;
+use std::io::Write as _;
+use std::path::Path;
+use tempfile::NamedTempFile;
+
+/// Filesystem operations the [`StateStore`](crate::StateStore) needs.
+///
+/// Three primitives is enough: reading the file, writing through
+/// temp-and-rename, and flushing the parent directory entry. Splitting
+/// the rename and the dir-fsync into separate calls is what lets a mock
+/// simulate the "crashed between rename and fsync" failure mode in
+/// chunk M1-W1-F.
+pub trait FileSystem: Send + Sync {
+    /// Read a UTF-8 file into a string.
+    ///
+    /// # Errors
+    /// Returns the underlying I/O error verbatim; callers translate it
+    /// into [`StateError::Io`](crate::StateError::Io).
+    fn read_string(&self, p: &Path) -> std::io::Result<String>;
+
+    /// Write `data` to a sibling temp file, fsync it, then atomically
+    /// rename to `p`.
+    ///
+    /// The temp file lives in `p`'s parent directory so the rename is
+    /// guaranteed-atomic on btrfs (PRD §7.4).
+    ///
+    /// # Errors
+    /// Returns the underlying I/O error verbatim.
+    fn write_temp_then_rename(&self, p: &Path, data: &[u8]) -> std::io::Result<()>;
+
+    /// `fsync(2)` on the directory entry that holds `p`.
+    ///
+    /// Without the directory fsync the rename can be reordered relative
+    /// to subsequent activity on btrfs, breaking the "old version or new
+    /// version, never partial" invariant.
+    ///
+    /// # Errors
+    /// Returns the underlying I/O error verbatim.
+    fn fsync_dir(&self, p: &Path) -> std::io::Result<()>;
+}
+
+/// Production [`FileSystem`] implementation backed by `std::fs` and
+/// [`tempfile::NamedTempFile`].
+#[derive(Clone, Copy, Debug, Default)]
+pub struct LiveFs;
+
+impl FileSystem for LiveFs {
+    fn read_string(&self, p: &Path) -> std::io::Result<String> {
+        std::fs::read_to_string(p)
+    }
+
+    fn write_temp_then_rename(&self, p: &Path, data: &[u8]) -> std::io::Result<()> {
+        let parent = p.parent().ok_or_else(|| {
+            std::io::Error::new(
+                std::io::ErrorKind::InvalidInput,
+                "atomic write target has no parent directory",
+            )
+        })?;
+        let mut tmp = NamedTempFile::new_in(parent)?;
+        tmp.as_file_mut().write_all(data)?;
+        tmp.as_file_mut().sync_all()?;
+        tmp.persist(p).map_err(std::io::Error::from)?;
+        Ok(())
+    }
+
+    fn fsync_dir(&self, p: &Path) -> std::io::Result<()> {
+        let parent = p.parent().ok_or_else(|| {
+            std::io::Error::new(
+                std::io::ErrorKind::InvalidInput,
+                "fsync_dir target has no parent directory",
+            )
+        })?;
+        let dir = File::open(parent)?;
+        dir.sync_all()?;
+        Ok(())
+    }
+}

crates/pearlite-state/src/lib.rs

@@ -11,14 +11,18 @@
 mod errors;
 mod failure;
 mod history;
+mod io;
 mod reconciliation;
 mod schema;
+mod store;
 
 pub use errors::StateError;
 pub use failure::FailureRef;
 pub use history::{HistoryEntry, SnapshotRef};
+pub use io::{FileSystem, LiveFs};
 pub use reconciliation::{ReconciliationAction, ReconciliationEntry};
 pub use schema::{
     Adopted, ConfigFileRecord, KernelRecord, Managed, SCHEMA_VERSION, ServicesState, State,
     UserEnvRecord,
 };
+pub use store::StateStore;