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 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 boot::SchemaResolver;

pub use boot::resolve_builtin_schema_pin_pub;

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.

drift

Drift detection and per-mem change synthesis.

error

Engine error envelopes.

events

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

file_watcher

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

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.

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.

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.

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

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.