Module shape_expr 

Fuel’s independent typed shape-expression AST + §6.19 canonical wire codec + evaluator (KISS-Ops §6.20). Byte-matches the KISS reference (conformance/src/shape_expr.rs), verified against the vendored golden vectors — the shape-side companion to the value oracle. EXPRESSION kind only (SameAs + DimExpr); the role/index-woven kind (reduce/gather/matmul) is a separate variant (Convergence-C C-2). Every malformed input is a typed decline, never a panic.

MOVED (Increment C slice 1, T1): the implementation now lives in fuel_kernel_seam_types::shape_expr — its permanent, dependency-free home, so fuel-graph can carry Dim/ShapeExpr in OpAttrs without depending on this crate. This module is a re-export shim: every existing crate::fkc::shape_expr::… path keeps compiling unchanged. The codec goldens moved with it (see the seam-types test module). The text-surface parser (shape_expr_parse) stays here — contract-import machinery, not grammar.

Enums

Dim

A single-dimension expression (DimExpr).

DimValue

Evaluating a DimExpr: a concrete dim, or a surfaced gap (§6.20-0004).

ShapeExpr

A whole-shape expression (ShapeExpr). The closed core is SameAs; WithDim and Dims are the experimental-range extension constructors registered via the KISS umbrella §6.4 registry (Ops §6.20-0009/-0010, issue #80), activating the §6.20-0005 tags 0x0A/0x0B. Reduce (0x09) stays reserved (no consumer).

ShapeExprError

A typed decline. A reader MUST refuse malformed input with one of these, never a panic (§6.20-0003/0006).

ShapeValue

Evaluating a ShapeExpr: a concrete shape, or a surfaced gap.

Constants

LAST

Reserved axis sentinel = the trailing axis, resolved to rank-1 at eval (§6.20-0002/-0003). Concrete axes are 0..MAX_RANK-1 (MAX_RANK=8), so 0xFF is unambiguously last. DISTINCT from §6.19-0020’s 0xFFFE (u16 axis-set mask) — a different field, different width.

SYMBOLIC

Sentinel extent for a symbolic / data-dependent axis length → surfaced Gap (§6.20-0004).

TAG_ADD

TAG_CONST

TAG_DIMS

TAG_DIV

TAG_EXTENT

TAG_MUL

TAG_PARAM

TAG_REDUCE

TAG_SAME_AS

TAG_SUB

TAG_WITH_DIM

Functions

decode_dim

Decode one DimExpr blob, rejecting a malformed one with a typed decline. Round-trips: decode_dim(&d.encode()) == Ok(d).

decode_shape

Decode one whole-shape ShapeExpr blob, rejecting a malformed one with a typed decline (§6.20-0006). Reads SameAs (core) plus the registered experimental extension constructors WithDim/Dims (§6.20-0009/-0010); the still-reserved Reduce (0x09) and the DimExpr-only tags decline typed. A well-formed blob round-trips: decode_shape(&s.encode()) == Ok(s). Distinct from decode_dim, which reads the single-dimension grammar (a Dim is never a whole shape, so a whole-shape tag declines there, and vice-versa).

eval_dim

Evaluate a DimExpr against operand shapes + param values.

eval_shape

Evaluate a ShapeExpr to a concrete shape (or a surfaced gap).

gather_shape

§6.20-0008 gather/index_select/embedding shape rule: the data shape with the gathered axis replaced by the index shape (data[..axis] ++ index ++ data[axis+1..]). In general the output equals NO operand’s shape — which is why advertising same_as(data) for a gather is a bug the shape oracle catches.

matmul_shape

§6.20-0008 matmul (contraction) shape rule: role-vector-derived (KISS-Classify §6.6-0016 M/N/K axis roles, carried as roles not a ShapeExpr). For the canonical same-rank ≥ 2 cell lhs[..batch, M, K] · rhs[..batch, K, N] -> [..batch, M, N]; the output equals neither operand (§6.20-0008).

reduce_shape

§6.20-0007 reduce-family shape rule: the input shape with reduce_axes removed (keepdim=false) or set to 1 (keepdim=true) — derived from op semantics.

resolve_axis

Resolve a non-negative axis (or LAST) against rank (§6.20-0003). pub since Increment C slice 1 (T2): the recipe-interior axis_last resolver (fuel_graph::runtime_fused::resolve_rel_attrs) reuses this as the single LAST→rank−1 evaluator instead of growing a second one.

shape_consistent

KISS-CONTRACT-6.4-0011: the Interface declared output shape is consistent iff it equals the op’s shape rule computed over the operand shapes. A surfaced Gap (symbolic/data-dependent output) is never a hard inconsistency — a consumer cannot assert a mismatch it cannot compute. The shape-side companion to the §6.4-0006 value oracle.