Module engine 

Unified engine.

One Engine type, three storage backends: the engine sits above MemBackend and routes reads / writes to the backend named by each mount’s mem. The MCP filesystem-mem server (memstead_mcp::filesystem_server::FilesystemMcpServer), every CLI lean subcommand, and the macOS UniFFI consumer all reach the engine through Engine::from_workspace_root (lean: folder + archive backends) or memstead_git_branch::engine_from_workspace_root (full: adds git-branch).

Routing

Each mount holds one mem. Lookup is by mem name: the first mount whose mem field equals the requested name wins. One mount per mem is enforced — duplicates are a configuration bug, not a feature, and the constructor rejects them.

Re-exports

pub use archive::FromArchiveBytesError;

pub use error::BootError;

pub use error::EngineError;

pub use error::INLINE_LIST_CAP;

pub use error::MissingWikiLink;

pub use error::ReferrerInfo;

pub use error::SchemaSourceDiagnostic;

pub use error::format_inline_list_overflow;

pub use events::DEFAULT_BROADCAST_CAPACITY;

pub use events::EventCallback;

pub use events::MemChangedEvent;

pub use events::SubscriptionHandle;

pub use file_watcher::FileWatcherError;

pub use file_watcher::MemRepoWatcher;

pub use file_watcher::watch_mem_repo;

pub use history::EntityHistoryReport;

pub use history::EntityTouch;

pub use history::HISTORY_PAGE_DEFAULT;

pub use history::HISTORY_PAGE_MAX;

pub use history::StoryStart;

pub use mutation::delete::DeleteReferrers;

pub use mutation::PATCH_OLD_NOT_FOUND_CONTENT_CAP;

pub use mutation::RELATIONSHIP_CYCLE_PATH_CAP;

pub use outcomes::CreateEntityArgs;

pub use outcomes::CreateEntityOutcome;

pub use outcomes::DeleteEntityArgs;

pub use outcomes::DeleteEntityOutcome;

pub use outcomes::RelateAction;

pub use outcomes::RelateEntityArgs;

pub use outcomes::RelateEntityOutcome;

pub use outcomes::RenameEntityArgs;

pub use outcomes::RenameEntityOutcome;

pub use outcomes::SetSchemaOutcome;

pub use outcomes::SetSchemaResult;

pub use outcomes::UpdateEntityArgs;

pub use outcomes::UpdateEntityOutcome;

pub use review::ReviewMarkStatus;

pub use review::SetReviewMarkOutcome;

pub use boot::SchemaResolver;

pub use boot::load_workspace_schemas;

pub use boot::resolve_builtin_schema_pin_pub;

pub use lifecycle::SchemaStaging;

Modules

apply_commit

Apply a CommitEnvelope to the in-memory store.

archive

Byte-based snapshot API: hydrate an engine from sealed .mem archive bytes, and export a mem’s current state back to archive bytes.

boot

Engine construction — from_mounts* and from_workspace_root.

check_ops

The check operation and derived check state (agent-trust plan 14).

drift

Drift detection and per-mem change synthesis.

due

The due-brief (first-author-path plan 08): a schema declares its deadline axis (memstead_schema::DueAxis), the engine renders “what is due next” as one deterministic markdown brief.

error

Engine error envelopes.

events

Mem-change events: runtime-agnostic callback-based subscribe API.

export_html

export --format html (first-author-path plan 11): one self-contained HTML file per mem — the read surface for non-operators. A file you hand to a person: no server, no account, no installed anything.

file_watcher

Cross-process file-watcher convenience for the change-event surface.

history

Per-entity history — the narrative query behind an inspector’s “how did this entity get this way”.

lifecycle

Engine lifecycle — settings/workspace-root setters, runtime mem add/remove, reload, and export.

mutation

Engine mutation entrypoints — split per mutation kind.

outcomes

Argument/outcome shapes for the mutation entrypoints (Engine::create_entity, update_entity, delete_entity, relate_entity, rename_entity). The MCP wire envelopes and CLI command output formatters branch on these shapes; their field layouts are part of the engine’s public surface.

query

Engine read paths — accessors and queries.

review

Review marks — one per-mem pointer to the last human-approved state (the operator’s review model: diffs accumulate against it, approving moves it, ignoring it entirely is first-class).

Structs

Engine

Unified engine. Holds a list of mounted backends and routes mem-named operations to the right one.

GitBranchOps

Bundle of git-branch-specific op dispatchers. Installed on the engine at full boot. Each field is one ops-method that previously lived on the MemBackend trait; moving them off the trait keeps the bytes-level primitive surface clean.

QuarantinedMem

One quarantined mem: the mem-level boot failure that took it out of service, and the retained mount record reload uses to re-attempt the attach after a repair. The reason code/message are plan-01 typed material — the message’s final clause names the repair command, so the roster entry is actionable as-is.

Type Aliases

BackendFactory

Backend factory function pointer. Both flavours’ existing instantiate_*_backend functions match this signature, so the type alias is what bridges the dependency direction (memstead-base can’t depend on memstead-git-branch) without an extra trait. Stateless, Send + Sync + Copy.

GitBranchBranchResetFn

Engine::branch_reset dispatch for git-branch mounts. Returns the outcome on success; surfaces BackendError::Other carrying an in-band marker (UNKNOWN_REF:<raw> or PUSHED_COMMITS_PROTECTED:<sha,sha,...>) the engine layer un-marshals into typed EngineErrors.

GitBranchChangesSinceFn

Engine::changes_since dispatch for git-branch mounts.

GitBranchDiffFn

Engine::diff dispatch for git-branch mounts. Walks the two refs inside the workspace’s mem-repo gitdir, produces a per-entity crate::ops::Diff. Refs are arbitrary gix::rev_parse_single inputs — branch names, commit SHAs, tag names. Resolves each independently so cross-branch (cross-mem) diffs work uniformly.

GitBranchExportFn

Engine::export_mem dispatch for git-branch mounts.

GitBranchExportToBytesFn

Engine::export_mem_to_bytes dispatch for git-branch mounts.

GitBranchFetchFn

Engine::fetch dispatch for git-branch mounts.

GitBranchPruneResidueFn

Residue-prune dispatch for git-branch mounts. The create_mem orchestrator calls this when RecoveryAction::ForceOverwrite is selected against pre-existing storage residue. Drops refs/heads/<branch_full_path> and the __MEMSTEAD:mems/<branch_full_path>/config.json blob in one ref-edit transaction (the same call the MemBackend::delete_artifacts impl wraps for delete-files flows). Surfaces as a function pointer so memstead-engine can drive a prune against an unmounted gitdir without depending on memstead-git-branch.

GitBranchPullFn

Engine::pull dispatch for git-branch mounts.

GitBranchPushFn

Engine::push dispatch for git-branch mounts.

GitBranchReadRefSchemasFn

Re-read every schema sealed on the workspace’s __MEMSTEAD:schemas/ ref (empty when the ref or subtree is absent). Read-only; Engine::full_refresh is the consumer — the warm-server path that makes an out-of-band memstead schema install resolvable without a process restart.

GitBranchReadSchemaFileFn

Read one file from a sealed schema package on the workspace’s __MEMSTEAD:schemas/<name>@<version>/ ref. Ok(None) when the ref, package, or file is absent — absence is a normal state (the install-provenance stamp only exists for path-sourced installs). Read-only; the authoring-drift health axis is the consumer.

GitBranchReadTreeFn

Read every .md blob at ref_name in gitdir, returning (relative_path, utf8_content) pairs. Skips .memstead/ engine-internal entries and non-blob nodes. Used by the pre-merge schema-validation pass Engine::pull and Engine::push run before they advance the branch pointer / push to the remote.

GitBranchRemoteAddFn

Engine::remote_add dispatch — configures a named remote on the mem-repo gitdir (upsert: add, or set-url when it already exists).

GitBranchRenameMemStorageFn

rename_mem dispatch for the git-branch backend: move the mem’s content branch refs/heads/<old> to refs/heads/<new> at the same tip (history preserved) and relocate the __MEMSTEAD:mems/<old>/ config blob to mems/<new>/, all in one ref-edit transaction. Refuses (no mutation) when the source branch is missing or the target branch already exists.

GitBranchWriteSchemaFn

Engine::install_schema dispatch for the git-branch backend: write a schema package ((relative-path, bytes) pairs) onto the workspace’s unified __MEMSTEAD:schemas/<name>@<version>/ ref and return the resulting commit sha. Mirrors memstead_git_branch::storage_memstead::write_schema_to_memstead_ref.

MutationClock

Clock the engine reads when stamping mutation timestamps. Arc’d closure rather than a trait so a test can pin a constant with one line: engine.set_mutation_clock(Arc::new(|| some_time)).