Module engine_error 

Typed engine-error surface (issue #58.6).

RFC-012 Stage 1a: moved from ff-sdk::engine_error to ff-core::engine_error so it becomes nameable by the EngineBackend trait (which lives in ff-core::engine_backend) without forcing a public-surface dependency from ff-core on ff-script. The [ScriptError]-aware helpers (From<ScriptError>, valkey_kind, transport_script, transport_script_ref) live in ff-script as free functions (see ff_script::engine_error_ext) — ff-core owns the enum shapes; ff-script owns the transport-downcast plumbing.

Mapping shape

ScriptError lives in the ff-script crate (transport-adjacent). EngineError lives here in ff-core and is what public SDK calls return via ff_sdk::SdkError::Engine. The bidirectional mapping:

• From<ScriptError> for EngineError — every ScriptError variant is classified into NotFound / Validation / Contention / Conflict / State / Bug / Transport. Parse + Valkey flow through Transport { source: Box<ScriptError> } so the underlying ferriskey::ErrorKind / parse detail is preserved.
• DependencyAlreadyExists is special: per the #58.6 design the variant carries the pre-existing [EdgeSnapshot] inline. Populating that field requires an extra round-trip (the Lua script only knows the edge_id), so plain From<ScriptError> returns a Transport fallback for that code — callers in the stage_dependency path use ff_sdk::engine_error::enrich_dependency_conflict to perform the follow-up describe_edge and upgrade the error before returning.

Exhaustiveness

The top-level EngineError and every sub-kind are #[non_exhaustive]. FF can add new Lua error codes in minors without a breaking change to this surface — consumers that match on a sub-kind must include a _ arm.

Enums

BackendError

Backend-agnostic transport error carried across public ff-sdk / ff-server error surfaces (#88).

BackendErrorKind

Classified backend transport errors, kept backend-agnostic on purpose (#88). Each variant maps a family of native backend error kinds into a stable, consumer-matchable shape.

BugKind

FF-internal invariant-violation sub-kinds. Should not be reachable in a correctly-behaving deployment.

ConflictKind

Permanent conflict sub-kinds. Caller must reconcile rather than retry.

ContentionKind

Contention sub-kinds (retryable per RFC-010 §10.7). Caller should re-dispatch or re-read and retry.

EngineError

Typed engine-error surface. See module docs.

StateKind

Legal-but-surprising state sub-kinds. Per-variant semantics vary (some are benign no-ops, some are terminal). Consult the RFC-010 §10.7 classification table.

ValidationKind

Validation sub-kinds. 1:1 with the Lua validation codes.

Functions

backend_context

Wrap an EngineError with a call-site label when the error is a transport-family fault — Transport or Unavailable. Typed classifications (NotFound, Validation, Contention, Conflict, State, Bug) form the public contract boundary for consumers that match on the variant, so we return them unchanged. Repeated wraps on an already-Contextual error nest an additional layer; callers should wrap once per op boundary.