Crate memstead_engine

Expand description

Full-flavor engine extension for Memstead.

This crate is the source-boundary home for code that the lean engine (memstead-base) must not carry. The boundary cut targets multi-mem lifecycle and the engine-only EngineError variants.

Today the crate hosts:

The typed full-error envelope (FullEngineError) — wraps memstead_base::EngineError and carries the lifecycle-only variants (error::FullEngineError::MemPathNotAllowed, error::FullEngineError::MemReferencedByPolicy, error::FullEngineError::MemSchemaNotAllowed, error::FullEngineError::ConfigAlreadyExists).
The mem-lifecycle orchestrators (mem_management::create_mem, mem_management::delete_mem) and their param/response types. They consume &mut memstead_base::Engine directly; full contributes lifecycle as free functions over the lean engine rather than via a wrapper struct or a policy-provider trait.

The matcher primitives (memstead_base::CreateRuleSet, memstead_base::DeleteRuleSet, memstead_base::MatcherSet) stay in lean — the lean engine’s cross_mem_link_allowed synthesises a CreateRuleSet on multi-folder workspaces, so they are a lean policy primitive used by both flavors.

Lifecycle functions currently return Result<_, memstead_base::EngineError> so the full-MCP server’s engine_err_unified mapper continues to consume them unchanged. A follow-up commit switches the return type to Result<_, FullEngineError> and drops the four lifecycle-only variants from memstead_base::EngineError.

Re-exports§

pub use error::FullEngineError;
pub use error::RecoveryAction;
pub use health::ComposeHealthError;
pub use health::HealthArgs;
pub use health::HealthConfig;
pub use health::compose_health;

Modules§

error: Full-flavor engine error envelope.
health: Shared health composer used by the memstead_health MCP tool and any non-MCP caller (CLI, a future HTTP surface).
mem_management: Mem-lifecycle orchestrator — full home for the multi-mem create and delete pipelines. The matcher primitives (memstead_base::CreateRuleSet, memstead_base::DeleteRuleSet, memstead_base::MatcherSet) stay in lean because the lean engine’s cross_mem_link_allowed synthesises a memstead_base::CreateRuleSet on multi-folder workspaces. Only the lifecycle orchestrators — create_mem, delete_mem, their param/response types, the shared NOTE_MAX_LEN cap, and the validate_mem_path helper — live here.
overview: The overview composer was relocated into memstead-base (its sole engine-type parameter already is memstead_base::Engine, and it imports only memstead-base + memstead-schema + std) so the lean memstead-mcp build — which does not depend on memstead-engine — can render the identical overview from one rendering authority.
workspace_config_edit: toml_edit-backed writer for .memstead/workspace.toml.

Structs§

OverviewArgs: Composer input — packed from the MCP OverviewParams or the CLI Args at the call site. chunk is intentionally NOT here: the surface decides how to chunk the output (MCP wraps with apply_chunking at a transport budget; CLI does the same at its own default), so the composer just returns markdown.
OverviewOutput: Composer output — rendered markdown plus the structured bits the surface needs to assemble its final envelope. extra_frontmatter is the (key, value) slot the surface threads into its own chunking helper (preserved at every chunk’s head).

Enums§

ComposeOverviewError: Typed input failures the composer surfaces. The MCP wrapper maps each variant to its existing envelope (INVALID_INPUT, UNKNOWN_MEM); the full CLI does the same to its CLI error codes.
Surface: Which surface is rendering. The composer branches on this only for inline command-name hints — never for content or shape. Adding a new surface (e.g. UniFFI) is an additive variant; today the macOS app consumes structured engine data, not rendered markdown, so two variants suffice.

Constants§

ALLOWED_OVERVIEW_INCLUDE_KEYS: Heavy-content include keys the composer recognises. Order is the greedy-fill priority order: mem_distribution, community_members, community_bridges, dangling_links. include-listed keys force inclusion regardless of budget; unlisted keys greedy-fill until the budget is exhausted, then surface as hints.
DEFAULT_OVERVIEW_BUDGET: Default token budget for heavy content. Matches the MCP tool’s pre-lift constant and the public-facing description.

Functions§

compose_overview: Compose the overview markdown for either surface.