Module ops 

Operation request/response types and the gix-free read paths (health, search).

Per-entity delta envelopes for memstead_changes_since live in changes — backend-neutral so both the git-branch tree-diff and any future folder-backend JSONL-walk produce the same shape. Wire types for the agent-notes payload live in agent_notes — pure data shapes, no gix. The producer functions (agent_notes_since, read_memstead_ref) stay in memstead-git-branch::ops::agent_notes because they read from a gitdir. The git-touching operation submodules (crud, export) still live in memstead-git-branch and are re-exported into memstead_git_branch::ops for downstream callers.

Re-exports

pub use agent_notes::AgentNotesReport;

pub use agent_notes::CommitNote;

pub use branch_reset::BranchResetOutcome;

pub use branch_reset::StrandedCrossMemRef;

pub use changes::BackendChanges;

pub use changes::ChangeEnvelope;

pub use changes::ChangesReport;

pub use changes::EMPTY_TREE_SHA;

pub use changes::MemChangedNotice;

pub use changes::NoticeByChange;

pub use changes::NoticeChanges;

pub use changes::RENAME_SIMILARITY_DEFAULT;

pub use changes::RENAME_SIMILARITY_MAX;

pub use changes::RENAME_SIMILARITY_MIN;

pub use changes::folder_changes_since;

pub use commit_envelope::CommitEnvelope;

pub use commit_envelope::EntityChange;

pub use diff::Diff;

pub use diff::DiffConfig;

pub use diff::EntityDiff;

pub use diff::IncomingRipple;

pub use export::MemExportBytes;

pub use export::MemExportError;

pub use transport::FetchOutcome;

pub use transport::PullOutcome;

pub use transport::PushOutcome;

pub use transport::RemoteAddOutcome;

pub use transport::UpdatedRef;

Modules

agent_notes

Agent-notes wire types — pure data shapes for the commit-trailer + workspace-__MEMSTEAD-ref payload that the git-branch backend produces from its gitdir.

branch_reset

Wire types for Engine::branch_reset.

changes

Backend-neutral entity-level delta surface for memstead_changes_since callers.

commit_envelope

Per-commit wire envelope and entity-change variants.

diff

Two-ref structural diff types.

export

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

Wire types for the three transport ops Engine::fetch, Engine::pull, Engine::push.

Structs

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.

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.

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.

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.

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

ListResult

List result with token totals.

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

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

Query

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

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

RenameResult

Result of a rename operation.

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.

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.

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.

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.

Enums

Direction

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

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.

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.

project_incoming

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