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;

Modules§

error: Full-flavor engine error envelope.
health: The memstead_health composer, re-exported from memstead-base so the full engine’s callers keep their import path. The composer lives in the base crate because every renderer of the health report (the MCP server, the CLI in both its full and lean builds) must build the same bytes from one implementation (backlog-engine plan A7).
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§

HealthArgs: Composer input — packed from the MCP HealthParams (or a CLI Args) at the call site. Mirrors the field set the pre-lift handler read off HealthParams.
HealthConfig: Surface-owned config the engine does not carry — supplied prebuilt so the composer inserts the bytes verbatim. mutations is {"require_notes": …}; plugin is the opaque [plugin.*] pass-through object. Only consulted when args.include_config is set.
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§

ComposeHealthError: Typed input failures the composer surfaces. The MCP wrapper maps each variant to its existing envelope (UNKNOWN_MEM, INVALID_INPUT) and the engine fault to its typed translator, so the wire code stays put.
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 is an additive variant; two variants suffice today.

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_health: Build the complete health payload. drift_warnings are the reload warnings the wrapper collected before calling in; the composer extends them with the health report’s own warnings, the limit-clamp notice, and unknown-include notices, then embeds the lot under warnings.
compose_overview: Compose the overview markdown for either surface.