Struct GitTreeMemWriter 

pub struct GitTreeMemWriter { /* private fields */ }

Git-tree-backed implementation of MemWriter. Holds the gitdir path and target ref name; opens the gix::Repository per call (matches the [crate::vcs::GixVcs] pattern, since gix::Repository is Send but not Sync — its object-database cache uses interior mutability via RefCell).

Mutations buffer in memory until Self::commit.

Implementations

impl GitTreeMemWriter

pub fn new(gitdir: PathBuf, ref_name: String) -> Self

Build a writer against the repository at gitdir targeting ref_name. The ref need not exist yet — the first commit creates it. ref_name is the per-branch mutex key; pass the fully-qualified form (e.g. refs/heads/main) so writers targeting the same branch under one gitdir share the same key.

Trait Implementations

impl MemBackend for GitTreeMemWriter

fn storage_present(&self) -> Result<bool, BackendError>

The per-mem branch ref exists. list_entities folds a missing branch into an empty list (a fresh mem has no commits yet), so this is the only way boot can tell “never created” from “empty” and say missing_ref instead of empty.

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

Existence probe with read_entity’s exact source-selection semantics (pending buffer first, snapshotted parent mid-transaction, live tip between transactions) — but stopping at the tree entry, never reading the blob.

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 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 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 current_head(&self) -> Result<Option<String>, BackendError>

Opaque cursor pointing at the backend’s current state. The engine compares against a per-mount cached cursor to detect drift — a sibling writer (another Engine instance, an out-of-band git pull, etc.) advancing the on-disk state past what the engine last read. Backends without history (folder, archive) inherit the default impl returning Ok(None); the engine treats None as “no drift signal available” and skips drift detection for that mount. The git-branch backend overrides to return the per-mem branch tip’s commit SHA hex; the filesystem backend overrides to return the changelog’s last-line timestamp cursor (folder mems with no changelog yet keep None). Archive and in-memory backends stay on the default.

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

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

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 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.

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 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 read_archive_provenance(&self) -> Result<Option<Vec<u8>>, BackendError>

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

impl MemWriter for GitTreeMemWriter

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).