Module vcs 

Backend-agnostic VCS provenance types and trailer-block helpers.

The engine’s git-bound bits — the Vcs trait, gix-using repository helpers, VcsError and its From<gix::*> conversions — live in memstead_git_branch::vcs. What stays here is the data model that travels through every commit (caller actor, client identity, optional tool name and provenance note) and the deterministic helpers that turn that data into the author signature and trailer block. Both adapters (legacy disk + git-tree) call the helpers so two paths produce byte-identical commit messages for the same logical input.

Structs

ClientId

Identity of the process speaking to the engine. For MCP, this is the clientInfo from the initialize handshake (e.g. ClientId { name: "claude-code", version: "2.1.0" }). For CLI-direct mutations, the crate populates it with its own name and version.

CommitContext

Provenance bundle for a single commit. Produced at the caller boundary (memstead-mcp tool handler, memstead-cli subcommand, engine-internal drift flush) and threaded through to the VCS commit path.

Enums

Actor

Caller categories for the Actor: trailer and for picking an author signature. Agent, Cli, and App get their author from the paired ClientId when one is present; External always uses the synthetic external <external@memstead.io> identity (no client is known); Unknown falls back to the committer identity.

Role

The caller-declared ROLE a mutation was performed in (agent-trust plan 13) — a closed vocabulary recorded immutably alongside every mutation (commit trailer / ledger field). Caller-declared but tamper-evident: bound to specific operations in append-only history, so it cannot be edited after the fact and identities can be cross-checked across operations — which no self-written metadata field can provide. Unspecified is legal forever: old clients, casual sessions, and humans at the CLI are never refused for not declaring; absence is recorded as absence (no trailer), and downstream gates treat it as “cannot confirm”, never as any specific role.

Functions

author_identity

Build the per-commit author (name, email) pair from the context. None means “fall back to the committer identity” — adapters then reuse the committer signature for the author slot.

format_commit_message

Append the trailer block to the caller’s prose, separated by exactly one blank line. Normalises trailing newlines so "subject" and "subject\n" both produce "subject\n\nActor: …\n…".

parse_client_id

Inverse of the name@version rendering used in both the commit trailer block (Client: <name>@<version>) and the folder-backend JSONL changelog ("client": "<name>@<version>"). Splits on the last @ because client names may legitimately contain . and -; versions never contain @. Returns None for malformed input (no @, empty name, empty version) so tolerant readers drop the field rather than constructing a half-record.

sanitise_client_name

Sanitise a raw client name to a git-safe local-part matching [a-z0-9._-]+. Empty/whitespace-only input falls back to "unknown".