Module ops

Expand description

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

Module ops

Module ops Copy item path

Re-exports§

Modules§

Structs§

Enums§

Constants§

Functions§

Module ops