Struct FilesystemMemWriter 

pub struct FilesystemMemWriter { /* private fields */ }

Filesystem-backed MemWriter. Mutations buffer in memory until Self::commit; commit replays them against the directory at root with per-file write-to-temp + rename atomicity.

Implementations

impl FilesystemMemWriter

pub fn new(root: PathBuf) -> Self

Build a writer rooted at root. The directory must already exist; sub-directories are created lazily as commits run.

Trait Implementations

impl MemBackend for FilesystemMemWriter

fn current_head(&self) -> Result<Option<String>, BackendError>

Folder-mem drift cursor: the changelog’s last-line ts — the same RFC3339-millisecond dialect folder_changes_since accepts as its cursor, so drift heads feed straight into delta reads. Every mutation appends a changelog line (in this process or a sibling’s), advancing the cursor; the drift check then treats the advance exactly like a git-branch tip move. Absent changelog (a mem never mutated through the engine) keeps the historical no-drift-signal None. Appends go through append_change_monotonic, so the cursor strictly advances even for same-millisecond commits; only a read-append race between separate processes can momentarily share a cursor value — detection then rides the next append.

fn list_entities(&self) -> Result<Vec<PathBuf>, BackendError>

Mem-relative paths of every entity-bearing file the backend holds. Order is not specified; callers that need stable ordering sort.

fn read_entity(&self, rel_path: &Path) -> Result<Option<Vec<u8>>, BackendError>

Read raw bytes at rel_path. Ok(None) for a missing path (idempotent reads); Err for IO or backend-specific failures.

fn write_entity( &self, rel_path: &Path, content: &[u8], ) -> Result<(), BackendError>

Upsert content at rel_path. Pending until Self::commit.

fn delete_entity(&self, rel_path: &Path) -> Result<(), BackendError>

Remove rel_path. Idempotent: no-op when the path is already absent. Pending until Self::commit.

fn move_entity(&self, from: &Path, to: &Path) -> Result<(), BackendError>

Rename from to to. Pending until Self::commit. Errors when to already exists.

fn discard_pending(&self) -> Result<(), BackendError>

Discard every pending (uncommitted) mutation, returning the staging buffer to empty without producing a commit. The transactional escape hatch for stage-then-commit callers: the atomic batch_update stages each item’s write into the pending set, and when a later item fails validation it calls this to drop the already-staged writes rather than commit a half-applied batch. Idempotent — discarding an empty buffer is a no-op.

fn commit( &self, message: &str, ctx: &CommitContext<'_>, ) -> Result<CommitId, BackendError>

Flush pending mutations into a single commit. Returns the resulting opaque CommitId; backends without history return a synthetic id (UNIX-nanos + counter, hex) so callers always get a non-empty cursor.

fn read_mem_config(&self) -> Result<Option<Vec<u8>>, BackendError>

Read the per-mem .memstead/config.json payload, if any.

fn write_mem_config(&self, bytes: &[u8]) -> Result<(), BackendError>

Write the per-mem .memstead/config.json payload. Symmetric counterpart to Self::read_mem_config.

fn read_anchors_sidecar(&self) -> Result<Option<Vec<u8>>, BackendError>

Read the engine-owned anchors sidecar (crate::anchor::ANCHOR_SIDECAR_PATH) bytes, if any.

fn write_anchors_sidecar(&self, bytes: &[u8]) -> Result<(), BackendError>

Stage a write of the engine-owned anchors sidecar so it rides the same commit as the entity mutation that produced it — the atomicity guarantee anchors depend on (rename’s referrer-rewrite, delete’s anchor removal, and branch_reset’s rewind all move entity + anchor state together).

fn append_provenance(&self, record: &Provenance) -> Result<(), BackendError>

Append a Provenance record to the backend’s mutation log. Persistence form differs per backend — JSONL line, commit trailer, etc. — but the in-memory shape is identical.

fn read_provenance( &self, cursor: Option<&str>, ) -> Result<Vec<Provenance>, BackendError>

Read provenance entries since cursor (opaque, backend-defined: a commit SHA for git-branch, an RFC-3339 timestamp for folder, ignored for archive). None cursor means “from the beginning”.

fn commit_with_expected_parent( &self, message: &str, ctx: &CommitContext<'_>, _expected_parent: Option<&str>, ) -> Result<CommitId, BackendError>

Commit pending mutations with a parent-ref pinning guard. When expected_parent is Some, the backend MUST refuse the commit (Err(BackendError::ParentMismatch { ... })) if its current head no longer matches the supplied ref — a sibling writer advanced the on-disk state between the snapshot the caller pinned and now. When expected_parent is None, the call is equivalent to Self::commit.

fn read_archive_provenance(&self) -> Result<Option<Vec<u8>>, BackendError>

Read the optional authoring-provenance payload (.memstead/provenance.json) the archive carries, if any.

fn write_mem_config_with_note( &self, bytes: &[u8], _note: Option<&str>, ) -> Result<(), BackendError>

Like Self::write_mem_config but records note (an optional agent/operator-supplied provenance reason) on the resulting commit body. The default delegates to the note-less form, so backends without a commit (folder) simply ignore the note; the git-branch backend overrides this to thread note into the __MEMSTEAD-ref commit. Lets set_mem_version carry a --note like the other commit-producing mem-lifecycle operations.

fn record_pipeline_edit( &self, _kind: &str, _edits: &[(String, Option<Vec<u8>>)], _note: Option<&str>, _verb: &str, ) -> Result<(), BackendError>

Record provenance for a pipeline-config edit (mediums / facets / projections / ingests). The canonical pipeline config is a plain JSON file under .memstead/ on the workspace root — it has no commit of its own — so backends with a commit timeline mirror the edit into their provenance record; the commit is the audit trail, the disk file stays the read path.

fn delete_artifacts(&self) -> Result<(), BackendError>

Drop every backend-side artifact for this mem — the symmetric counterpart to the writes performed by memstead_mem_create (entity-seed commit on the per-mem branch + Self::write_mem_config on __MEMSTEAD). Called by memstead_mem_delete orchestration when delete_files=true and the delete rule matched, to give the backend a chance to prune ref-store state the engine alone has the git authority to touch.

impl MemWriter for FilesystemMemWriter

fn write_entity( &self, rel_path: &Path, content: &[u8], ) -> Result<(), MemWriterError>

Upsert content at rel_path (mem-relative). Pending until Self::commit.

fn delete_entity(&self, rel_path: &Path) -> Result<(), MemWriterError>

Remove rel_path (mem-relative). Idempotent: no-op when the path is already absent. Pending until Self::commit.

fn move_entity(&self, from: &Path, to: &Path) -> Result<(), MemWriterError>

Rename from to to (both mem-relative). Pending until Self::commit. Errors if to already exists.

fn commit( &self, _message: &str, _ctx: &CommitContext<'_>, ) -> Result<CommitId, MemWriterError>

Flush pending mutations into a single commit. The implementation picks up the actor / committer / trailer information from ctx. Returns the resulting CommitId (opaque; the git-tree adapter formats it as a hex object id).