Enum FullEngineError 

pub enum FullEngineError {
    Lean(EngineError),
    MemPathNotAllowed {
        attempted: PathBuf,
        candidate: String,
        patterns: Vec<String>,
        reason: &'static str,
        policy_table: &'static str,
    },
    InvalidMemName {
        name: String,
        reason: &'static str,
    },
    MemReferencedByPolicy {
        name: String,
        referring_mems: Vec<String>,
    },
    MemSchemaNotAllowed {
        candidate: String,
        matched_pattern: String,
        requested_schema: String,
        allowed_schemas: Vec<String>,
    },
    ConfigAlreadyExists {
        path: PathBuf,
    },
    MemStorageResidueDetected {
        branch_ref: String,
        config_blob: Option<String>,
        entity_count: usize,
    },
}

Errors surfaced by the full engine extension.

Lean(EngineError) wraps any failure that originates in the underlying lean engine — full orchestrators that delegate to memstead_base::Engine propagate lean errors verbatim through this variant (#[from]), so the wire-rendering layer at the full MCP surface can recover the lean code() for any wrapped variant.

The remaining variants are lifecycle-only: they fire from the full mem management orchestrator (create_mem / delete_mem) and have no lean-side fire conditions. They live in this crate alongside their orchestrator.

Variants

Lean(EngineError)

Wrapped lean-engine error. Use this variant whenever a full code path delegates to memstead_base::Engine and a lean-side failure should surface unchanged.

MemPathNotAllowed

create_mem / delete_mem rejected because the mem path is not covered by an allowlist rule. reason is one of no_allowlist_configured / no_match / outside_workspace. policy_table names the refusing allowlist — "mem_management.create" or "mem_management.delete" — so an agent recovering from the envelope knows which TOML table to edit without threading subcommand context through error handling. The two discriminators are orthogonal: reason names why the gate refused; policy_table names which gate refused.

Fields

attempted: PathBuf

candidate: String

patterns: Vec<String>

reason: &'static str

policy_table: &'static str

InvalidMemName

create_mem rejected before the allowlist check because the supplied name is structurally malformed — empty, whitespace, invalid characters, or carries the reserved __ prefix. reason discriminates the four shapes so an agent who typed the wrong thing gets a recoverable signal instead of an allowlist refusal. Split out of the MemPathNotAllowed (no_match) catch-all so the structural failure modes are visible.

Fields

name: String

reason: &'static str

MemReferencedByPolicy

delete_mem rejected because the workspace [cross_mem_links] policy grants one or more other mems permission to write into this one. referring_mems lists the granting mems sorted alphabetically so the agent can walk the policy table. The condition is a policy grant, not a materialised graph edge — revoking the grant in .memstead/workspace.toml is the recovery path.

Fields

name: String

referring_mems: Vec<String>

MemSchemaNotAllowed

create_mem rejected because the matched create-rule does not allow the requested schema. allowed_schemas is the canonicalised allow-list (each entry name@version).

Fields

candidate: String

matched_pattern: String

requested_schema: String

allowed_schemas: Vec<String>

ConfigAlreadyExists

create_mem rejected because the target .memstead/config.json already exists at the requested location — the engine never silently overwrites a prior attempt.

Fields

path: PathBuf

MemStorageResidueDetected

create_mem detected on-disk storage residue for the requested branch path that is not reflected in the in-memory mem router — typically left over by a crash or a partially-failed delete. The caller must select an explicit recovery action via [MemCreateParams::recovery] (Reattach, ForceOverwrite, or HardCleanupFirst) and retry; the special case of unregistered_at-tombstoned residue (deliberate operator state from memstead mem unregister) defaults to Reattach without this refusal. The payload carries the composed branch ref, the config-blob path, and the entity count of the residual data so the caller can decide between adopting and discarding.

Fields

branch_ref: String

Composed branch reference (refs/heads/<branch_leaf>) that carries the residue.

config_blob: Option<String>

Tree path of the __MEMSTEAD:mems/<branch_leaf>/config.json blob (or None when the branch exists but the config blob has already been pruned).

entity_count: usize

Best-effort entity count on the residual branch. Reads the branch’s tip tree and counts .md entries; 0 when the count is unavailable.

Implementations

impl FullEngineError

pub fn prose_render(&self) -> String

Render rich, fully-inlined recovery prose for the agent-visible text channel. Closes the asymmetry where structured details.X fields stayed off the agent’s text channel. Each lifecycle variant with a structured list (patterns, referring_mems, allowed_schemas) inlines the full payload; lean wraps delegate to EngineError::prose_render; trivial variants fall back to Display.

pub fn details(&self) -> Value

Variant-specific recovery payload, rendered as a structured JSON object that surfaces under error.details in MCP / CLI envelopes. The CLI’s mem commands used to discard the engine’s structured details because the lift code didn’t have a single source of truth — this mirrors EngineError::details() so the lift can call err.details() directly without hand-maintaining each per- variant payload at the CLI surface.

Lean(inner) delegates to EngineError::details(). Lifecycle variants return the same JSON object shape full_engine_err_unified builds on the MCP wire — both surfaces share the payload here so they cannot drift.

pub fn code(&self) -> &'static str

Stable, surface-independent error code token.

Matches memstead_base::EngineError::code() for every variant — wrapped lean errors delegate to the lean mapping, lifecycle variants return the exact strings the lean enum returned for them today. This is load-bearing: the wire-shape pins in memstead-mcp/tests/wire_shape.rs assert these exact code strings.

Trait Implementations

impl Debug for FullEngineError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for FullEngineError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for FullEngineError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<EngineError> for FullEngineError

fn from(source: EngineError) -> Self

Converts to this type from the input type.