Module ops 

Re-export shim over memstead_base::ops (request/response types, WarningHint, plus the gix-free health and search submodules) plus the git-touching operation submodules that stay in this crate.

Modules

agent_notes

agent_notes_since — walk a mem’s branch from a caller-provided cursor to the current tip and return one CommitNote per commit along the way, with the body parsed into structured fields.

branch_reset

Engine::branch_reset implementation for git-branch mounts.

changes

memstead_changes_since — two-tree diff between a caller-provided commit SHA and the mem’s current HEAD, with rename detection tunable via rename_similarity (default 60%).

commit_envelope

Per-commit wire envelope and entity-change variants.

diff

Engine::diff(ref_a, ref_b) implementation for git-branch mounts.

export

Markdown and mem-archive export.

health

Health checks — missing required fields, staleness, scoring.

integrity

Integrity linter — read-time conformance findings.

search

Full-text search across entities with BM25 scoring via tantivy.

transport

memstead_fetch / memstead_pull / memstead_push implementations.

Structs

AgentNotesReport

Walked output of agent_notes_since. head echoes the resolved branch tip so callers record it as the next polling cursor without a follow-up memstead_health round-trip. memstead_ref carries the workspace-level __MEMSTEAD ref tip (unified schemas + per-mem configs) so commit-mirroring consumers — e.g. an outer-repo cursor block — anchor it alongside the per-mem head without a second round-trip. None when the workspace has not been migrated to the unified layout yet.

BackendChanges

Backend-neutral “what changed” report. The engine wrapper (crate::Engine::changes_since, landing in a follow-up session) adds rename-similarity clamping warnings, optional agent-notes piggyback (git-branch only), and the operator-facing mem: String field on top.

BatchEntry

BatchError

Per-item error envelope on a batch result. The shape matches the MCP wire envelope for single-entry failures: code is the stable UPPER_SNAKE_CASE token from crate::EngineError::code(); details carries the variant-specific recovery payload (e.g. declared list, allowed enum values, hash-mismatch current) when available, or an empty object for variants without a structured payload.

BatchResult

Result of an atomic batch update — all-or-nothing.

BranchResetOutcome

Successful outcome of Engine::branch_reset. Carries enough context for callers (CLI, replay skills, audit UIs) to surface what happened without a follow-up memstead_changes_since poll.

ChangesReport

Engine-wrapper-level “what changed” shape returned by crate::Engine::changes_since.

CommitEnvelope

One commit’s wire envelope. JSON example from the spec:

CommitNote

One commit’s worth of structured agent-note state. Fields are populated best-effort: a body that doesn’t match the memstead: <verb> <id> subject shape leaves tool_verb / entity_id None; absent trailers leave the corresponding fields None. Callers branch on actor for agent-vs-external classification.

ContextResult

Context around an entity — neighbors, community, related entities.

CreateArgs

Arguments for creating an entity.

CreateResult

Result of a create operation.

DanglingLink

One dangling wiki-link finding surfaced by memstead_health include=["dangling_links"]. A link is dangling when its resolved target is a stub (i.e. the markdown file does not exist on disk). This is the post-delete / renamed-without-rewrite / typo signal.

DeleteResult

Result of a delete operation.

Diff

Top-level diff response. Echoes the two refs the caller passed in (verbatim), reports the SHAs they resolved to, surfaces the configuration the operation used, and lists every per-entity entry.

DiffConfig

Caller-supplied diff configuration. Defaults yield a useful diff without requiring callers to opt in to every feature.

ExpansionInfo

Metadata attached to hits reached via graph expansion. The primary hit that seeded the expansion is identified by of; via_edge is the exact rel_type string; depth counts hops from the seed.

ExportResult

Export result.

Facets

Fixed set of facet dimensions computed over the unpaginated hit set. Tier 1 freezes the dimensions; extend later only if empirical use demands it. Zero-count entries are excluded to keep the payload small.

FetchOutcome

Outcome of Engine::fetch. Updates remote-tracking refs without moving the local branch pointer.

FoldedTag

Case-drift audit entry. Surfaces when two or more casings of the same canonical (lowercased) tag appear in the authored graph — the agent-hostile bug where decision and Decision look like two healthy low-count tags in the case-sensitive primary surface.

FullRefreshReport

What Engine::full_refresh changed — and, just as deliberately, what it SKIPPED. The refresh is additive-only: removals never take effect warm, and this report is how the caller learns whether its next call will succeed instead of guessing.

HealthIssue

HealthReport

Health check result for one entity.

HealthSummary

Aggregated health report for the whole graph.

IncomingRef

Serialisable projection of store::InEdge for CreateResult.incoming. source is the lowercase EdgeSource variant: "explicit" | "hierarchy" | "body_link".

IncomingRipple

One entry in an entity’s incoming-wikilink ripple list. The referrer entity is on either ref_a or ref_b (side discriminates); consumers building a “what would break” preview consult both sides.

ListResult

List result with token totals.

MemChangedNotice

Non-blocking “the mem moved under you” notice, attached to a response only when a reload happened during the operation. The operation’s own result/error rides alongside — this is purely the objective “what else changed” delta, scaled by size, for the agent to judge relevance against (the engine does not filter to a per-agent interest model).

MemExportBytes

Byte-shaped output of export_mem_to_bytes. Bundles the produced archive bytes with the same metadata MemExportResult reports for path-based exports.

MemExportResult

Result of a .mem mem-archive export.

MissingRequiredOutgoingBlock

Wire-shape entry inside MissingRequiredOutgoing.missing. Lists the relationship-name alternatives and the rendered cardinality literal for one unsatisfied RequiredOutgoing block. Custom struct so the JSON output is { "relationships": [...], "cardinality": "at_least_one" } — identical to the schema YAML shape, so an agent can copy the envelope’s details.missing entry directly into a memstead_relate plan without renaming fields.

ModifiedMetadata

Metadata-level mutations applied by a single memstead_update call. Same empty-vec-omit convention as ModifiedSections; auto-timestamp metadata fields written by the engine are NOT surfaced here (they are engine-driven, not user-driven — the caller has nothing to react to).

ModifiedSections

Section-level mutations applied by a single memstead_update call. Each vec lists the section keys that landed in that mutation mode. Empty inner vecs are serde-omitted so the wire stays quiet; the struct itself always serialises so the outer modified_sections key is a stable shape regardless of what the call actually touched.

NeighborInfo

NoticeByChange

Per-change-kind counts in mode: "counts". Field names track the memstead_changes_since action vocabulary (updated, not modified) so the notice and the recovery surface speak one language.

ParseRecoveryEntry

Per-entry result of an apply_parse_recovery call. One entry per PARSED_RELATION_INVALID warning the engine observed at the call site: the bulk-fix dispatches the writable-origin recoveries and reports the read-only-origin warnings as skipped. Wire-equivalent across MCP, CLI, and UniFFI surfaces; the renderer chooses the shape it prefers.

ParseRecoveryReport

Outcome of Engine::apply_parse_recovery. Carries one ParseRecoveryEntry per parse-time-dropped relation observed at the call site plus the last successful commit sha for callers that want to poll memstead_changes_since for the per-entity diff. An empty entries list means the workspace was already clean.

ParsedRelationRecovery

Abstract recovery action attached to a PARSED_RELATION_INVALID warning when the source mem is writable. The shape is tool- agnostic: it names what to do, not which tool to call. A consumer (agent, bulk-fix orchestrator, app surface) maps kind to the concrete call on whichever MCP / CLI / UniFFI path it uses; the warning’s payload itself does not drift when the mutation surface evolves.

PatchArg

Arguments for a patch (substring replacement).

PullOutcome

Outcome of Engine::pull. Fast-forwards the local branch when possible; refuses with LOCAL_DIVERGENCE on a diverged local branch.

PushOutcome

Outcome of Engine::push. The remote’s view of the mem’s branch has moved to new_sha after the operation.

QuarantinedMemReport

One quarantine-roster entry on HealthSummary: the mem, the typed reason code, and the full reason message (repair command included — plan-01 material).

Query

Flat query shape for full-text search. Four optional fields, all combined with implicit AND across fields.

RefreshFailure

One failed refresh item — item is schema-source:<which>, mount:<mem>, mount-manifest, or workspace.

RelateArg

Arguments for a relate/unrelate operation.

RelateResult

Result of a relate operation.

RelationUnsetArg

One repair-shaped relation removal on memstead_update — relations_unset: [{ rel_type, target }]. Symmetric with metadata_unset: an absent (rel_type, target) pair is a silent no-op. Only accepted when the target entity currently fails the conformance check (REPAIR_NOT_NEEDED otherwise) — the everyday detach path stays memstead_relate(remove).

ReloadReport

Per-mem reload outcome — produced by [Engine::reload_one_mem] and surfaced verbatim in the memstead_reload MCP tool’s response when an explicit operator-triggered reload runs against a single mem. Auto-reloads on the read path consume this internally and emit a WarningHint::MemReloaded (which carries mem, old_head, new_head, entities_loaded — the diff list is intentionally omitted from the lean warning payload; agents that need it call memstead_changes_since themselves with the supplied old_head).

ReloadResult

RemoteAddOutcome

Outcome of Engine::remote_add. Configures a named remote on the workspace’s mem-repo so fetch / pull / push have somewhere to go — upsert semantics (re-pointing an existing remote is not an error; updated says which happened).

RenameResult

Result of a rename operation.

SchemaHeadingViolation

Wire-shape entry inside SchemaHeadingRoundtripViolation.violations — one section whose declared heading does not derive back to its declared key. Mirrors memstead_schema::HeadingKeyViolation, kept as a local struct so the warning’s JSON shape is owned here.

ScoreBreakdown

Per-hit score components surfaced so agents can understand ranking.

SearchHit

A search result hit.

SearchResult

Search result with metadata.

SearchScope

Scope filters for search and list operations.

SetMemDescriptionOutcome

Result of Engine::set_mem_description. Carries the (mem, old_description, new_description) triple so callers can surface the change without an extra read.

SetMemSubjectOutcome

Result of Engine::set_mem_subject. The block sets/clears as a unit; old/new carry the whole block.

SetMemSyncStateOutcome

Result of Engine::set_mem_sync_state. Carries the (mem, key, previous-token) triple so callers (CLI, MCP) can surface the change without an extra read. The token values are opaque to the engine — see MemConfig::sync_state.

SetMemTitleOutcome

Result of Engine::set_mem_title. Same shape discipline as SetMemDescriptionOutcome.

SetMemVersionOutcome

Result of Engine::set_mem_version. Carries the (mem, old_version, new_version) triple so callers (CLI, MCP) can surface the change without an extra read.

SkippedMount

One mount declined by export_markdown because the active backend doesn’t support in-place markdown regeneration.

StaleEntity

Status

Graph status — node / edge counts and schema distribution. Renamed from the former Stats when the stats command became status (bundle plan 03-projection-promotion, D11); the fields are unchanged so every caller’s payload stays byte-compatible.

StrandedCrossMemRef

One inbound cross-mem reference that a branch reset would strand: an edge from an entity in another mem pointing at an entity that exists at the current head but would not exist at the reset target (it was created — or renamed to its current id — after the target commit). Computed engine-side by Engine::branch_reset_stranded_refs; the human surface warns with these before confirming a reset.

SubsectionFacet

One sub-section-level facet entry. path is ordered outermost → innermost, prefixed with the H2 section key (e.g. ["specifies", "Response Shapes", "Markdown Output"]). Structured vector (not a delimiter-joined string) so headings containing punctuation don’t break the key.

SummaryPair

Lead-section (heading, value) for a search/list hit, resolved against the hit’s own mem schema at search time. Carried in-memory from the search op to the renderers; see SearchHit::summary.

TagDistribution

One entry in the tag distribution surface: an authored tag string, the number of non-stub entities carrying it, and the per-entity-type breakdown of those hits. Comparison is case-sensitive — decision and Decision count as distinct entries here (see tag_distribution_folded for the drift-aware sidecar).

TagVariant

TermMatch

One snippet-level match recorded per (term, field). heading_path is Some when the match falls under an H3–H6 sub-heading; elements are ordered outermost → innermost.

UntaggedStats

Aggregate count of non-stub entities with zero effective tags, broken down by entity_type. “Untagged” collapses three states: missing tags metadata, empty string value, and comma-only value (e.g. ",").

UpdateArgs

Arguments for updating an entity.

UpdateResult

Result of an update operation.

UpdatedRef

One ref’s transition recorded by a successful fetch / pull.

Enums

ChangeEnvelope

Single delta entry between two snapshots. Renamed collapses what would otherwise appear as a Removed + Added pair so agents see one semantic event per filesystem rename.

Direction

EntityChange

One entity-level change carried by a CommitEnvelope. Tagged via the op discriminator so the wire shape matches the spec’s { "op": "...", ... } envelope.

EntityDiff

Per-entity diff entry. Variants mirror the change kinds an entity-level diff can produce; InvalidEntity is the soft-failure path for entities that fail to parse on either side (consumers decide how to handle each case — memstead_diff does not refuse the whole call just because one entity is malformed).

HealthIssueCode

Machine-readable condition discriminator for a HealthIssue — the enumeration lives here, with the issue type, and is never re-derived per projection. A projection that lists issues carries the code; the code is NEVER only a message-string prefix (a projection that drops messages would silently collapse distinct conditions — the exact misdirection SECTION_HEADING_MISMATCH exists to prevent).

MemExportError

NoticeChanges

The size-graceful body of a MemChangedNotice. Internally tagged on mode so a caller decodes one stable shape and branches on the discriminator — no request-shape-dependent polymorphism.

WarningHint

Typed non-fatal issue surfaced from engine operations. Serialises as the uniform { code, message, details } envelope so a generic warning handler (log sink, UI, alerting) can read code + message without branching on variant. Display renders the agent-facing text, reachable via WarningHint::message; per-variant structured fields land under details, their shape keyed by code.

Constants

EMPTY_TREE_SHA

Canonical git empty-tree hash. Callers without a prior cursor pass this to get “every entity in the current state as added”. Both the git-branch backend (special-cased to bypass rev_parse) and any future folder-backend implementation honour the same sentinel.

OVERVIEW_INCLUDE_KEYS

Allowed include keys for memstead_overview — single source of truth shared across the lean MCP server, full MCP server, and the lean CLI’s overview command. Mirrors HEALTH_INCLUDE_KEYS for the health surface. The CLI --include flag validates against this list and surfaces UNKNOWN_INCLUDE_KEY warnings, matching the MCP tool’s behaviour.

RENAME_SIMILARITY_DEFAULT

Default content-similarity threshold for rename detection (60%). Callers override per-call via changes_since’s rename_similarity parameter; the engine wrapper accepts [0.1, 1.0] and emits a LIMIT_CLAMPED warning for out-of-range values. Higher values miss edited renames; lower values risk false-positive rename pairing.

RENAME_SIMILARITY_MAX

Upper bound for rename_similarity — 1.0 means “only paired up on a byte-identical match”; above that there is no semantic meaning.

RENAME_SIMILARITY_MIN

Lower bound for rename_similarity — anything below 0.1 produces nearly-random rewrite pairing on a modest diff.

Functions

envelope

Build the uniform { code, message, details } envelope used on both the warning wire (WarningHint’s custom Serialize) and the MCP error wire (tool_error_with_payload payloads in engine_err_with_suggestions). Agents and other decoders branch on code (UPPER_SNAKE_CASE, stable) and parse details by code when they need structured fields.

folder_changes_since

Synthesise per-entity events for a folder-backed mem by reading <mem_root>/.memstead/changes.jsonl and bucketing events by entity.

project_incoming

Project &[store::InEdge] into a sorted Vec<IncomingRef>. Ordering by (rel_type, from) ascending — deterministic output despite the underlying HashMap iteration order.