tatara_lisp/

error.rs

use thiserror::Error;

use crate::span::Span;

pub type Result<T> = std::result::Result<T, LispError>;

// Compile-time pairwise-distinctness witnesses — one `const _: () =
// crate::ast::assert_str_array_pairwise_distinct(&…)` per family-wide
// `[&'static str; N]` array on this module's closed-set diagnostic /
// classification algebras. Each invocation is const-evaluated at
// `cargo check` time; a regression that silently collides two entries
// on any of these arrays fails the build rather than the test suite.
//
// Sibling to the runtime `_pairwise_distinct` tests (`compiler_spec_
// io_stage_labels_pairwise_distinct`, `macro_def_head_keywords_
// pairwise_distinct`, `unquote_form_markers_pairwise_distinct`,
// `unquote_form_iac_forge_tags_pairwise_distinct`,
// `unquote_form_labels_pairwise_distinct`, `kwarg_path_kind_labels_
// pairwise_distinct`, `expected_kwarg_shape_labels_pairwise_distinct`,
// `sexp_shape_labels_pairwise_distinct`,
// `structural_kind_labels_pairwise_distinct`) plus the runtime cross-
// check `assert_str_array_pairwise_distinct_accepts_every_family_
// wide_error_module_array` on this module's tests submodule — the
// three surfaces enforce the SAME theorem at THREE stages of the
// toolchain (compile-time `const _` sweep, per-array runtime pin,
// runtime cross-check), so a build that skips tests still catches
// the regression here, and a build that runs tests catches it a
// second and third time as safety nets if the const-eval sweep is
// ever silently dropped.
//
// Column-dual peer to the FIVE `assert_str_array_pairwise_distinct`
// witnesses on `ast.rs`'s closed-set outer algebras
// (`Atom::BOOL_LITERALS`, `AtomKind::LABELS`, `QuoteForm::PREFIXES`,
// `QuoteForm::IAC_FORGE_TAGS`, `QuoteForm::LABELS`) on the
// (declaration-file) axis: `ast.rs` covers the reader / atomic-
// payload / quote-family vocabulary; `error.rs` covers the
// diagnostic / classification / typed-entry-rejection vocabulary
// across NINE closed-set algebras (`CompilerSpecIoStage`,
// `TemplateInvariantKind` (STATIC + DYNAMIC subsets),
// `MacroDefHead`, `OptionalParamMalformedReason` (STATIC + DYNAMIC
// subsets), `UnquoteForm` (three per-role vocabularies —
// MARKERS / IAC_FORGE_TAGS / LABELS), `KwargPathKind`,
// `ExpectedKwargShape`, `SexpShape`, `StructuralKind`) — the two
// files together lift ALL EIGHTEEN family-wide `[&'static str; N]`
// arrays declared on `tatara-lisp`'s closed-set outer algebras into
// a COMPILE-TIME pairwise-distinctness theorem.
//
// `CompilerSpecIoStage::OPERATIONS` (`[&'static str; 4]` at
// line 1744) is DELIBERATELY excluded from this block: it is a
// variant-aligned projection whose four entries are
// `[REALIZE_TO_DISK, REALIZE_TO_DISK, LOAD_FROM_DISK, LOAD_FROM_DISK]`
// (the first two arms and the last two arms collapse onto the
// per-operation labels), so the array is INTENTIONALLY non-distinct.
// Enrolling it in this block would fail const-eval; the intended
// invariant on `OPERATIONS` is "variant-index alignment with
// `CompilerSpecIoStage::ALL`", not injectivity — different theorem,
// different helper. The peer helper the substrate now carries is
// `crate::ast::assert_str_array_is_concatenation_of_two_scalar_
// replicas` on the (contract-shape ∈ {MANY-TO-ONE-BLOCK-CONSTANCY})
// corner of the (`&'static str`) row; its ONE `const _` witness
// binding `CompilerSpecIoStage::OPERATIONS` lives further down this
// module in the STR-BLOCK-CONSTANCY witness block (search for
// `assert_str_array_is_concatenation_of_two_scalar_replicas`).
//
// Adding a new family-wide `[&'static str; N]` array to this module:
// add ONE co-located `const _: () = crate::ast::assert_str_array_
// pairwise_distinct(&<TYPE>::<ARRAY>);` line in this block AND ONE
// runtime call in the cross-check test on the tests submodule. A
// regression that silently collided two entries on the new array
// would fail `cargo check` at the module-level `const _` line
// before the test suite runs. Rustc's forced-arity `[&'static str;
// N]` composes with this const-eval sweep so BOTH cardinality AND
// injectivity are compile-time theorems on the SAME array
// declaration.
const _: () = crate::ast::assert_str_array_pairwise_distinct(&CompilerSpecIoStage::LABELS);
const _: () =
    crate::ast::assert_str_array_pairwise_distinct(&TemplateInvariantKind::STATIC_MESSAGES);
const _: () =
    crate::ast::assert_str_array_pairwise_distinct(&TemplateInvariantKind::DYNAMIC_DESCRIPTORS);
const _: () = crate::ast::assert_str_array_pairwise_distinct(&MacroDefHead::KEYWORDS);
const _: () =
    crate::ast::assert_str_array_pairwise_distinct(&OptionalParamMalformedReason::STATIC_LABELS);
const _: () = crate::ast::assert_str_array_pairwise_distinct(
    &OptionalParamMalformedReason::DYNAMIC_DESCRIPTORS,
);
const _: () = crate::ast::assert_str_array_pairwise_distinct(&UnquoteForm::MARKERS);
const _: () = crate::ast::assert_str_array_pairwise_distinct(&UnquoteForm::IAC_FORGE_TAGS);
const _: () = crate::ast::assert_str_array_pairwise_distinct(&UnquoteForm::LABELS);
const _: () = crate::ast::assert_str_array_pairwise_distinct(&KwargPathKind::LABELS);
const _: () = crate::ast::assert_str_array_pairwise_distinct(&ExpectedKwargShape::LABELS);
const _: () = crate::ast::assert_str_array_pairwise_distinct(&SexpShape::LABELS);
const _: () = crate::ast::assert_str_array_pairwise_distinct(&StructuralKind::LABELS);

// Compile-time NONEMPTY-CARDINALITY-LOWER-BOUND witnesses — one
// `const _: () = crate::ast::assert_str_array_all_nonempty(&…)` per
// family-wide `[&'static str; N]` array declared in this module.
// Sibling to the `_pairwise_distinct` witnesses above — those pin
// INJECTIVITY on each array (`∀ i ≠ j : arr[i] ≠ arr[j]`), these pin
// the strictly-weaker per-entry cardinality gate (`∀ i : arr[i].len()
// > 0`). The two contracts compose orthogonally: an array carrying
// `["", ""]` fails INJECTIVITY at the zero-length-pair corner, but an
// array carrying `["", "a"]` passes INJECTIVITY while failing NONEMPTY
// — so the NONEMPTY witnesses close the remaining `""`-carrying corner
// that INJECTIVITY alone cannot pin. Every consumer that spells a
// closed-set variant through its `&'static str` label
// (`AtomKind::label` / `QuoteForm::label` / `UnquoteForm::label` /
// `StructuralKind::label` / `SexpShape::label` label projections;
// `KwargPathKind::label` / `ExpectedKwargShape::label` for the kwarg-
// diagnostic vocabulary; `MacroDefHead::KEYWORDS` /
// `UnquoteForm::MARKERS` / `UnquoteForm::IAC_FORGE_TAGS` for the
// reader-boundary sub-vocabularies; `CompilerSpecIoStage::LABELS` for
// the compiler-spec I/O stage diagnostic) treats each entry as a
// NONEMPTY identifier and would silently mis-behave on a `""` entry.
// The two `TemplateInvariantKind` message / descriptor arrays and the
// two `OptionalParamMalformedReason` message / descriptor arrays are
// nonempty for the same reason — an empty diagnostic message erases
// the failure signal at the display boundary.
const _: () = crate::ast::assert_str_array_all_nonempty(&CompilerSpecIoStage::LABELS);
const _: () = crate::ast::assert_str_array_all_nonempty(&TemplateInvariantKind::STATIC_MESSAGES);
const _: () =
    crate::ast::assert_str_array_all_nonempty(&TemplateInvariantKind::DYNAMIC_DESCRIPTORS);
const _: () = crate::ast::assert_str_array_all_nonempty(&MacroDefHead::KEYWORDS);
const _: () =
    crate::ast::assert_str_array_all_nonempty(&OptionalParamMalformedReason::STATIC_LABELS);
const _: () =
    crate::ast::assert_str_array_all_nonempty(&OptionalParamMalformedReason::DYNAMIC_DESCRIPTORS);
const _: () = crate::ast::assert_str_array_all_nonempty(&UnquoteForm::MARKERS);
const _: () = crate::ast::assert_str_array_all_nonempty(&UnquoteForm::IAC_FORGE_TAGS);
const _: () = crate::ast::assert_str_array_all_nonempty(&UnquoteForm::LABELS);
const _: () = crate::ast::assert_str_array_all_nonempty(&KwargPathKind::LABELS);
const _: () = crate::ast::assert_str_array_all_nonempty(&ExpectedKwargShape::LABELS);
const _: () = crate::ast::assert_str_array_all_nonempty(&SexpShape::LABELS);
const _: () = crate::ast::assert_str_array_all_nonempty(&StructuralKind::LABELS);

// Compile-time ASCII-BYTE-RANGE witnesses — one `const _: () =
// crate::ast::assert_str_array_all_ascii(&…)` per family-wide
// `[&'static str; N]` array declared in this module. Sibling to the
// `_all_nonempty` witnesses above on the (per-entry × contract-shape)
// axis: those pin the length-lower-bound gate (`∀ i : arr[i].len() >
// 0`), these pin the strictly-orthogonal byte-range gate (`∀ i, ∀ b ∈
// arr[i].as_bytes() : b <= 0x7F`). The two contracts compose
// orthogonally — an array carrying `["café"]` passes NONEMPTY while
// failing ASCII; `["", "a"]` passes ASCII while failing NONEMPTY.
// Every consumer that ships an entry through a seven-bit-clean
// downstream surface (K8s annotation keys + label values; YAML
// flow-scalar map keys; BLAKE3 hash inputs; Rust byte-pattern
// `matches!` arms) treats each entry as ASCII — a non-ASCII byte
// silently invites Unicode-normalization drift on the wire and
// lookalike-label collisions that byte-equality parsing cannot
// detect. Post-lift a regression that silently re-inlined one label
// constant to a lookalike non-ASCII spelling fails at `cargo check`
// BEFORE any test scheduler runs. The thirteen arrays covered here
// mirror the thirteen arrays already pinned by the `_all_nonempty`
// witnesses above — the (per-entry × contract-shape) coverage matrix
// on the (`&'static str`) row of this module now holds at BOTH
// corners {NONEMPTY, ASCII} for every family-wide array declared
// here.
const _: () = crate::ast::assert_str_array_all_ascii(&CompilerSpecIoStage::LABELS);
const _: () = crate::ast::assert_str_array_all_ascii(&TemplateInvariantKind::STATIC_MESSAGES);
const _: () = crate::ast::assert_str_array_all_ascii(&TemplateInvariantKind::DYNAMIC_DESCRIPTORS);
const _: () = crate::ast::assert_str_array_all_ascii(&MacroDefHead::KEYWORDS);
const _: () = crate::ast::assert_str_array_all_ascii(&OptionalParamMalformedReason::STATIC_LABELS);
const _: () =
    crate::ast::assert_str_array_all_ascii(&OptionalParamMalformedReason::DYNAMIC_DESCRIPTORS);
const _: () = crate::ast::assert_str_array_all_ascii(&UnquoteForm::MARKERS);
const _: () = crate::ast::assert_str_array_all_ascii(&UnquoteForm::IAC_FORGE_TAGS);
const _: () = crate::ast::assert_str_array_all_ascii(&UnquoteForm::LABELS);
const _: () = crate::ast::assert_str_array_all_ascii(&KwargPathKind::LABELS);
const _: () = crate::ast::assert_str_array_all_ascii(&ExpectedKwargShape::LABELS);
const _: () = crate::ast::assert_str_array_all_ascii(&SexpShape::LABELS);
const _: () = crate::ast::assert_str_array_all_ascii(&StructuralKind::LABELS);

// Compile-time SUBSET-embedding witnesses — the THREE family-wide
// `[&'static str; N]` sub-vocabularies of the substrate's twelve-arm
// outer-shape label vocabulary at `SexpShape::LABELS` whose distinct-
// value set is an intentionally-closed PROPER SUBSET of the outer
// twelve-arm `[&'static str; 12]` superset. Pre-lift the three subset
// relations lived only as prose in the outer array's twelve-arm
// partition-rule docstring plus runtime per-role alias-chain checks
// (each per-role `<TYPE>::<ROLE>_LABEL` on the three sub-vocabulary
// algebras (`AtomKind`, `QuoteForm`, `StructuralKind`) aliases the
// namesake `SexpShape::<ROLE>_LABEL` on the outer algebra); post-lift
// the ARRAY-LEVEL subset embedding of the three pinned pairs binds at
// rustc time via ONE `const _` line per pair. A regression that
// silently re-inlined either the SUBSET side (e.g. dropping
// `AtomKind::SYMBOL_LABEL`'s `SexpShape::SYMBOL_LABEL` alias to a
// fresh distinct byte spelling `"sym"` — the array would still be
// pairwise-distinct AND still disjoint from `QuoteForm::LABELS`, but
// the subset embedding into `SexpShape::LABELS` would break) or the
// SUPERSET side (e.g. dropping `SexpShape::SYMBOL_LABEL` and leaving
// `AtomKind::SYMBOL_LABEL` as a stale copy of `"symbol"` outside the
// outer vocabulary) fails at `cargo check` BEFORE any test scheduler
// runs. Sibling to the FIVE `assert_str_array_pairwise_distinct`
// witnesses on `ast.rs` and the THIRTEEN `assert_str_array_pairwise_
// distinct` witnesses above on the (contract-shape ∈ {pairwise-
// distinctness}) column: those pin INJECTIVITY on each individual
// array; these pin SUBSET containment ORIENTED across PAIRS of arrays
// on the (contract-shape ∈ {subset-embedding}) column.
//
// The three pinned pairs are (all under the shared `&'static str`
// element-type):
//   1. `AtomKind::LABELS`       ⊂ `SexpShape::LABELS` (6-in-12 arms —
//      atomic-payload kind labels; symbol / keyword / string / int /
//      float / bool).
//   2. `QuoteForm::LABELS`      ⊂ `SexpShape::LABELS` (4-in-12 arms —
//      quote-family labels; quote / quasiquote / unquote / unquote-
//      splice).
//   3. `StructuralKind::LABELS` ⊂ `SexpShape::LABELS` (2-in-12 arms —
//      structural-shape labels; nil / list).
//
// Cardinality composition: 6 + 4 + 2 = 12 = `SexpShape::LABELS.len()`
// closes a NON-CONTIGUOUS PARTITION of the outer twelve-arm
// vocabulary at compile time when composed with the THREE pairwise-
// disjointness witnesses on the sub-vocabulary triple: one lives on
// `ast.rs` at the (`AtomKind::LABELS`, `QuoteForm::LABELS`) pair (the
// two sub-vocabularies whose HOST TYPES both live in `ast.rs`), the
// two peers below at the two (`_, StructuralKind::LABELS`) pairs
// (each with ONE sub-vocabulary hosted here in `error.rs`). Together
// with the pre-existing pairwise-distinctness witnesses on each of
// the four arrays, the three subset-embedding witnesses on the three
// sub-vocabulary → superset pairs, AND the three pairwise-disjointness
// witnesses on the three sub-vocabulary × sub-vocabulary pairs, the
// substrate now carries a COMPLETE COMPILE-TIME PROOF that
// `SexpShape::LABELS` is a DISJOINT UNION of the three sub-vocabulary
// arrays — every rearrangement of the twelve outer-shape labels
// across the four algebras is either (a) a legal partition rebalance
// (which passes every witness) or (b) drift that breaks at least one
// of INJECTIVITY / SUBSET-EMBEDDING / PAIRWISE-DISJOINTNESS on at
// least one array or pair, failing `cargo check` before any test
// scheduler runs.
const _: () = crate::ast::assert_str_array_within_str_finite_set::<6, 12>(
    &crate::ast::AtomKind::LABELS,
    &SexpShape::LABELS,
);
const _: () = crate::ast::assert_str_array_within_str_finite_set::<4, 12>(
    &crate::ast::QuoteForm::LABELS,
    &SexpShape::LABELS,
);
const _: () = crate::ast::assert_str_array_within_str_finite_set::<2, 12>(
    &StructuralKind::LABELS,
    &SexpShape::LABELS,
);

// Compile-time DISJOINTNESS witnesses closing the twelve-arm
// `SexpShape::LABELS` partition proof — the TWO remaining sub-
// vocabulary × sub-vocabulary pairs on the partition triple
// (`AtomKind::LABELS`, `QuoteForm::LABELS`, `StructuralKind::LABELS`)
// whose two hosts split across `ast.rs` and `error.rs` (the third
// pair `(AtomKind::LABELS, QuoteForm::LABELS)`, whose two hosts both
// live in `ast.rs`, is pinned there). Pre-lift the two disjointness
// relations lived only as prose in the outer partition-rule
// docstring plus the runtime `sexp_shape_labels_are_disjoint_union`
// cross-check; post-lift the ARRAY-LEVEL disjointness of the two
// pinned pairs binds at rustc time via ONE `const _` line per pair.
// A regression that silently renamed `StructuralKind::NIL_LABEL`
// (`"nil"`) to `"symbol"` (aliasing `AtomKind::SYMBOL_LABEL`),
// renamed `StructuralKind::LIST_LABEL` (`"list"`) to `"quote"`
// (aliasing `QuoteForm::QUOTE_LABEL`), or drifted either entry of
// `StructuralKind::LABELS` to bytes shared with an entry of the
// atomic-kind or quote-family peer sub-vocabulary fails at
// `cargo check` BEFORE any test scheduler runs. Sibling to the FOUR
// `assert_str_arrays_disjoint` witnesses in `ast.rs`.
//
// The two pinned pairs are (all under the shared `&'static str`
// element-type):
//   1. `AtomKind::LABELS`  ∩ `StructuralKind::LABELS` = ∅
//   2. `QuoteForm::LABELS` ∩ `StructuralKind::LABELS` = ∅
//
// Composed with the ast.rs-pinned
// (`AtomKind::LABELS`, `QuoteForm::LABELS`) disjointness witness,
// the THREE pairwise-disjointness witnesses cover every pair on the
// three-element sub-vocabulary triple (C(3, 2) = 3 pairs). Together
// with the three pairwise-distinctness INTRA-array witnesses AND the
// three SUBSET-embedding witnesses above, the substrate now carries
// the full DISJOINT-UNION theorem
//   `SexpShape::LABELS ≡ AtomKind::LABELS ⊕ QuoteForm::LABELS ⊕
//    StructuralKind::LABELS`
// as a rustc-time proof obligation, closing the twelve-arm outer
// vocabulary partition at compile time.
const _: () = crate::ast::assert_str_arrays_disjoint::<6, 2>(
    &crate::ast::AtomKind::LABELS,
    &StructuralKind::LABELS,
);
const _: () = crate::ast::assert_str_arrays_disjoint::<4, 2>(
    &crate::ast::QuoteForm::LABELS,
    &StructuralKind::LABELS,
);

// Compile-time (⊆) SET-COVERAGE witness closing the twelve-arm
// `SexpShape::LABELS` disjoint-union theorem — every entry of the
// parent outer-shape vocabulary is reached by at least one of the
// three sub-vocabularies (`AtomKind::LABELS`, `QuoteForm::LABELS`,
// `StructuralKind::LABELS`). Composes with the pre-existing (⊇)
// SUBSET-embedding witnesses (three `_within_str_finite_set` lines
// above), the pairwise-DISJOINTNESS witnesses (two above plus one
// (`AtomKind::LABELS` ∩ `QuoteForm::LABELS`) in `ast.rs`), and the
// parent INJECTIVITY witness (`assert_str_array_pairwise_distinct(
// &SexpShape::LABELS)` above) to close the FULL disjoint-union
// theorem
//   `SexpShape::LABELS ≡ AtomKind::LABELS ⊕ QuoteForm::LABELS ⊕
//    StructuralKind::LABELS`
// as a rustc-time proof obligation. Pre-lift the (⊆) direction lived
// only as the runtime cross-check
// `sexp_shape_labels_is_disjoint_union_of_three_sub_vocabularies` at
// the tests submodule; post-lift the (⊆) direction binds at `cargo
// check` time via ONE `const _` line on the partition quadruple. A
// regression that silently drops a variant from ONE sub-vocabulary
// (e.g. removing `AtomKind::Bool` and its `AtomKind::BOOL_LABEL`
// alias while leaving `SexpShape::Bool` and `SexpShape::BOOL_LABEL`
// in the parent vocabulary) fires the SET-STR-MISSING panic at
// `cargo check` BEFORE any test scheduler runs.
//
// Composition law with the sibling (⊇) SUBSET + pairwise-
// DISJOINTNESS + parent INJECTIVITY witnesses: given the four
// corners, the disjoint-union theorem follows CONSTRUCTIVELY —
//   (⊇) every sub-vocabulary label is in the parent (three SUBSET
//        witnesses);
//   (⊆) every parent label is in some sub-vocabulary (this witness);
//   pairwise-disjoint sub-vocabularies (three DISJOINTNESS witnesses);
//   parent has no duplicate entries (INJECTIVITY witness).
// The cardinality composition `6 + 4 + 2 = 12` is a CONSEQUENCE of
// the four corners rather than a separate pre-check; the rustc-
// enforced arities `[&'static str; N]` for N ∈ {6, 4, 2, 12} pin the
// cardinality quadruple at the declaration site.
const _: () = crate::ast::assert_str_finite_set_covered_by_three_str_arrays::<6, 4, 2, 12>(
    &crate::ast::AtomKind::LABELS,
    &crate::ast::QuoteForm::LABELS,
    &StructuralKind::LABELS,
    &SexpShape::LABELS,
);

// Compile-time SLICE-EQUALS-ARRAY witnesses closing the twelve-arm
// `SexpShape::LABELS` POSITIONAL decomposition — the FOUR canonical
// sub-slices of the twelve-slot outer container each byte-equal a
// sub-carving's canonical `[&'static str; M]` listing at rustc time.
// Strictly STRONGER on the (contract-strength) axis than the seven
// sibling SET-level witnesses above (three `_within_str_finite_set`
// SUBSET-embedding + three `_arrays_disjoint` pairwise-disjointness +
// one `_finite_set_covered_by_three_str_arrays` coverage): the SET-
// level disjoint-union theorem `SexpShape::LABELS ≡ AtomKind::LABELS ⊕
// QuoteForm::LABELS ⊕ StructuralKind::LABELS` those seven witnesses
// close is SILENT on which SLOTS each sub-vocabulary's arms occupy —
// a regression that permuted `SexpShape::LABELS` from the CANONICAL
// declaration order `[NIL, SYMBOL, KEYWORD, STRING, INT, FLOAT, BOOL,
// LIST, QUOTE, QUASIQUOTE, UNQUOTE, UNQUOTE_SPLICE]` (`StructuralKind`
// at slots `{0, 7}`, `AtomKind` at slots `[1..7)`, `QuoteForm` at
// slots `[8..12)`) to `[SYMBOL, NIL, KEYWORD, STRING, INT, FLOAT,
// BOOL, LIST, QUOTE, QUASIQUOTE, UNQUOTE, UNQUOTE_SPLICE]` (swapping
// slots `0` and `1`, interleaving `AtomKind` into a slot the
// structural-residual carving previously owned) preserves the SET-
// level disjoint-union theorem (both sub-vocabularies still embed
// into the parent, still cover, still disjoint, parent still
// injective) but silently misaligns every consumer indexing
// `SexpShape::LABELS[0]` for the NIL diagnostic literal. Post-lift
// the ARRAY-LEVEL positional decomposition binds at rustc time via
// FOUR `const _` lines below, one invocation stage earlier than the
// runtime pin.
//
// Sibling posture to the (u8)-row's FOUR positional witnesses on
// `SexpShape::HASH_DISCRIMINATORS` at `ast.rs` (two singleton
// `assert_u8_array_slice_equals_u8_array::<12, 1, {0, 7}>` witnesses
// on `[0..1)` + `[7..8)`, one six-slot `assert_u8_array_slice_is_
// scalar_replica::<12, 1, 7>` witness on `[1..7)`, one four-slot
// `assert_u8_array_slice_equals_u8_array::<12, 4, 8>` witness on
// `[8..12)`). The (u8) row's `[1..7)` slice collapses to a SCALAR
// replica (all six atomic-payload shapes share the outer-`Sexp`
// `Atom` marker byte `1u8`); the (str) row's `[1..7)` slice preserves
// all six SLOTS individually (each atomic variant carries a DISTINCT
// diagnostic label byte-string). The (str) row's stronger information
// content at the `[1..7)` slice is precisely why the (str) row picks
// up the FULL slice-equals-array shape at ALL FOUR slices (not the
// SCALAR-REPLICA sibling at the interior slice).
//
// The FOUR pinned pairs — all on the shared `&'static str` element-
// type and on the shared parent `[&'static str; 12]` outer container
// `SexpShape::LABELS`:
//   1. `SexpShape::LABELS[0..1)   == [StructuralKind::NIL_LABEL]`
//      (singleton left-endpoint slot, structural-residual NIL role)
//   2. `SexpShape::LABELS[1..7)   == AtomKind::LABELS`
//      (six-slot atomic-payload middle slice — the six atomic-kind
//      labels in CANONICAL variant-declaration order)
//   3. `SexpShape::LABELS[7..8)   == [StructuralKind::LIST_LABEL]`
//      (singleton mirror-endpoint slot at the atomic-collapse right
//      endpoint, structural-residual LIST role)
//   4. `SexpShape::LABELS[8..12)  == QuoteForm::LABELS`
//      (four-slot quote-family tail — the four quote-family labels in
//      CANONICAL variant-declaration order)
//
// The four disjoint slice ranges `[0..1) ∪ [1..7) ∪ [7..8) ∪ [8..12)`
// exhaust the twelve-slot outer container's position space —
// `1 + 6 + 1 + 4 = 12`. Composed with the pre-existing pairwise-
// distinctness witness on the parent array, the FOUR positional
// witnesses jointly close the POSITIONAL DECOMPOSITION theorem
//   `SexpShape::LABELS == [NIL] ++ AtomKind::LABELS ++ [LIST] ++
//    QuoteForm::LABELS`
// as a rustc-time proof obligation, strictly stronger than the SET-
// level disjoint-union theorem the seven sibling witnesses above
// close. A regression that reordered ANY of the twelve slots in the
// outer array's initializer fails HERE at `cargo check` BEFORE any
// test scheduler runs.
//
// The two singleton pairs use INLINE `[&'static str; 1]` singleton
// arrays rather than `&StructuralKind::LABELS[0..1]` slice syntax
// because the helper's signature takes `&[&'static str; M]` (a const-
// generic array reference, arity-known at rustc time) rather than
// `&[&'static str]` (a slice type with runtime-length). The inline
// arrays project the two per-role `pub const *_LABEL` bytes directly
// — a regression that renamed one of the two aliases fails at the
// alias's declaration site FIRST (a missing symbol referent), which
// routes to a distinct diagnostic axis rather than to the witness's
// STR-SLICE-EQUALS-ARRAY-VIOLATION panic.
const _: () = crate::ast::assert_str_array_slice_equals_str_array::<12, 1, 0>(
    &SexpShape::LABELS,
    &[StructuralKind::NIL_LABEL],
);
const _: () = crate::ast::assert_str_array_slice_equals_str_array::<12, 6, 1>(
    &SexpShape::LABELS,
    &crate::ast::AtomKind::LABELS,
);
const _: () = crate::ast::assert_str_array_slice_equals_str_array::<12, 1, 7>(
    &SexpShape::LABELS,
    &[StructuralKind::LIST_LABEL],
);
const _: () = crate::ast::assert_str_array_slice_equals_str_array::<12, 4, 8>(
    &SexpShape::LABELS,
    &crate::ast::QuoteForm::LABELS,
);

// Compile-time SUBSET-embedding witnesses closing the `[&'static str;
// N]` STR row of the (UnquoteForm ⊂ QuoteForm) 2-of-4 subset-carve
// axis on the substrate's `str`-side vocabulary triple. Pre-lift the
// three subset relations lived per-role at the SCALAR alias sites on
// this module (`UnquoteForm::UNQUOTE_MARKER = crate::ast::QuoteForm::
// UNQUOTE_PREFIX`, `UnquoteForm::SPLICE_MARKER = crate::ast::QuoteForm::
// UNQUOTE_SPLICE_PREFIX`, `UnquoteForm::UNQUOTE_LABEL = crate::ast::
// QuoteForm::UNQUOTE_LABEL`, `UnquoteForm::SPLICE_LABEL = crate::ast::
// QuoteForm::UNQUOTE_SPLICE_LABEL`, `UnquoteForm::UNQUOTE_IAC_FORGE_
// TAG = crate::ast::QuoteForm::UNQUOTE_IAC_FORGE_TAG`, `UnquoteForm::
// SPLICE_IAC_FORGE_TAG = crate::ast::QuoteForm::UNQUOTE_SPLICE_IAC_
// FORGE_TAG`) plus a runtime cross-check that iterated each subset
// array and matched against the parent superset's array. The ARRAY-
// LEVEL subset embedding of the three sibling vocabularies onto their
// respective four-arm supersets was NOT bound at rustc const-eval time
// — a regression that silently re-inlined the subset array with a
// fresh literal drifted OUT of the alias-composition (e.g.
// `UnquoteForm::LABELS: [&'static str; 2] = ["unquote", "splice"]`
// with the second entry spelling `"splice"` instead of the aliased
// `"unquote-splice"`) would still pass INJECTIVITY (the array remains
// pairwise-distinct) AND still pass every DISJOINTNESS witness above
// (the array's shared vocabulary with `AtomKind::LABELS` /
// `StructuralKind::LABELS` doesn't gain a member) BUT would silently
// break the `UnquoteForm::to_quote_form()` composition law consumers
// route through — every `UnquoteForm::LABELS[i]` would fail its
// composition round-trip through the parent superset's label
// projection at runtime rather than at rustc time.
//
// The three pinned pairs are (all under the shared `&'static str`
// element-type):
//   1. `UnquoteForm::LABELS`         ⊂ `crate::ast::QuoteForm::LABELS`
//      (2-in-4 arms — the two substitution-subset LABELS embed into
//      the four-arm quote-family LABELS' vocabulary).
//   2. `UnquoteForm::MARKERS`        ⊂ `crate::ast::QuoteForm::PREFIXES`
//      (2-in-4 arms — the two substitution-subset reader-marker
//      prefixes embed into the four-arm quote-family reader-prefix
//      vocabulary).
//   3. `UnquoteForm::IAC_FORGE_TAGS` ⊂ `crate::ast::QuoteForm::IAC_FORGE_TAGS`
//      (2-in-4 arms — the two substitution-subset iac-forge canonical-
//      form tag bytes embed into the four-arm quote-family iac-forge
//      canonical-form tag vocabulary).
//
// Sibling to the pre-existing u8-row `assert_u8_array_within_u8_
// finite_set::<2, 4>(&UnquoteForm::HASH_DISCRIMINATORS,
// &QuoteForm::HASH_DISCRIMINATORS)` witness at `ast.rs`: together
// the u8 + str rows close the (element-type × vocabulary-axis) 2×3 =
// 6-corner face on the (UnquoteForm ⊂ QuoteForm) 2-of-4 subset-carve
// column at compile time. A future fourth vocabulary axis (e.g. a
// hypothetical `UnquoteForm::LEADS ⊂ QuoteForm::LEADS` on the
// `[char; N]` element-type row) picks up ONE new `const _:` witness
// through `assert_char_array_within_char_finite_set` with the same
// posture — the 3-vocabulary str row extends mechanically to a fourth
// (element-type × vocabulary-axis) column.
//
// Composition law with the sibling u8-row witness: for every `i ∈
// [0, 2)`, all four projections stay in lockstep — `UnquoteForm::
// LABELS[i] == QuoteForm::UNQUOTE_LABEL` or `QuoteForm::UNQUOTE_
// SPLICE_LABEL` (at some `j ∈ [0, 4)`), and similarly for MARKERS
// through PREFIXES, IAC_FORGE_TAGS through IAC_FORGE_TAGS, and (via
// the pre-existing u8 witness) HASH_DISCRIMINATORS through HASH_
// DISCRIMINATORS. The FOUR per-axis subset-embedding witnesses
// jointly enforce the (UnquoteForm ⊂ QuoteForm) 2-of-4 subset-carve
// on every vocabulary axis simultaneously; any single-axis regression
// (a drifted marker byte, a drifted label spelling, a drifted iac-
// forge tag, a drifted cache-key byte) fails cargo check on ONE of
// the four witnesses BEFORE it reaches the runtime cross-check on
// `unquote_form_v_marker_aliases_quote_form_v_prefix_bytes` /
// `unquote_form_v_label_aliases_quote_form_v_label_bytes` /
// `unquote_form_v_iac_forge_tag_aliases_quote_form_v_iac_forge_tag_
// bytes`.
const _: () = crate::ast::assert_str_array_within_str_finite_set::<2, 4>(
    &UnquoteForm::LABELS,
    &crate::ast::QuoteForm::LABELS,
);
const _: () = crate::ast::assert_str_array_within_str_finite_set::<2, 4>(
    &UnquoteForm::MARKERS,
    &crate::ast::QuoteForm::PREFIXES,
);
const _: () = crate::ast::assert_str_array_within_str_finite_set::<2, 4>(
    &UnquoteForm::IAC_FORGE_TAGS,
    &crate::ast::QuoteForm::IAC_FORGE_TAGS,
);

// Compile-time SLICE-EQUALS-ARRAY witnesses tightening the (UnquoteForm ⊂
// QuoteForm) 2-of-4 subset-carve from set-level SUBSET to positionwise
// SLICE-EQUALS at a specific contiguous START offset on the SAME three
// `[&'static str; N]` sub-vocabulary → superset pairs the SUBSET witnesses
// above cover. Pre-lift, the sub-carving's positional relationship to the
// superset was pinned indirectly: (a) each sub-array's INJECTIVITY via the
// three `assert_str_array_pairwise_distinct` witnesses at the top of this
// module, (b) each sub-array's SET-EMBEDDING via the three SUBSET witnesses
// immediately above, (c) each per-role scalar (`UnquoteForm::UNQUOTE_MARKER =
// QuoteForm::UNQUOTE_PREFIX`, etc.) via alias equality at rustc time. What
// NEITHER (a) + (b) NOR (c) alone pinned was the ARRAY-LEVEL POSITIONWISE
// composition — that `UnquoteForm::MARKERS == QuoteForm::PREFIXES[2..4]`
// element-for-element. A regression that silently swapped the two per-role
// slot bindings in the sub-array initializer (e.g. `UnquoteForm::MARKERS:
// [&'static str; 2] = [Self::SPLICE_MARKER, Self::UNQUOTE_MARKER]`) would
// still pass INJECTIVITY (both aliases distinct), still pass SET-EMBEDDING
// (both aliases still appear in `QuoteForm::PREFIXES`), still pass per-role
// scalar equality (each alias still binds to the same `QuoteForm::*_PREFIX`
// source constant), BUT would silently mis-align every consumer that reads
// the sub-array by slot ordinal (`UnquoteForm::MARKERS[0]` semantically
// naming the two-quote-family-arms-in-declaration-order for e.g. a per-slot
// error diagnostic that mirrors `QuoteForm`'s slot ordinal 2 vs 3). The
// SLICE-EQUALS witness pins the sub-carving's slot-ordering to a SPECIFIC
// contiguous slice of the superset (`[2..4)` — the two UnquoteForm-family
// arms sit at the tail of QuoteForm's four-arm declaration listing,
// after the two non-substitution `Quote` + `Quasiquote` arms). Both drifts
// the SUBSET witness stayed silent on (sub-carving reorder AND SUPERSET
// reorder that leaves the sub-array's two aliases still present but at
// different positions) fail HERE at rustc time with the
// `STR-SLICE-EQUALS-ARRAY-VIOLATION` axis panic naming the drifted position.
//
// Sibling posture to the four-witness `SexpShape::LABELS` (12) SLICE-EQUALS
// cluster at lines 331..=346 above (the outer twelve-arm SexpShape
// vocabulary bound as the SEGMENTED CONCATENATION `[NIL_LABEL] ++
// AtomKind::LABELS ++ [LIST_LABEL] ++ QuoteForm::LABELS` at rustc time via
// four `assert_str_array_slice_equals_str_array` witnesses on the four
// slot segments). Together the seven witnesses close the SLICE-EQUALS
// column on BOTH sub-carving directions: those four pin sub-vocabularies
// AS SEGMENTS OF the twelve-arm SexpShape outer array (the outer superset
// pinned by-segment against its sub-carvings); these three pin
// UnquoteForm sub-arrays AS SLICES OF the QuoteForm superset (the outer
// superset pinned as the position-source for the sub-carvings). The
// (SexpShape ⊃ {AtomKind, QuoteForm, StructuralKind}) SUPERSET-AS-SEGMENTS
// posture and the (UnquoteForm ⊂ QuoteForm) SUB-AS-SLICE posture are the
// two orientations of the same positionwise-composition theorem the
// SLICE-EQUALS helper carries.
const _: () = crate::ast::assert_str_array_slice_equals_str_array::<4, 2, 2>(
    &crate::ast::QuoteForm::LABELS,
    &UnquoteForm::LABELS,
);
const _: () = crate::ast::assert_str_array_slice_equals_str_array::<4, 2, 2>(
    &crate::ast::QuoteForm::PREFIXES,
    &UnquoteForm::MARKERS,
);
const _: () = crate::ast::assert_str_array_slice_equals_str_array::<4, 2, 2>(
    &crate::ast::QuoteForm::IAC_FORGE_TAGS,
    &UnquoteForm::IAC_FORGE_TAGS,
);

// Compile-time STR-DISJOINTNESS witnesses closing the ARRAY-LEVEL
// vocabulary-disjointness corner of the STATIC ⊕ DYNAMIC partition
// idiom on the substrate's TWO peer diagnostic algebras
// (`TemplateInvariantKind` — the bytecode-runtime invariant surface;
// `OptionalParamMalformedReason` — the `&optional` parser rejection
// surface). Each algebra carries the SAME closed-set carving idiom
// documented on `Self::DYNAMIC_DESCRIPTORS`'s docstring: "every closed-
// set outer algebra the substrate carries now pins BOTH its STATIC-
// subset canonical-bytes array AND its DYNAMIC-subset per-role-slot
// array at ONE `pub const` per axis" — TemplateInvariantKind at
// 2 ⊕ 2 asymmetric widths, OptionalParamMalformedReason at 3 ⊕ 1
// asymmetric widths. Pre-lift, EACH array's INTRA-array pairwise-
// distinctness bound at compile time via the four `assert_str_array_
// pairwise_distinct` witnesses at the top of this module — but the
// CROSS-array (STATIC ∩ DYNAMIC = ∅) vocabulary-disjointness clause
// lived ONLY as an emergent property of the two carvings' semantic
// contract (STATIC arms bind FULL diagnostic bytes; DYNAMIC arms bind
// only the noun-slot bytes that a shared `format!("… {descriptor} …")`
// template interpolates). Post-lift the ARRAY-LEVEL disjointness of
// the STATIC ⊕ DYNAMIC 2-of-2 face binds at rustc time via ONE `const _`
// line per algebra. A regression that silently drifts a DYNAMIC
// descriptor into a STATIC message/label byte (e.g. renames
// `TemplateInvariantKind::SUBST_BAD_INDEX_DESCRIPTOR` from `"param"`
// into `"compiled template produced no value"`, colliding with
// `TemplateInvariantKind::FINAL_NO_VALUE_MESSAGE`; renames
// `OptionalParamMalformedReason::EXTRA_ELEMENTS_DESCRIPTOR` from
// `"elements"` into `"empty list"`, colliding with
// `OptionalParamMalformedReason::EMPTY_LIST_LABEL`) fails at
// `cargo check` BEFORE any test scheduler runs. The invariant is
// load-bearing at three consumer layers documented on the two
// algebras' DYNAMIC_DESCRIPTORS docstrings: (i) `tatara-check`
// coverage assertions grep the STATIC arms' full label bytes and the
// DYNAMIC arms' descriptor noun bytes as DISJOINT vocabularies, so a
// collision would silently mis-classify one carving's diagnostic as
// the other's; (ii) Sekiban audit-trail metrics keyed on the STATIC-
// subset FULL message OR the DYNAMIC-subset noun-descriptor treat
// the two byte-spaces as disjoint metric-label sub-vocabularies; (iii)
// LSP quick-fix vocabularies rendered from the DYNAMIC-arm descriptor
// slot MUST NOT collide with the STATIC-arm full-label vocabulary
// (else a quick-fix keyed on the descriptor would fire on a STATIC
// arm whose full label happens to string-equal the descriptor). The
// two witnesses close the STR-DISJOINTNESS column on the (algebra ×
// carving-pair) face at ONE `const _` line per algebra; adding a
// hypothetical fifth per-algebra rejection reason on either the
// STATIC or DYNAMIC arm extends only the respective array (with
// rustc's forced-arity `[&'static str; N]` gate re-firing the
// disjointness sweep against the extended array in lockstep).
// Sibling to the FIVE substrate-pinned `assert_str_arrays_disjoint`
// witnesses on the (SexpShape sub-vocabulary × sub-vocabulary) triple
// (three at the (`AtomKind`, `QuoteForm`, `StructuralKind`) triple
// hosted across `ast.rs` and `error.rs`) plus the (UnquoteForm ⊂
// QuoteForm) subset-embedding face — those witnesses close the DISJOINT
// UNION theorem on the substrate's twelve-arm outer-shape LABELS
// vocabulary; these witnesses close the STATIC ⊕ DYNAMIC carving
// theorem on the substrate's TWO peer diagnostic algebras.
//
// The two pinned pairs are (all under the shared `&'static str`
// element-type):
//   1. `TemplateInvariantKind::STATIC_MESSAGES` ∩
//      `TemplateInvariantKind::DYNAMIC_DESCRIPTORS` = ∅
//      (2-arm STATIC subset carrying the full `"compiled template:
//      EndList with empty stack"` / `"compiled template produced no
//      value"` messages vs. 2-arm DYNAMIC subset carrying the `"param"`
//      / `"splice"` noun slots — no byte shared).
//   2. `OptionalParamMalformedReason::STATIC_LABELS` ∩
//      `OptionalParamMalformedReason::DYNAMIC_DESCRIPTORS` = ∅
//      (3-arm STATIC subset carrying the full `"empty list"` /
//      `"missing default"` / `"name not a symbol"` labels vs. 1-arm
//      DYNAMIC subset carrying the `"elements"` noun slot — no byte
//      shared).
const _: () = crate::ast::assert_str_arrays_disjoint::<2, 2>(
    &TemplateInvariantKind::STATIC_MESSAGES,
    &TemplateInvariantKind::DYNAMIC_DESCRIPTORS,
);
const _: () = crate::ast::assert_str_arrays_disjoint::<3, 1>(
    &OptionalParamMalformedReason::STATIC_LABELS,
    &OptionalParamMalformedReason::DYNAMIC_DESCRIPTORS,
);

// Compile-time STR-BLOCK-CONSTANCY witness closing the ARRAY-LEVEL
// MANY-TO-ONE variant → canonical-projection corner on the substrate's
// TYPED-VARIANT × CANONICAL-PROJECTION MANY-TO-ONE surface at
// `CompilerSpecIoStage::OPERATIONS`. Where every OTHER family-wide
// `[&'static str; N]` array on the substrate carries a BIJECTIVE
// per-index projection (`AtomKind::LABELS[i]` is bijective with
// `AtomKind::ALL[i].label()`; `QuoteForm::LABELS[i]` is bijective with
// `QuoteForm::ALL[i].label()`; `CompilerSpecIoStage::LABELS[i]` is
// bijective with `CompilerSpecIoStage::ALL[i].label()`) and binds
// INJECTIVITY through `assert_str_array_pairwise_distinct` at the
// module top, `CompilerSpecIoStage::OPERATIONS` is the ONE substrate
// array whose per-index projection is INTENTIONALLY MANY-TO-ONE —
// the four `CompilerSpecIoStage::ALL[i].operation()` per-variant
// projections collapse onto EXACTLY TWO canonical operation-label
// bytes (both `Realize…` variants share `"realize_to_disk"`; both
// `Load…` variants share `"load_from_disk"`) yielding the
// `[REALIZE_TO_DISK, REALIZE_TO_DISK, LOAD_FROM_DISK, LOAD_FROM_DISK]`
// 2-of-2-to-2 block-constant array literal at the declaration site.
// The pre-existing module-top comment (adjacent to the family-wide
// `assert_str_array_pairwise_distinct` witnesses) documents the
// EXCLUSION from injectivity as intentional AND names the intended
// axis: "variant-index alignment with `CompilerSpecIoStage::ALL`, not
// injectivity — different theorem, different helper". This witness
// IS the different helper the comment named — the ARRAY-LEVEL block-
// constant structure `arr = [head; K] ++ [tail; N - K]` at
// `(N, K) = (4, 2)`, `(head, tail) = (REALIZE_TO_DISK_OPERATION,
// LOAD_FROM_DISK_OPERATION)`. Pre-lift the block-constant structure
// bound only at runtime through `compiler_spec_io_stage_operations_
// align_with_all_by_index` (positional projection through
// `stage.operation()`) plus `compiler_spec_io_stage_operations_
// partition_all_two_ways` (multiplicity counts of the two operation
// labels); post-lift the ARRAY-LEVEL block-constancy binds at rustc
// time via ONE `const _` line. A regression that silently flip-
// flopped the projection (reorder `OPERATIONS` to `[REALIZE, LOAD,
// REALIZE, LOAD]`; drift a slot to a distinct third operation label;
// collapse to a single-block `[REALIZE, REALIZE, REALIZE, REALIZE]`)
// fails at `cargo check` BEFORE any test scheduler runs. The
// invariant is load-bearing at THREE consumer layers documented on
// `Self::OPERATIONS`'s docstring: (i) an LSP / REPL completion
// provider surfacing every legal operation label in an `operation=`
// metrics query bar (the deduped block-labels IS the ONE typed
// coverage sweep); (ii) `tatara-check` coverage assertions verifying
// every workspace `.lisp` file's `CompilerSpec` rejection classifies
// to some entry of `Self::OPERATIONS`; (iii) Sekiban audit-trail
// metrics jointly labeled by `Self::operation` × `Self::label` whose
// `operation=` label set IS the deduped `Self::OPERATIONS` (e.g.
// `tatara_lisp_compiler_spec_io_total{operation="realize_to_disk",
// stage="serialize"}`) — all three layers rely on the block-constant
// partition holding at ONE cargo-check-time site. Adding a hypothetical
// fifth variant (`LoadFromStrDeserialize` once an in-memory
// `load_from_str` lands, `RealizeToDiskAtomicReplace` if the realize
// path grows a crash-safe-rename stage) extends `Self::ALL` ONCE +
// `Self::operation` ONCE + `Self::OPERATIONS` ONCE — the block-
// constant witness re-fires against the extended arity through the
// rustc-forced `[&'static str; N]` gate (with the appropriate new
// `(N, K)` const-generic reflecting the new 2-of-2-to-3 or 2-of-3-to-2
// partition) so the extension picks up the block-constancy contract
// mechanically. Sibling to the FOURTEEN family-wide
// `assert_str_array_pairwise_distinct` witnesses at the module top on
// the (contract-shape ∈ {INJECTIVITY}) column of the (`&'static str`)
// row — this witness closes the (contract-shape ∈ {MANY-TO-ONE-BLOCK-
// CONSTANCY}) corner peer to the (INJECTIVITY) column at ONE `const
// _` line, closing the (INJECTIVITY, MANY-TO-ONE-BLOCK-CONSTANCY)
// 2-corner face on the (`&'static str`) row on the substrate's
// per-index projection surface.
const _: () = crate::ast::assert_str_array_is_concatenation_of_two_scalar_replicas::<4, 2>(
    &CompilerSpecIoStage::OPERATIONS,
    CompilerSpecIoStage::REALIZE_TO_DISK_OPERATION,
    CompilerSpecIoStage::LOAD_FROM_DISK_OPERATION,
);

// Compile-time per-position ORDER witnesses closing the (`&'static
// str`)-row FULL-ARRAY LITERAL column across the FIVE remaining scalar-
// composed `[&'static str; N]` label vocabularies in this module —
// `ExpectedKwargShape::LABELS` (7), `KwargPathKind::LABELS` (3),
// `MacroDefHead::KEYWORDS` (3), `CompilerSpecIoStage::LABELS` (4),
// `StructuralKind::LABELS` (2). Peer to ast.rs's FIVE-witness
// (str)-row cluster on `Atom::BOOL_LITERALS` (2), `AtomKind::LABELS`
// (6), and `QuoteForm::PREFIXES` / `LABELS` / `IAC_FORGE_TAGS`
// (4 each) at lines 1252..=1269 in that file, and to the pre-existing
// FOUR-witness `SexpShape::LABELS` (12) per-position cluster at lines
// 331..=346 above in this file — together the ten witnesses bind the
// (str)-row FULL-ARRAY per-position ORDER column across TEN family-
// wide `[&'static str; N]` label vocabularies on the substrate at
// rustc time.
//
// Each per-role scalar `pub const *_LABEL` / `*_KEYWORD` alias on the
// closed-set outer algebra binds AT rustc TIME to its CANONICAL
// literal-str value through the outer array's `[_; N]` initializer
// positional composition. Two failure axes survive the pre-lift
// `_pairwise_distinct` cluster at the module top that the post-lift
// LITERAL witnesses reject at rustc time:
//   1. Outer-array SLOT REORDER: a regression that swaps
//      `KwargPathKind::NAMED_LABEL` (`"named"`) and
//      `KwargPathKind::ITEM_LABEL` (`"item"`) in the outer
//      `KwargPathKind::LABELS` initializer preserves pairwise-
//      distinctness (both strs still distinct) but silently
//      misaligns every consumer indexing `LABELS[0]` for the canonical
//      NAMED-arm diagnostic dispatch. Analogous reorder-drifts on
//      `ExpectedKwargShape::LABELS` / `MacroDefHead::KEYWORDS` /
//      `CompilerSpecIoStage::LABELS` / `StructuralKind::LABELS`
//      survive the pairwise-distinctness witness the SAME way.
//   2. Per-role scalar VALUE DRIFT: a silent value-drift of a per-
//      role scalar (e.g. an operator-facing polish
//      `ExpectedKwargShape::LIST_OF_STRINGS_LABEL` from `"list of
//      strings"` to `"list<string>"`; a Racket-compat rename
//      `MacroDefHead::DEFMACRO_KEYWORD` from `"defmacro"` to
//      `"define-syntax"`; a shorter idiom migration
//      `CompilerSpecIoStage::REALIZE_TO_DISK_SERIALIZE_LABEL` from
//      `"serialize"` to `"ser"`) that flows through the composed
//      array without updating the outer array's literal image fails
//      HERE with the `STR-SLICE-EQUALS-ARRAY-VIOLATION` panic naming
//      the drifted position, where the pairwise-distinctness witness
//      stays silent because the drifted str remains distinct from
//      its peers.
//
// Future extensions that benefit: adding a hypothetical eighth
// expected-shape variant (a distinct `Float` once `extract_float`
// stops accepting integers, a `Symbol`, or a parameterized
// `ListOfInts`) extends `ExpectedKwargShape::ALL` AND
// `ExpectedKwargShape::LABELS` AND requires widening this witness's
// `<7, 7, 0>` const-generic turbofish AND appending the new label
// literal to the RHS listing in lockstep — rustc's forced-arity
// check on `[&'static str; N]` fails compilation if either side
// drifts out of lockstep. Analogous single-variant extensions on the
// four sibling algebras (`KwargPathKind`, `MacroDefHead`,
// `CompilerSpecIoStage`, `StructuralKind`) propagate through their
// respective `<N, N, 0>` witnesses under the same forced-arity
// gate.
const _: () = crate::ast::assert_str_array_slice_equals_str_array::<7, 7, 0>(
    &ExpectedKwargShape::LABELS,
    &[
        "keyword",
        "string",
        "int",
        "number",
        "bool",
        "list",
        "list of strings",
    ],
);
const _: () = crate::ast::assert_str_array_slice_equals_str_array::<3, 3, 0>(
    &KwargPathKind::LABELS,
    &["named", "item", "slot"],
);
const _: () = crate::ast::assert_str_array_slice_equals_str_array::<3, 3, 0>(
    &MacroDefHead::KEYWORDS,
    &["defmacro", "defpoint-template", "defcheck"],
);
const _: () = crate::ast::assert_str_array_slice_equals_str_array::<4, 4, 0>(
    &CompilerSpecIoStage::LABELS,
    &["serialize", "write", "read", "deserialize"],
);
const _: () = crate::ast::assert_str_array_slice_equals_str_array::<2, 2, 0>(
    &StructuralKind::LABELS,
    &["nil", "list"],
);

#[derive(Debug, Error)]
pub enum LispError {
    #[error("unexpected character {0:?} at position {1}")]
    UnexpectedChar(char, usize),
    /// Unterminated string literal. The span runs from the opening `"`
    /// to end-of-input — the whole run the tokenizer consumed looking
    /// for a closer — so the rendered diagnostic underlines the
    /// unterminated literal rather than pointing at its opening quote.
    #[error("unterminated string literal at position {}", .0.start)]
    UnterminatedString(Span),
    /// A `)` with no matching `(`. The span is the offending token — one
    /// byte — so this renders as a single caret, same as pre-lift.
    #[error("unmatched closing paren at position {}", .span.start)]
    UnmatchedParen { span: Span },
    /// A `(` the reader never found a closer for. The span runs from the
    /// unclosed `(` to the END OF THE LAST TOKEN read, i.e. the extent of
    /// the partial form — NOT to `src.len()`, which would drag trailing
    /// whitespace and comments under the underline. This is the variant
    /// the `Span` lift buys the most: pre-lift it named the `(` byte and
    /// rendered one caret, post-lift it underlines the form that was left
    /// open.
    #[error("unmatched opening paren at position {}", .span.start)]
    UnmatchedOpenParen { span: Span },
    /// Input ran out where a datum was required. A zero-width span AT the
    /// end offset — there is no text to underline, so `caret_run`'s
    /// clamp-up-to-one renders the single caret one column past the last
    /// visible char, exactly as pre-lift.
    #[error("unexpected end of input at position {}", .span.start)]
    Eof { span: Span },
    #[error("invalid number literal {0:?}")]
    InvalidNumber(String),
    #[error("unknown symbol: {0}")]
    UnknownSymbol(String),
    #[error("type error: expected {expected}, got {got}")]
    Type { expected: &'static str, got: String },
    #[error("compile error in {form}: {message}")]
    Compile { form: String, message: String },
    /// Structured type mismatch — both sides are first-class fields, not
    /// embedded substrings of `message`. Rendered as `"compile error in
    /// {form}: expected {expected}, got {got}"` so the user-facing string
    /// matches the legacy `Compile`-shaped diagnostic byte-for-byte; the
    /// gain is structural — authoring tools (REPL, LSP, `tatara-check`)
    /// pattern-match on the variant and bind directly to `expected` /
    /// `got` instead of substring-parsing the rendered message.
    ///
    /// `form` is the typed closed-set `KwargPath` enum so consumers
    /// pattern-match on path-shape identity (`KwargPath::Item { .. }`,
    /// `KwargPath::Slot(_)`, `KwargPath::Named(_)`) directly rather than
    /// substring-matching the rendered prefix. The Display projection
    /// flows through `KwargPath::Display`, so the user-facing
    /// `"compile error in {form}: …"` rendering matches the legacy
    /// `String`-shaped diagnostic byte-for-byte.
    ///
    /// `expected` is the typed closed-set `ExpectedKwargShape` enum —
    /// the seven reachable expected-shape labels the typed-entry kwarg
    /// gate emits (`Keyword` ⊎ `String` ⊎ `Int` ⊎ `Number` ⊎ `Bool` ⊎
    /// `List` ⊎ `ListOfStrings`) encoded as a TYPE so a typo in any
    /// label literal can never drift into the diagnostic at runtime;
    /// consumers (REPL, LSP, `tatara-check`) pattern-match on
    /// `ExpectedKwargShape::Number` etc. directly instead of
    /// substring-matching `expected == "number"`. Same posture as
    /// `LispError::Defmacro*.head: MacroDefHead`,
    /// `LispError::UnboundTemplateVar.prefix: UnquoteForm`,
    /// `LispError::CompilerSpecIo.stage: CompilerSpecIoStage`,
    /// `LispError::TemplateInvariant.kind: TemplateInvariantKind`, and
    /// `LispError::TypeMismatch.form: KwargPath`: the closed set
    /// becomes a TYPE rather than a `&'static str` projection at the
    /// helper boundary. The Display projection flows through
    /// `ExpectedKwargShape::Display`, so the user-facing
    /// `"... expected {expected}, ..."` rendering matches the legacy
    /// `&'static str`-shaped diagnostic byte-for-byte.
    ///
    /// `got` is the typed closed-set `SexpShape` enum — the twelve
    /// reachable Sexp outermost shapes (`Nil` ⊎ `Symbol` ⊎ `Keyword` ⊎
    /// `String` ⊎ `Int` ⊎ `Float` ⊎ `Bool` ⊎ `List` ⊎ `Quote` ⊎
    /// `Quasiquote` ⊎ `Unquote` ⊎ `UnquoteSplice`) encoded as variant
    /// identities so the SexpShape that the typed-entry gate observed
    /// is load-bearing data in the type system. Consumers (REPL, LSP,
    /// `tatara-check`) pattern-match on `SexpShape::Int` etc. directly
    /// instead of substring-matching `got == "int"`. Same posture as
    /// `form: KwargPath` and `expected: ExpectedKwargShape`: after this
    /// lift the TypeMismatch variant's identity is fully closed-set
    /// typed in ALL THREE of its slots — no `&'static str` projection
    /// at any helper boundary, every reachable identity encoded as a
    /// variant of a typed enum. The Display projection flows through
    /// `SexpShape::Display` (which delegates to `SexpShape::label()`),
    /// so the user-facing `"... got {got}"` rendering matches the
    /// legacy `&'static str`-shaped diagnostic byte-for-byte. When a
    /// future run gives `Sexp` source spans, `pos: Option<usize>`
    /// lands here in ONE place and every type-mismatch site picks up
    /// positional rendering via `crate::diagnostic::format_diagnostic`
    /// mechanically.
    #[error("compile error in {form}: expected {expected}, got {got}")]
    TypeMismatch {
        form: KwargPath,
        expected: ExpectedKwargShape,
        got: SexpShape,
    },
    /// Structural head-mismatch — the `(head ...)` of a top-level form
    /// didn't match `T::KEYWORD`. Both sides are first-class fields, not
    /// embedded substrings of `message`. Rendered as `"compile error in
    /// {keyword}: expected ({keyword} ...), got ({got} ...)"` so the
    /// user-facing string matches the legacy `Compile`-shaped diagnostic
    /// byte-for-byte; the gain is structural — authoring tools (REPL,
    /// LSP, `tatara-check`) pattern-match on the variant and bind
    /// directly to `keyword` / `got` instead of substring-parsing the
    /// rendered message.
    ///
    /// `keyword` is `&'static str` because it always comes from
    /// `T::KEYWORD`, a compile-time literal; `got` is `String` because
    /// it is an arbitrary symbol from the source. When a future run
    /// gives `Sexp` source spans, `pos: Option<usize>` lands here in
    /// ONE place and every head-mismatch site picks up positional
    /// rendering via `crate::diagnostic::format_diagnostic`
    /// mechanically.
    #[error("compile error in {keyword}: expected ({keyword} ...), got ({got} ...)")]
    HeadMismatch { keyword: &'static str, got: String },
    #[error("unknown {category}: {value}")]
    Unknown {
        category: &'static str,
        value: String,
    },
    #[error("missing required field: {0}")]
    Missing(&'static str),
    /// A kwargs list of odd length: the last element has no partner. The
    /// `dangling` field holds the offending element's `Sexp::Display`
    /// projection — `:query` for a keyword whose value got lost, or the
    /// literal form of a stray non-keyword. Naming both halves of the
    /// failure (the failure mode AND the offending element) is the
    /// typed-entry gate's structural-completeness floor (THEORY.md §V.1):
    /// without it the operator must re-read the source to find what
    /// actually misfired.
    #[error("odd keyword arguments: dangling element `{dangling}`")]
    OddKwargs { dangling: String },
    /// An unquote (`,name`) or unquote-splice (`,@name`) in a macro template
    /// body referenced a name that wasn't bound by the macro's params (during
    /// `compile_template`) or wasn't available in the substitution scope
    /// (during `substitute`). `prefix` is the syntactic marker — `","` for
    /// unquote, `",@"` for splice — so the rendered diagnostic preserves the
    /// form exactly as the author wrote it. `hint` is `Some(name)` when the
    /// substrate found a near-miss against the available bound names within
    /// the bounded edit distance (see `crate::domain::suggest`); `None`
    /// otherwise — a wrong hint is worse than no hint, so the slot stays
    /// empty unless the substrate is confident.
    ///
    /// `prefix` is `UnquoteForm` — the closed-set typed enum whose two
    /// variants are EXACTLY the two reachable syntactic markers
    /// (`Unquote` ⊎ `Splice`). Encoding the closed set as a TYPE makes the
    /// constraint that ONLY 2 marker identities are reachable load-bearing
    /// in the type system — a third pseudo-marker can never drift into the
    /// diagnostic at runtime; consumers (REPL, LSP, `tatara-check`)
    /// pattern-match on `UnquoteForm::Splice` etc. directly instead of
    /// substring-matching `prefix == ",@"`. Same posture as
    /// `LispError::Defmacro*.head: MacroDefHead`,
    /// `LispError::CompilerSpecIo.stage: CompilerSpecIoStage`, and
    /// `LispError::TemplateInvariant.kind: TemplateInvariantKind`: the
    /// closed set becomes a TYPE rather than a `&'static str` projection
    /// at the helper boundary. `name` and `hint` are `String` because
    /// they come from arbitrary source / the live bindings set. When a
    /// future run gives `Sexp` source spans, `pos: Option<usize>` lands
    /// here in ONE place and every unbound-template-var site picks up
    /// positional rendering via `crate::diagnostic::format_diagnostic`
    /// mechanically.
    ///
    /// Display matches the legacy `Compile`-shaped diagnostic byte-for-byte
    /// when `hint` is `None` — `"compile error in {prefix}{name}: unbound"`
    /// — so existing consumer assertions that pattern-match on the message
    /// substring keep passing. With a hint, the suffix `"; did you mean
    /// {prefix}{hint}?"` is appended; the prefix is preserved in the hint so
    /// the operator can copy-paste the suggestion verbatim.
    #[error(
        "compile error in {prefix}{name}: unbound{}",
        unbound_hint_suffix(*prefix, hint.as_deref())
    )]
    UnboundTemplateVar {
        prefix: UnquoteForm,
        name: String,
        hint: Option<String>,
    },
    /// A kwargs slice contained the same `:key` twice. The offending key is
    /// carried as a structural field — not embedded in a free-form message —
    /// so authoring surfaces (REPL, LSP, `tatara-check`) pattern-match on
    /// the variant and bind to `key` directly instead of substring-parsing
    /// the rendered diagnostic. Same posture as the `OddKwargs { dangling }`
    /// sibling: every distinct `parse_kwargs` failure mode (odd length,
    /// not-a-keyword-at-position, duplicate key) is now a structural variant
    /// of `LispError`, not a `Compile`-shaped substring.
    ///
    /// `key` is `String` because it comes from arbitrary source. Display
    /// renders `"compile error in :{key}: duplicate keyword"` byte-for-byte
    /// equivalent to the legacy `Compile { form: kwarg_form(key), message:
    /// "duplicate keyword" }` shape, so existing consumer assertions
    /// (`msg.contains(":name")`, `msg.contains("duplicate keyword")`) pass
    /// unchanged. When a future run gives `Sexp` source spans, `pos:
    /// Option<usize>` lands here in ONE place and every duplicate-kwarg
    /// site picks up positional rendering via
    /// `crate::diagnostic::format_diagnostic` mechanically.
    #[error("compile error in :{key}: duplicate keyword")]
    DuplicateKwarg { key: String },
    /// A required kwarg was absent from the kwargs slice. The offending key
    /// is carried as a structural field — not embedded in a free-form
    /// message — so authoring surfaces (REPL, LSP, `tatara-check`)
    /// pattern-match on the variant and bind to `key` directly instead of
    /// substring-parsing the rendered diagnostic. Same posture as
    /// `DuplicateKwarg { key }` and `OddKwargs { dangling }`: every
    /// distinct typed-entry kwarg failure mode is now a structural variant
    /// of `LispError`, not a `Compile`-shaped substring. Sibling of the
    /// pre-existing `Missing(&'static str)` variant — `MissingKwarg`
    /// covers the runtime-key path the kwargs extractors share, while
    /// `Missing` stays for compile-time-known names.
    ///
    /// `key` is `String` because it comes from the runtime kwargs lookup
    /// (each derive-generated extractor and every hand-written
    /// `TataraDomain` impl can pass an arbitrary key). Display renders
    /// `"compile error in :{key}: required but not provided"`
    /// byte-for-byte equivalent to the legacy `Compile { form:
    /// kwarg_form(key), message: "required but not provided" }` shape, so
    /// existing consumer assertions (`msg.contains(":threshold")`,
    /// `msg.contains("required")`) pass unchanged. When a future run gives
    /// `Sexp` source spans, `pos: Option<usize>` lands here in ONE place
    /// and every missing-kwarg site picks up positional rendering via
    /// `crate::diagnostic::format_diagnostic` mechanically.
    #[error("compile error in :{key}: required but not provided")]
    MissingKwarg { key: String },
    /// A kwargs slice contained a `:key` that isn't in the allowed-kwarg
    /// set for the surrounding `TataraDomain`. The offending key, the
    /// near-miss hint (if any), and the full allowed set are all carried
    /// as first-class fields — not embedded in a free-form message — so
    /// authoring surfaces (REPL, LSP, `tatara-check`) pattern-match on
    /// the variant and bind to `key` / `hint` / `allowed` directly
    /// instead of substring-parsing the rendered message. Same posture
    /// as the `OddKwargs { dangling }`, `DuplicateKwarg { key }`, and
    /// `MissingKwarg { key }` siblings: every distinct typed-entry
    /// kwarg-gate failure mode is now a structural variant of
    /// `LispError`, not a `Compile`-shaped substring.
    ///
    /// `key` is `String` because it comes from arbitrary source. `hint`
    /// is `Some(allowed_keyword)` when `crate::domain::suggest` ranks an
    /// allowed kwarg within the bounded edit distance; `None`
    /// otherwise — a wrong hint is worse than no hint, so the slot
    /// stays empty unless the substrate is confident. `allowed` is
    /// `Vec<String>` (sorted lexicographically by `unknown_kwarg`)
    /// because the variant owns its data — the derive-emitted
    /// `&'static [&'static str]` allowed-set crosses the structural
    /// boundary as owned `String`s so the diagnostic crosses thread
    /// boundaries cleanly and lives independent of the call frame.
    /// Display matches the legacy `Compile { form: kwarg_form(key),
    /// message: "unknown keyword (...)" }` rendering byte-for-byte
    /// (`"compile error in :{key}: unknown keyword (did you mean
    /// :{hint}?; allowed: :a, :b, :c)"` with a hint, `"compile error
    /// in :{key}: unknown keyword (allowed: :a, :b, :c)"` without),
    /// so existing consumer assertions
    /// (`msg.contains("unknown keyword")`,
    /// `msg.contains("did you mean :threshold?")`,
    /// `msg.contains("allowed: ")`) pass unchanged. When a future
    /// run gives `Sexp` source spans, `pos: Option<usize>` lands
    /// here in ONE place and every unknown-kwarg site picks up
    /// positional rendering via
    /// `crate::diagnostic::format_diagnostic` mechanically.
    #[error(
        "compile error in :{key}: unknown keyword{}",
        unknown_kwarg_suffix(hint.as_deref(), allowed)
    )]
    UnknownKwarg {
        key: String,
        hint: Option<String>,
        allowed: Vec<String>,
    },
    /// A registry-dispatched form `(<keyword> ...)` whose head symbol isn't in
    /// the global `TataraDomain` registry. The offending keyword, the
    /// near-miss hint (if any), and the full registered keyword set are all
    /// carried as first-class fields — not embedded in a free-form message —
    /// so authoring surfaces (REPL, LSP, `tatara-check`) pattern-match on the
    /// variant and bind to `keyword` / `hint` / `registered` directly instead
    /// of substring-parsing the rendered message. Same posture as the
    /// `UnknownKwarg { key, hint, allowed }` sibling: the kwarg-gate's
    /// unknown-allowed-set rejection and the registry-gate's
    /// unknown-registered-set rejection share ONE structural shape.
    ///
    /// `keyword` is `String` because it comes from arbitrary source (a
    /// top-level form's head symbol). `hint` is
    /// `Some(registered_keyword)` when `crate::domain::suggest_keyword`
    /// ranks a registered keyword within the bounded edit distance;
    /// `None` otherwise — a wrong hint is worse than no hint, so the slot
    /// stays empty unless the substrate is confident. `registered` is
    /// `Vec<String>` (sorted lexicographically by
    /// `unknown_domain_keyword`) because the variant owns its data — the
    /// registry's `&'static [&'static str]` keyword-set crosses the
    /// structural boundary as owned `String`s so the diagnostic crosses
    /// thread boundaries cleanly and lives independent of the call frame.
    /// Empty `registered` (no domains seeded) renders `(no domains
    /// registered)` so the operator sees the structural reason — the
    /// registry has no candidates at all — instead of a misleading empty
    /// "registered: " suffix. When a future run gives `Sexp` source
    /// spans, `pos: Option<usize>` lands here in ONE place and every
    /// unknown-domain-keyword site picks up positional rendering via
    /// `crate::diagnostic::format_diagnostic` mechanically.
    #[error(
        "unknown domain keyword: ({keyword} ...){}",
        unknown_domain_keyword_suffix(hint.as_deref(), registered)
    )]
    UnknownDomainKeyword {
        keyword: String,
        hint: Option<String>,
        registered: Vec<String>,
    },
    /// The slot inside a `Sexp::Unquote(_)` (`,X`) or
    /// `Sexp::UnquoteSplice(_)` (`,@X`) was not a symbol. The `prefix`
    /// field is the syntactic marker — `","` for unquote, `",@"` for
    /// splice — so the rendered diagnostic preserves the form exactly
    /// as the author wrote it. The `got` field is the offending inner's
    /// `Sexp::Display` projection so the operator sees both what was
    /// expected (a symbol — the only form a no-evaluator template can
    /// substitute) and what was actually written (the literal value —
    /// `(list 1 2)`, `5`, `:foo`, etc.). Naming both halves of the
    /// failure is the typed-entry gate's structural-completeness floor
    /// (THEORY.md §V.1).
    ///
    /// Sibling of `UnboundTemplateVar { prefix, name, hint }` for the
    /// same template-side typed-entry surface — that variant fires when
    /// the slot IS a symbol but the symbol isn't bound; this variant
    /// fires when the slot isn't a symbol at all. After this lift every
    /// distinct typed-entry template-gate failure mode binds to ONE
    /// structural variant of `LispError`, not a `Compile`-shaped
    /// substring.
    ///
    /// `prefix` is `UnquoteForm` — the closed-set typed enum whose two
    /// variants are EXACTLY the two reachable syntactic markers
    /// (`Unquote` ⊎ `Splice`). Encoding the closed set as a TYPE makes
    /// the constraint load-bearing in the type system — a third
    /// pseudo-marker can never drift into the diagnostic at runtime;
    /// consumers (REPL, LSP, `tatara-check`) pattern-match on
    /// `UnquoteForm::Splice` etc. directly instead of substring-matching
    /// `prefix == ",@"`. Same typed-slot posture as `UnboundTemplateVar`'s
    /// `prefix` slot, parallel to `LispError::Defmacro*.head:
    /// MacroDefHead`. `got` is `SexpWitness` — the closed-set typed
    /// joint identity pairing the offending inner's `SexpShape` (the
    /// twelve reachable outermost shapes the reader can produce) with
    /// its `Sexp::Display` projection (the literal value the author
    /// wrote — `(list 1 2)`, `5`, `:foo`, etc.). Same typed-witness
    /// posture as `SpliceOutsideList.got: SexpWitness`: authoring
    /// tools (REPL, LSP, `tatara-check`) bind to BOTH `got.shape`
    /// (structurally pattern-matchable on `SexpShape::List` etc.) AND
    /// `got.display` (the literal value, renderable verbatim) without
    /// losing either side. The two template-gate `,X/,@X` rejection
    /// variants (`NonSymbolUnquoteTarget` AND `SpliceOutsideList`)
    /// now share ONE typed witness identity at their `got` slot —
    /// every Sexp-display-source `got` slot on the template-gate's
    /// distinct rejection variants carries the SAME typed primitive.
    /// When a future run gives `Sexp` source spans, `pos:
    /// Option<usize>` lands here in ONE place and every
    /// non-symbol-unquote-target site picks up positional rendering
    /// via `crate::diagnostic::format_diagnostic` mechanically.
    #[error("compile error in {prefix}: expected symbol, got {got}")]
    NonSymbolUnquoteTarget {
        prefix: UnquoteForm,
        got: SexpWitness,
    },
    /// A `,@X` (unquote-splice) appeared at a syntactic position where there
    /// is no containing list to splice into — i.e. the splice is the entire
    /// macro-template body, not nested inside a `(... ,@xs ...)` list. Splice
    /// is always list-flattening: `,@(a b c)` inside `(outer ,@xs)` becomes
    /// `(outer a b c)`. At a non-list position there is no list to flatten
    /// into; the form is ill-positioned regardless of whether the inner slot
    /// is a symbol, a literal, or a bound list.
    ///
    /// Sibling of `NonSymbolUnquoteTarget { prefix, got }` and
    /// `UnboundTemplateVar { prefix, name, hint }` for the template-gate's
    /// other distinct failure modes — together the three close every
    /// distinct typed-entry template-gate failure mode for the no-evaluator
    /// template language: each is a structural variant of `LispError`, not
    /// a `Compile`-shaped substring. `prefix` is implicit (always `,@`) and
    /// elided from the variant: this failure mode names ONE syntactic
    /// marker, parallel to how `OddKwargs` names ONE failure mode (odd-length
    /// kwargs slice) without a syntactic-marker slot.
    ///
    /// `got` is `SexpWitness` — the closed-set typed joint identity
    /// pairing the offending inner's `SexpShape` (the twelve reachable
    /// outermost shapes the reader can produce) with its
    /// `Sexp::Display` projection (the literal value the author wrote
    /// — `xs`, `(list 1 2)`, `5`, `:foo`, etc.). Promotes the legacy
    /// `got: String` shape to a typed witness so authoring tools (REPL,
    /// LSP, `tatara-check`) bind to BOTH `got.shape` (structurally
    /// pattern-matchable on `SexpShape::List` etc.) AND `got.display`
    /// (the literal value, renderable verbatim) without losing either
    /// side. Naming both the failure mode AND the offending element
    /// is the typed-entry gate's structural-completeness floor
    /// (THEORY.md §V.1) — without it the operator must re-read the
    /// source to find what actually misfired. After this lift the
    /// structural identity is part of the variant's typed data shape;
    /// a regression that re-collapses `got` to a free-form `String`
    /// loses the rustc-enforced closed-set guarantee on shape
    /// identity.
    ///
    /// First consumer of the `SexpWitness` primitive. Sibling lifts
    /// landed for `NonSymbolUnquoteTarget.got`, `NonSymbolParam.got`,
    /// `DefmacroNonSymbolName.got`, and `DefmacroNonListParams.got`;
    /// the remaining trajectory —
    /// `RestParamMissingName.got: Option<String>` and
    /// `MissingHeadSymbol.got: Option<String>` — is the next set of
    /// moves: every `got: String` (or `Option<String>`) slot whose
    /// source is `Sexp::Display` picks up the typed witness
    /// mechanically once the variant's data shape is bumped. The
    /// remaining two are both `Option<String>` — the typed witness
    /// lands on the `Some` arm directly, the `None` arm encodes the
    /// "missing entirely" sub-mode that's structurally distinct from
    /// "present but malformed".
    ///
    /// When a future run gives `Sexp` source spans, `pos: Option<usize>`
    /// lands on `SexpWitness` ONCE and every splice-outside-list site
    /// picks up positional rendering via
    /// `crate::diagnostic::format_diagnostic` mechanically.
    ///
    /// Display renders `"compile error in ,@: \`,@\` may only appear inside
    /// a list (got ,@{got})"` — the legacy substring `"\`,@\` may only
    /// appear inside a list"` is preserved verbatim so authoring tools that
    /// substring-match on the rendered diagnostic see no drift; the
    /// parenthetical `(got ,@{got})` names the offending form so an LSP
    /// quick-fix that surfaces "the splice has no containing list; you
    /// wrote `,@xs`" gains the literal value as data, no message re-parsing
    /// required. The `{got}` slot flows through `SexpWitness::Display`,
    /// which writes only the `display` field, so the rendering is
    /// byte-for-byte identical to the legacy `got: String` shape.
    #[error("compile error in ,@: `,@` may only appear inside a list (got ,@{got})")]
    SpliceOutsideList { got: SexpWitness },
    /// A macro was called with fewer arguments than its required-param arity:
    /// `(defmacro f (a b) `(,a ,b)) (f 1)` — `b` has no arg. Both the failing
    /// macro's name AND the un-bound param are first-class structural fields,
    /// not embedded substrings of `message`, so authoring surfaces (REPL,
    /// LSP, `tatara-check`) pattern-match on the variant and bind to
    /// `macro_name` / `param` directly instead of substring-parsing the
    /// rendered message. Sibling of `MissingKwarg { key }` for the
    /// macro-call-gate's positional-arity surface — that variant fires when
    /// a `(<head> :key value …)` kwargs form omits a required keyword;
    /// this variant fires when a `(<macroname> a b …)` call omits a required
    /// positional param. The two close every distinct typed-entry
    /// missing-required surface in the substrate.
    ///
    /// Same single emission shape across both expansion strategies — the
    /// substitute path's `bind_args` and the bytecode path's
    /// `apply_compiled` share ONE structural variant, parallel to how the
    /// template-gate's `SpliceOutsideList` is shared across both paths
    /// (THEORY.md §II.1 invariant 2 — free middle: which strategy you
    /// picked must not change which inputs you reject). Before this lift
    /// the same failure mode emitted ONE `LispError::Compile { form:
    /// format!("call to {macro_name}"), message: format!("missing
    /// required arg: {param}") }` triple at TWO call sites — the
    /// three-times rule had two sites with byte-identical shape and one
    /// failure mode.
    ///
    /// `macro_name` and `param` are `String` because they come from
    /// arbitrary source (the call-site head symbol AND the
    /// macro-definition's param symbol). Display matches the legacy
    /// `Compile`-shaped diagnostic byte-for-byte — `"compile error in call
    /// to {macro_name}: missing required arg: {param}"` — so existing
    /// consumer assertions (`msg.contains("missing required arg")`) pass
    /// unchanged. When a future run gives `Sexp` source spans, `pos:
    /// Option<usize>` lands here in ONE place and every missing-macro-arg
    /// site picks up positional rendering via
    /// `crate::diagnostic::format_diagnostic` mechanically.
    #[error("compile error in call to {macro_name}: missing required arg: {param}")]
    MissingMacroArg { macro_name: String, param: String },
    /// A macro was called with MORE arguments than its declared
    /// required+optional arity, on a param list with NO `&rest` slot to
    /// collect the surplus: `(defmacro f (a b) `(,a ,b)) (f 1 2 3)` — `3`
    /// has nowhere to bind. The mirror at the call-site of
    /// `RestParamTrailingTokens` (the definition-site rejection that
    /// surfaces tokens trailing a `&rest <name>` clause, lifted in the
    /// prior-run typed-promotion lineage): that variant rejects malformed
    /// DEFINITIONS that the typed `MacroParams` shape cannot hold (a
    /// `&rest` clause is structurally LAST); this variant rejects
    /// malformed CALLS that the typed `bind` cannot honor (a rest-less
    /// param list has a FIXED maximum arity equal to
    /// `required.len() + optional.len()`). Together with
    /// `MissingMacroArg`, the macro-call-gate's positional-arity surface
    /// is now structurally complete in both directions — too-few AND
    /// too-many — closing the asymmetry where the typed-entry gate
    /// rejected too-few-args loudly but silently truncated too-many to
    /// the slice `bind` could consume.
    ///
    /// A rest-PRESENT param list has no maximum arity (the `&rest` slot
    /// collects every trailing arg into a `Sexp::List`), so this
    /// rejection fires ONLY when `MacroParams.rest` is `None`. The
    /// `expected` slot is `required.len() + optional.len()` — the maximum
    /// number of args the rest-less binder can consume; `got` is
    /// `args.len()` — the actual number supplied. Surfacing both lets
    /// authoring tools (REPL, LSP, `tatara-check`) name the
    /// "you supplied {got} args but the macro takes at most {expected}"
    /// quick-fix without re-deriving either count from the source.
    ///
    /// The leftmost-priority discipline is preserved: `MissingMacroArg`
    /// for a missing REQUIRED arg fires BEFORE this too-many gate
    /// (`bind` iterates the required walk first and bails on the first
    /// missing slot), so `(defmacro f (a b c) …) (f 1)` is
    /// `MissingMacroArg { param: "b" }`, NOT `TooManyMacroArgs`. The two
    /// failure modes are structurally disjoint: too-few-required vs.
    /// too-many-with-no-rest.
    ///
    /// `macro_name` is `String` because it comes from arbitrary source
    /// (the call-site head symbol); `expected` and `got` are `usize`
    /// arities. Display matches the legacy `Compile`-shaped diagnostic
    /// style — `"compile error in call to {macro_name}: too many args:
    /// expected at most {expected}, got {got}"` — so the same
    /// `"compile error in call to {macro_name}:"` substring authoring
    /// tools' assertions key on stays unchanged across the new
    /// rejection mode. When a future run gives `Sexp` source spans,
    /// `pos: Option<usize>` lands here in ONE place and every
    /// too-many-macro-args site picks up positional rendering via
    /// `crate::diagnostic::format_diagnostic` mechanically — same
    /// posture as `MissingMacroArg`.
    #[error(
        "compile error in call to {macro_name}: too many args: \
         expected at most {expected}, got {got}"
    )]
    TooManyMacroArgs {
        macro_name: String,
        expected: usize,
        got: usize,
    },
    /// A non-symbol element appeared in a `defmacro` / `defpoint-template`
    /// / `defcheck` param list at the named position. The legacy
    /// `LispError::Compile { form: "defmacro params", message: "expected
    /// symbol" }` shape named only the failure mode — it didn't say WHICH
    /// element of the param list misfired NOR what was found in its slot.
    /// The structural variant names both: `position` is the 0-based index
    /// of the offending element within the param list, `got` is its
    /// `Sexp::Display` projection so the operator sees the literal value
    /// they wrote (`5`, `"x"`, `:foo`, `(nested)`) instead of the bare
    /// "expected symbol" verdict. Naming both the position AND the
    /// offending element is the typed-entry gate's
    /// structural-completeness floor (THEORY.md §V.1) — without both an
    /// LSP that wants to surface "the third element of your param list
    /// isn't a symbol; you wrote `5`" must re-parse the source.
    ///
    /// Sibling of `MissingMacroArg { macro_name, param }` for the
    /// macro-call-gate's positional-arity surface — that variant fires
    /// when a CALL `(<macroname> a b …)` omits a required positional
    /// param; this variant fires when the DEFMACRO `(defmacro <name> (a
    /// b …) …)` declaration's param list contains a non-symbol where a
    /// param name was expected. The two are the macro-call-gate and the
    /// defmacro-syntax-gate's first-named structural failure modes
    /// respectively — call-site malformed vs. definition-site malformed.
    ///
    /// `position` is `usize` because it is always the loop index inside
    /// `parse_params`; `got` is `SexpWitness` — the closed-set typed
    /// joint identity (structural `SexpShape` + renderable
    /// `Sexp::Display` projection) the offending-value side of the
    /// typed-entry rejection owes the operator. Third consumer of the
    /// `SexpWitness` primitive (after `SpliceOutsideList.got` and
    /// `NonSymbolUnquoteTarget.got`); same posture — authoring tools
    /// (REPL, LSP, `tatara-check`) bind to BOTH `got.shape`
    /// (`SexpShape::Int`, `SexpShape::Keyword`, `SexpShape::List`, etc.)
    /// AND `got.display` (the literal value, renderable verbatim)
    /// jointly across the variant slot rather than substring-grepping
    /// a free-form `String`. Display projects the witness's `display`
    /// field verbatim into the `#[error(... got {got})]` annotation's
    /// `{got}` slot, so the rendered `"compile error in defmacro params:
    /// expected symbol at position {position}, got <display>"` shape is
    /// byte-for-byte identical to the pre-lift `got: String` rendering;
    /// authoring tools that substring-grep on the rendered diagnostic
    /// see no drift. When a future run gives `Sexp` source spans, `pos:
    /// Option<usize>` lands inside `SexpWitness` in ONE place and every
    /// non-symbol-param site picks up positional rendering via
    /// `crate::diagnostic::format_diagnostic` mechanically.
    #[error(
        "compile error in defmacro params: expected symbol at position \
         {position}, got {got}"
    )]
    NonSymbolParam { position: usize, got: SexpWitness },
    /// A `&rest` marker in a `defmacro` / `defpoint-template` / `defcheck`
    /// param list was followed by no element at all (`(&rest)`,
    /// `(a &rest)`) OR by a non-symbol element (`(&rest 5)`,
    /// `(&rest :foo)`). The legacy `LispError::Compile { form: "defmacro
    /// params", message: "&rest needs a name" }` shape named only the
    /// failure mode — it didn't say WHICH `&rest` (i.e. its position
    /// within the param list) misfired NOR what was found in the slot
    /// where the rest-name should have been. The structural variant
    /// names both: `rest_position` is the 0-based index of the `&rest`
    /// marker within the param list, `got` is the offending follower's
    /// typed witness (`Some(SexpWitness::new(SexpShape::Int, "5"))`,
    /// `Some(SexpWitness::new(SexpShape::Keyword, ":foo"))`,
    /// `Some(SexpWitness::new(SexpShape::List, "(nested)"))`) or
    /// `None` when the marker was the last element in the list and
    /// nothing followed at all. Naming both the marker position AND
    /// the offending follower (or its absence) is the typed-entry
    /// gate's structural-completeness floor (THEORY.md §V.1) —
    /// without both, an LSP that wants to surface "your `&rest` at
    /// param-list position 1 has no name; you wrote `5` instead of
    /// a symbol" must re-parse the source.
    ///
    /// Sibling of `NonSymbolParam { position, got }` for the
    /// defmacro-syntax-gate's other definition-site failure mode —
    /// that variant fires when a NON-`&rest` element at a param
    /// position isn't a symbol; this variant fires specifically on the
    /// post-`&rest` follower slot, where the failure mode bifurcates
    /// into "missing entirely" vs. "present but not a symbol". Both
    /// modes share ONE structural variant via `got: Option<SexpWitness>`
    /// (parallel to how `UnboundTemplateVar` and `UnknownKwarg` carry
    /// `hint: Option<String>` for a present-or-absent secondary slot)
    /// rather than splitting into two near-identical variants — the
    /// failure mode IS one ("rest name missing"); the bifurcation is
    /// in the renderable detail, not in what the gate rejects.
    ///
    /// Together, `NonSymbolParam` and `RestParamMissingName` close the
    /// `parse_params` pair — every distinct failure mode the
    /// `parse_params` walker can emit is now a structural variant of
    /// `LispError`, not a `Compile`-shaped substring.
    ///
    /// `rest_position` is `usize` because it is always the loop index
    /// inside `parse_params` at which the `&rest` marker was matched;
    /// `got` is `Option<SexpWitness>` — the SIXTH consumer of the typed
    /// `SexpWitness` primitive (after `SpliceOutsideList.got`,
    /// `NonSymbolUnquoteTarget.got`, `NonSymbolParam.got`,
    /// `DefmacroNonSymbolName.got`, and `DefmacroNonListParams.got`).
    /// The `Option`-shape bifurcates structurally into "missing
    /// entirely" (`None`, when the marker was the param list's last
    /// element) and "present but malformed" (`Some(SexpWitness)`, when
    /// a non-symbol follower came from arbitrary source via
    /// `Sexp::Display`); the typed witness lands on the `Some` arm
    /// only. Display preserves the legacy `"compile error in defmacro
    /// params: &rest needs a name"` prefix byte-for-byte so authoring
    /// tools that substring-grep on the rendered diagnostic see no
    /// drift; the structural detail (`(rest marker at position
    /// {rest_position}, got {got})` when present, `(rest marker at
    /// position {rest_position}, none provided)` when absent) is
    /// appended. When a future run gives `Sexp` source spans, `pos:
    /// Option<usize>` lands inside `SexpWitness` in ONE place and
    /// every rest-param-missing-name site picks up positional
    /// rendering via `crate::diagnostic::format_diagnostic`
    /// mechanically.
    #[error(
        "compile error in defmacro params: &rest needs a name{}",
        rest_param_missing_name_suffix(*rest_position, got.as_ref().map(|w| w.display.as_str()))
    )]
    RestParamMissingName {
        rest_position: usize,
        got: Option<SexpWitness>,
    },
    /// A `&rest <name>` param was followed by one or more further tokens —
    /// `(defmacro f (a &rest xs extra) …)`. The `&rest` name binds every
    /// remaining call arg into a list, so it is structurally the LAST thing
    /// a param list can name: nothing can follow it. Before this variant
    /// `parse_params` returned the moment it bound the rest name, SILENTLY
    /// DROPPING any trailing tokens — `extra` above vanished with no error,
    /// so an author who fat-fingered a stray param (or wrote `&rest xs
    /// &optional y` expecting a feature that doesn't exist yet) got no
    /// signal that their text was ignored. This variant turns that silent
    /// drop into a loud rejection at the typed-entry gate.
    ///
    /// Sibling of `NonSymbolParam` and `RestParamMissingName` — the third
    /// and final `parse_params` definition-site failure mode. The earlier
    /// two fire on a param SLOT (a non-symbol where a name was expected) and
    /// on the post-`&rest` follower (missing-or-malformed name); this one
    /// fires once the rest name is bound and the walker discovers the param
    /// list does not end there. Together the three now genuinely close the
    /// `parse_params` walker — every shape it accepts is a well-formed
    /// `MacroParams`, and every shape it rejects is a structural variant of
    /// `LispError`, not a silently-truncated `Vec` nor a `Compile`-shaped
    /// substring.
    ///
    /// `rest_position` is the loop index at which the `&rest` marker was
    /// matched (parallel to `RestParamMissingName.rest_position`), so an LSP
    /// quick-fix can point at the `&rest` form whose name must be last.
    /// `extra` is the count of trailing tokens (always ≥ 1) and `first` is
    /// the typed witness of the first of them — the SEVENTH consumer of the
    /// `SexpWitness` primitive. `first` is a non-`Option` witness (unlike
    /// `RestParamMissingName.got`) because the trailing run is non-empty by
    /// construction: this variant is only built when `list[rest_position +
    /// 2..]` has a first element. Display appends `(rest marker at position
    /// {rest_position}, {extra} trailing after name, first: {first})` via
    /// `rest_param_trailing_tokens_suffix`, which delegates the bare
    /// parenthetical to the shared `paren_suffix`. When a future run gives
    /// `Sexp` source spans, `pos: Option<usize>` lands inside `SexpWitness`
    /// in ONE place and this site picks up positional rendering
    /// mechanically — exactly as its two siblings do.
    #[error(
        "compile error in defmacro params: &rest name must be last{}",
        rest_param_trailing_tokens_suffix(*rest_position, *extra, &first.display)
    )]
    RestParamTrailingTokens {
        rest_position: usize,
        extra: usize,
        first: SexpWitness,
    },
    /// A `defmacro` / `defpoint-template` / `defcheck` param list carried a
    /// SECOND `&optional` marker — `(defmacro f (a &optional b &optional c)
    /// …)`. The canonical Lisp lambda-list (`(req* &optional opt* &rest r)`,
    /// the shape [`MacroParams`](crate::macro_expand::MacroParams) makes a
    /// type) has exactly ONE optional section, between the required run and
    /// the rest. A second `&optional` is unrepresentable: `MacroParams.optional`
    /// is one flat `Vec`, not a sequence of sections. Without this gate the
    /// walker would treat the second `&optional` as an optional param literally
    /// NAMED `&optional`, binding call args to a marker symbol — the precise
    /// silent misalignment the typed param-list shape exists to forbid (a
    /// sibling of the index-misalignment `MacroParams` ruled out when it
    /// replaced `Vec<Param>`).
    ///
    /// Sibling of `RestParamTrailingTokens` — both fire INSIDE `parse_params`
    /// once a marker is matched and the walker finds the surrounding param
    /// list's marker structure is one the canonical lambda-list ordering
    /// cannot represent (tokens after `&rest <name>`; a repeated `&optional`).
    /// `first_position` is the loop index of the first `&optional` marker,
    /// `second_position` the index of the offending second one — naming both
    /// lets an LSP quick-fix point at the redundant marker to delete. Neither
    /// is a `SexpWitness`: both elements ARE the `&optional` symbol by
    /// construction (the variant is only built when `s == "&optional"` twice),
    /// so there is nothing to witness — only the two positions carry
    /// information. When a future run gives `Sexp` source spans, the marker
    /// positions gain editor-ready rendering by threading spans here.
    #[error(
        "compile error in defmacro params: &optional may appear at most once{}",
        optional_marker_repeated_suffix(*first_position, *second_position)
    )]
    OptionalMarkerRepeated {
        first_position: usize,
        second_position: usize,
    },
    /// A `defmacro` / `defpoint-template` / `defcheck` `&optional` section
    /// carried a list-form entry that did not match the only admissible
    /// shape `(NAME DEFAULT)` — exactly two elements with a symbol head.
    /// Per-param default forms are the typed promotion of `optional:
    /// Vec<String>` to `optional: Vec<OptionalParam>` that the prior
    /// `&optional` run signposted, and this variant is the gate that
    /// admits only the canonical `(NAME DEFAULT)` shape into the typed
    /// `OptionalParam.default` slot. Four distinct list shapes are
    /// rejected, named via the closed-set typed `reason`
    /// ([`OptionalParamMalformedReason`]):
    ///
    ///   * `()`              — empty list spec.
    ///   * `(name)`          — one element, no default form supplied.
    ///   * `(name d e …)`    — three or more elements (CL's
    ///     `(name default supplied-p)` shape is not yet supported — no
    ///     `supplied-p` variable binding without an evaluator).
    ///   * `(5 default)`     — first element isn't a symbol.
    ///
    /// Sibling of `OptionalMarkerRepeated` (the `&optional`-section
    /// marker gate) and `NonSymbolParam` (the bare-symbol gate): together
    /// the three close every distinct typed-entry rejection the optional
    /// section can emit. The bare-symbol form `&optional x` is still
    /// admitted through the bare-symbol path; the list form `&optional
    /// (x default)` is admitted iff this gate accepts the spec.
    ///
    /// `position` is the loop index of the offending list inside
    /// `parse_params`, parallel to `OptionalMarkerRepeated.first_position`
    /// / `RestParamTrailingTokens.rest_position` — naming the position
    /// lets an LSP quick-fix point at the spec to repair. `got` is
    /// `SexpWitness` — the closed-set typed joint identity pairing the
    /// offending list's `SexpShape::List` with its `Sexp::Display`
    /// projection, so consumers (REPL, LSP, `tatara-check`) bind to
    /// BOTH the structural shape AND the renderable literal jointly,
    /// same posture as `NonSymbolParam.got` / `OptionalMarkerRepeated`'s
    /// SexpWitness siblings. `reason` is `OptionalParamMalformedReason`
    /// — the closed-set typed enum whose four variants are EXACTLY the
    /// four reachable list-spec rejection modes, encoded as a TYPE so a
    /// future fifth reason (e.g. supplied-p once an evaluator lands)
    /// becomes a type-level extension rather than a substring drift.
    /// Mirror at the `parse_params` optional-section boundary of the
    /// prior-run `MacroDefHead` / `UnquoteForm` / `TemplateInvariantKind`
    /// / `CompilerSpecIoStage` closed-set lifts.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform / "make invalid
    /// states unrepresentable"; the four malformed list-spec shapes are
    /// nonsense `MacroParams` cannot hold, so the gate must REJECT
    /// rather than bind args to a marker symbol or drop the extras
    /// silently. THEORY.md §II.1 invariant 1 — typed entry; a malformed
    /// default-form spec is exactly the failure mode the typed-entry
    /// gate exists to reject — and the gate must reject DEFINITIONS as
    /// readily as it rejects CALLS. THEORY.md §II.1 invariant 2 — free
    /// middle; the gate fires inside `parse_params` BEFORE either
    /// expansion strategy runs, so both `Expander::new()` (bytecode) and
    /// `Expander::new_substitute_only()` (substitute) reject the SAME
    /// malformed spec at the SAME gate.
    #[error(
        "compile error in defmacro params: malformed &optional spec, got {got}{}",
        optional_param_malformed_suffix(*position, *reason)
    )]
    OptionalParamMalformed {
        position: usize,
        got: SexpWitness,
        reason: OptionalParamMalformedReason,
    },
    /// A `defmacro` / `defpoint-template` / `defcheck` form had fewer
    /// than 4 list elements: the head keyword must be followed by a
    /// name symbol, a param list, and a body — three required slots
    /// after the head, total length 4. The legacy `LispError::Compile
    /// { form: head.to_string(), message: "(defmacro name (params)
    /// body) required" }` shape named only the failure mode — it
    /// didn't say HOW MANY elements the operator actually wrote, so
    /// an authoring surface that wants to surface "you wrote 2
    /// elements; need 4" had to re-parse the source. The structural
    /// variant carries both: `head` is the head keyword (one of
    /// `"defmacro"` / `"defpoint-template"` / `"defcheck"`); `arity`
    /// is the actual length of the form, including the head element.
    /// Naming the actual arity is the typed-entry gate's structural-
    /// completeness floor (THEORY.md §V.1).
    ///
    /// Sibling of `NonSymbolParam` and `RestParamMissingName` for
    /// the defmacro-syntax-gate's other definition-site failure
    /// modes — those variants fire INSIDE `parse_params`, AFTER the
    /// arity gate has passed; this variant fires AT the arity gate
    /// itself, BEFORE name / params / body validation can run.
    /// Together, the three close `macro_def_from`'s outermost
    /// rejection chain — every distinct failure mode the gate can
    /// emit at the top level becomes a structural variant of
    /// `LispError`, not a `Compile`-shaped substring.
    ///
    /// `head` is `MacroDefHead` — the closed-set typed enum whose
    /// three variants are EXACTLY the three reachable head keywords
    /// (`Defmacro` ⊎ `DefpointTemplate` ⊎ `Defcheck`). Encoding the
    /// closed set as a TYPE makes the constraint that ONLY 3 head
    /// identities are reachable load-bearing in the type system — a
    /// fourth pseudo-head can never drift into the diagnostic at
    /// runtime; consumers (REPL, LSP, `tatara-check`) pattern-match
    /// on `MacroDefHead::Defcheck` etc. directly instead of
    /// substring-matching `head == "defcheck"`. Same posture as
    /// `LispError::CompilerSpecIo.stage: CompilerSpecIoStage` and
    /// `LispError::TemplateInvariant.kind: TemplateInvariantKind`:
    /// the closed set becomes a TYPE rather than a `&'static str`
    /// projection at the helper boundary. `arity` is `usize` because
    /// it is always `list.len()` at the call site (the length of
    /// the form including the head element). Display renders the
    /// head via `MacroDefHead`'s Display impl (which projects
    /// through `MacroDefHead::keyword()` to the canonical `&'static
    /// str` literal), so the legacy `head: &'static str`-shaped
    /// diagnostic rides through byte-for-byte.
    ///
    /// Display preserves the legacy `"(defmacro name (params) body)
    /// required"` substring byte-for-byte: the head is parameterized
    /// in the prefix `compile error in {head}:`, but the example
    /// template literal stays `(defmacro name (params) body)` —
    /// matching the legacy form's small infidelity for non-defmacro
    /// heads (the legacy shape rendered `compile error in
    /// defpoint-template: (defmacro name (params) body) required`)
    /// so authoring tools that substring-grep on the legacy
    /// rendering see no drift; the structural detail (`got {arity}
    /// elements, need 4`) is appended. When a future run gives
    /// `Sexp` source spans, `pos: Option<usize>` lands here in ONE
    /// place and every defmacro-arity site picks up positional
    /// rendering via `crate::diagnostic::format_diagnostic`
    /// mechanically.
    #[error(
        "compile error in {head}: (defmacro name (params) body) required \
         (got {arity} elements, need 4)"
    )]
    DefmacroArity { head: MacroDefHead, arity: usize },
    /// A `defmacro` / `defpoint-template` / `defcheck` form passed the
    /// arity gate (≥4 elements) but its name slot — `list[1]`, the
    /// element directly after the head — wasn't a symbol. The legacy
    /// `LispError::Compile { form: head.to_string(), message: "expected
    /// name symbol" }` shape named only the failure mode — it didn't
    /// say WHAT was found in the name slot, so an authoring surface
    /// that wants to surface "you wrote `5` where a name symbol was
    /// expected" had to re-parse the source. The structural variant
    /// carries both: `head` is the head keyword (one of `"defmacro"` /
    /// `"defpoint-template"` / `"defcheck"`); `got` is the offending
    /// `Sexp::Display` projection of the non-symbol element. Naming
    /// both the head AND the offending element is the typed-entry
    /// gate's structural-completeness floor (THEORY.md §V.1).
    ///
    /// Sibling of `DefmacroArity` and the `parse_params` pair
    /// (`NonSymbolParam`, `RestParamMissingName`) for the
    /// defmacro-syntax-gate's other definition-site failure modes.
    /// Walking a malformed `(defmacro …)` from the outside in, the
    /// gate fires:
    ///   1. `DefmacroArity { head, arity }` if the form has fewer
    ///      than 4 elements (`(defmacro)`, `(defmacro f)`).
    ///   2. `DefmacroNonSymbolName { head, got }` if list[1] isn't a
    ///      symbol (`(defmacro 5 () body)`, `(defmacro :foo () body)`).
    ///   3. Inside `parse_params`: `NonSymbolParam { position, got }`
    ///      and `RestParamMissingName { rest_position, got }`.
    ///
    /// This run lifts step 2; the only remaining `Compile`-shaped
    /// site in `macro_def_from` is the `expected param list` gate
    /// (list[2] is not a list), which is the next move in the same
    /// rejection chain.
    ///
    /// `head` is `MacroDefHead` — same typed closed-set posture as
    /// `DefmacroArity.head`: the three reachable head identities
    /// (`Defmacro` ⊎ `DefpointTemplate` ⊎ `Defcheck`) are encoded as
    /// a TYPE so consumers pattern-match on variant identity rather
    /// than substring-comparing the rendered `head` literal.
    /// `got` is `SexpWitness` — the closed-set typed joint identity
    /// pairing the offending name-slot element's `SexpShape` (the
    /// twelve reachable outermost shapes the reader can produce) with
    /// its `Sexp::Display` projection (`5`, `:foo`, `"name"`,
    /// `(nested)`, etc.). Fourth consumer of the `SexpWitness`
    /// primitive (after `SpliceOutsideList.got`,
    /// `NonSymbolUnquoteTarget.got`, and `NonSymbolParam.got`):
    /// authoring tools (REPL, LSP, `tatara-check`) bind to BOTH
    /// `got.shape` (structurally pattern-matchable on `SexpShape::Int`,
    /// `SexpShape::Keyword`, `SexpShape::List`, etc.) AND `got.display`
    /// (the literal value, renderable verbatim) jointly across the
    /// variant slot.
    ///
    /// Display preserves the legacy `"expected name symbol"` substring
    /// byte-for-byte: the prefix `compile error in {head}:` matches
    /// the legacy `Compile { form: head.to_string(), message:
    /// "expected name symbol" }` shape; the structural detail (`,
    /// got {got}`) is appended. `{got}` flows through
    /// `SexpWitness::Display`, which writes only the `display` field,
    /// so the rendering is byte-for-byte identical to the legacy
    /// `got: String` shape. When a future run gives `Sexp` source
    /// spans, `pos: Option<usize>` lands inside `SexpWitness` in ONE
    /// place and every non-symbol-name site picks up positional
    /// rendering via `crate::diagnostic::format_diagnostic`
    /// mechanically.
    #[error("compile error in {head}: expected name symbol, got {got}")]
    DefmacroNonSymbolName {
        head: MacroDefHead,
        got: SexpWitness,
    },
    /// A `defmacro` / `defpoint-template` / `defcheck` form passed both
    /// the arity gate (≥4 elements) AND the name-symbol gate (list[1]
    /// is a symbol) but its param-list slot — `list[2]`, the third
    /// element after the head — wasn't a list. The legacy
    /// `LispError::Compile { form: head.to_string(), message: "expected
    /// param list" }` shape named only the failure mode — it didn't
    /// say WHAT was found in the param-list slot, so an authoring
    /// surface that wants to surface "you wrote `x` where a param list
    /// was expected" had to re-parse the source. The structural variant
    /// carries both: `head` is the head keyword (one of `"defmacro"` /
    /// `"defpoint-template"` / `"defcheck"`); `got` is the offending
    /// `Sexp::Display` projection of the non-list element. Naming both
    /// the head AND the offending element is the typed-entry gate's
    /// structural-completeness floor (THEORY.md §V.1).
    ///
    /// Sibling of `DefmacroArity`, `DefmacroNonSymbolName`, and the
    /// `parse_params` pair (`NonSymbolParam`, `RestParamMissingName`)
    /// for the defmacro-syntax-gate's other definition-site failure
    /// modes. Walking a malformed `(defmacro …)` from the outside in,
    /// the gate fires:
    ///   1. `DefmacroArity { head, arity }` if the form has fewer
    ///      than 4 elements (`(defmacro)`, `(defmacro f)`).
    ///   2. `DefmacroNonSymbolName { head, got }` if list[1] isn't a
    ///      symbol (`(defmacro 5 () body)`).
    ///   3. `DefmacroNonListParams { head, got }` if list[2] isn't a
    ///      list (`(defmacro f x body)`).
    ///   4. Inside `parse_params`: `NonSymbolParam { position, got }`
    ///      and `RestParamMissingName { rest_position, got }`.
    ///
    /// This run lifts step 3; after it, every inline `LispError::Compile
    /// { … }` triple in `macro_def_from` has been lifted to a structural
    /// variant — the entire `macro_def_from` rejection chain (arity →
    /// name-symbol → param-list → parse_params) is structurally typed
    /// for failure modes, with each variant naming WHICH failure mode
    /// AND WHAT was offending.
    ///
    /// `head` is `MacroDefHead` — same typed closed-set posture as
    /// `DefmacroArity.head` and `DefmacroNonSymbolName.head`. After
    /// this lift all three `Defmacro*` variants share ONE typed
    /// head identity, parallel to how `LispError::CompilerSpecIo`
    /// carries `stage: CompilerSpecIoStage` for the four
    /// disk-persistence (operation, stage) pairs.
    /// `got` is `SexpWitness` — the closed-set typed joint identity
    /// pairing the offending param-list-slot element's `SexpShape`
    /// (the twelve reachable outermost shapes the reader can produce)
    /// with its `Sexp::Display` projection (`x`, `5`, `:foo`,
    /// `"params"`, etc.). Fifth consumer of the `SexpWitness`
    /// primitive (after `SpliceOutsideList.got`,
    /// `NonSymbolUnquoteTarget.got`, `NonSymbolParam.got`, and
    /// `DefmacroNonSymbolName.got`): authoring tools (REPL, LSP,
    /// `tatara-check`) bind to BOTH `got.shape` (structurally
    /// pattern-matchable on `SexpShape::Symbol`, `SexpShape::Int`,
    /// `SexpShape::Keyword`, `SexpShape::String`, etc.) AND
    /// `got.display` (the literal value, renderable verbatim) jointly
    /// across the variant slot. After this lift the entire
    /// `macro_def_from` rejection chain — arity → name-symbol →
    /// param-list — shares ONE typed witness identity at every
    /// `Sexp::Display`-source slot; the only remaining unlifted
    /// rejection points in `macro_def_from`'s typed-entry chain are
    /// `RestParamMissingName.got: Option<String>` (inside
    /// `parse_params`) and `MissingHeadSymbol.got: Option<String>`
    /// (at the outer typed-entry gate).
    ///
    /// Display preserves the legacy `"expected param list"` substring
    /// byte-for-byte: the prefix `compile error in {head}:` matches
    /// the legacy `Compile { form: head.to_string(), message:
    /// "expected param list" }` shape; the structural detail (`, got
    /// {got}`) is appended. `{got}` flows through
    /// `SexpWitness::Display`, which writes only the `display` field,
    /// so the rendering is byte-for-byte identical to the legacy
    /// `got: String` shape. When a future run gives `Sexp` source
    /// spans, `pos: Option<usize>` lands inside `SexpWitness` in ONE
    /// place and every non-list-params site picks up positional
    /// rendering via `crate::diagnostic::format_diagnostic`
    /// mechanically.
    #[error("compile error in {head}: expected param list, got {got}")]
    DefmacroNonListParams {
        head: MacroDefHead,
        got: SexpWitness,
    },
    /// `T::compile_from_sexp` (the `TataraDomain` trait default) was
    /// passed something that isn't a list — a bare atom (`5`, `:foo`,
    /// `"x"`, `name`) where a top-level `(KEYWORD …)` form was
    /// expected. The legacy `LispError::Compile { form:
    /// keyword.to_string(), message: "expected list form" }` shape
    /// named only the failure mode and the keyword, and required
    /// authoring tools (REPL, LSP, `tatara-check`) to substring-grep
    /// the rendered message to recognize this specific gate. The
    /// structural variant carries `keyword` as a first-class field so
    /// consumers pattern-match on the variant and bind directly to
    /// the keyword instead of substring-parsing.
    ///
    /// Sibling of `HeadMismatch` — both are typed-entry rejection
    /// gates inside the trait default `compile_from_sexp` walking a
    /// malformed form from the outside in:
    ///   1. `NotAListForm { keyword }` if the form isn't a list at
    ///      all (`5`, `:foo`, `"x"`, `name` — bare atoms).
    ///   2. `LispError::Compile { form, message: "missing head
    ///      symbol" }` (NOT YET LIFTED) if the list is empty or
    ///      list[0] isn't a symbol (`()`, `(5 …)`, `(:foo …)`).
    ///   3. `HeadMismatch { keyword, got }` if list[0] is a symbol
    ///      but doesn't match `T::KEYWORD` (`(other-name …)`).
    ///
    /// After this lift step 1 is structural; the `missing head
    /// symbol` gate is the next move in the same rejection chain
    /// (its own structural-variant lift, parallel to how the
    /// `defmacro_*` family was lifted gate-by-gate).
    ///
    /// `keyword` is `&'static str` because every call site passes
    /// `Self::KEYWORD` from the trait default — a compile-time
    /// literal sourced from the `#[tatara(keyword = "...")]` derive
    /// attribute (or hand-written const). Using a static slot makes
    /// that compile-time guarantee load-bearing in the type system
    /// (a typo in the keyword can never drift into the diagnostic at
    /// runtime — the type system is the floor, same posture as
    /// `HeadMismatch.keyword`, `TypeMismatch.expected`, and the
    /// `Defmacro*.head` family).
    ///
    /// Display preserves the legacy `"expected list form"` substring
    /// AND the `"compile error in {keyword}:"` prefix byte-for-byte
    /// — `"compile error in {keyword}: expected list form"` — so
    /// existing consumer assertions (e.g., the
    /// `compile_from_sexp_emits_compile_for_non_list_form` test
    /// against `MonitorSpec`, `tatara-check`'s diagnostic capture)
    /// pass unchanged. The variant carries no `got` slot because the
    /// offending value's type is itself the diagnostic — `5` /
    /// `:foo` / `"x"` / `name` all reduce to the same failure mode
    /// (not a list); naming the type would be redundant with what
    /// the source already shows. When a future run gives `Sexp`
    /// source spans, `pos: Option<usize>` lands here in ONE place
    /// and every not-a-list-form site picks up positional rendering
    /// via `crate::diagnostic::format_diagnostic` mechanically.
    #[error("compile error in {keyword}: expected list form")]
    NotAListForm { keyword: &'static str },
    /// `T::compile_from_sexp` was passed a list whose head can't be
    /// projected to a symbol — either the list is empty (`()` — there
    /// is no first element) or its first element exists but isn't a
    /// symbol (`(5 …)`, `(:foo …)`, `("x" …)`, `((nested) …)`). The
    /// legacy `LispError::Compile { form: keyword.to_string(),
    /// message: "missing head symbol" }` shape collapsed both
    /// sub-modes into one diagnostic — a `()` form and a `(5 …)` form
    /// produced byte-identical messages, so an authoring surface that
    /// wants to surface "your form is empty" vs. "your form's head is
    /// `5`, not a symbol" had to re-parse the source. The structural
    /// variant carries `got: Option<String>` so the two sub-modes are
    /// distinguishable structurally — `None` for the empty-list case,
    /// `Some(g)` for the present-but-not-symbol case where `g` is
    /// the offending head's `Sexp::Display` projection. Naming both
    /// the failure mode AND the structural detail (empty vs. offending
    /// head) is the typed-entry gate's structural-completeness floor
    /// (THEORY.md §V.1).
    ///
    /// Sibling of `NotAListForm { keyword }` and `HeadMismatch
    /// { keyword, got }` — together the three close every distinct
    /// failure mode the trait-default `compile_from_sexp` rejection
    /// chain can emit. Walking a malformed `(KEYWORD …)` form from
    /// the outside in:
    ///   1. `NotAListForm { keyword }` — the form isn't a list at all
    ///      (`5`, `:foo`, `"x"`, `name` — bare atoms).
    ///   2. `MissingHeadSymbol { keyword, got }` — the form is a
    ///      list but list[0] doesn't exist (`()`) or isn't a symbol
    ///      (`(5 …)`, `(:foo …)`).
    ///   3. `HeadMismatch { keyword, got }` — list[0] is a symbol
    ///      but doesn't match `T::KEYWORD` (`(other-name …)`).
    ///
    /// After this lift the entire `compile_from_sexp` rejection chain
    /// is structurally typed for failure modes — every distinct
    /// rejection binds to ONE structural variant of `LispError`, not
    /// a `Compile`-shaped substring. The `got: Option<String>`
    /// posture parallels `RestParamMissingName.got: Option<String>`:
    /// the failure mode IS one ("head can't be projected to a
    /// symbol"); the bifurcation is in the renderable detail (empty
    /// vs. present-but-wrong-type), not in what the gate rejects, so
    /// the two sub-modes share ONE variant rather than splitting into
    /// near-identical siblings.
    ///
    /// `keyword` is `&'static str` because every call site passes
    /// `Self::KEYWORD` from the trait default — a compile-time literal
    /// sourced from the `#[tatara(keyword = "...")]` derive attribute
    /// (or hand-written const). Using a static slot makes that
    /// compile-time guarantee load-bearing in the type system (a typo
    /// in the keyword can never drift into the diagnostic at runtime —
    /// the type system is the floor, same posture as
    /// `NotAListForm.keyword`, `HeadMismatch.keyword`, and the
    /// `Defmacro*.head` family). `got` is `Option<SexpWitness>` — the
    /// SEVENTH consumer of the typed `SexpWitness` primitive (after
    /// `SpliceOutsideList.got`, `NonSymbolUnquoteTarget.got`,
    /// `NonSymbolParam.got`, `DefmacroNonSymbolName.got`,
    /// `DefmacroNonListParams.got`, and `RestParamMissingName.got`).
    /// The `Option`-wrap bifurcates structurally between "missing
    /// entirely" (`None`, when the list is empty) and "present but
    /// malformed" (`Some(SexpWitness)`, when the head exists but
    /// isn't a symbol); the typed witness lands on the `Some` arm
    /// only — same posture as `RestParamMissingName.got:
    /// Option<SexpWitness>`. With this lift EVERY Sexp-display-source
    /// `got` slot in the substrate carries ONE typed identity:
    /// the typed-entry / template-gate / defmacro-syntax-gate
    /// rejection surface is structurally unified end-to-end across
    /// ALL `got: <T>` slots where `<T>` projects from `Sexp::Display`.
    ///
    /// Display preserves the legacy `"missing head symbol"` substring
    /// AND the `"compile error in {keyword}:"` prefix byte-for-byte —
    /// `"compile error in {keyword}: missing head symbol"` is the
    /// stable prefix; the structural detail (`(empty list)` for
    /// `None`, `(got {g})` for `Some(g)`) is appended in a
    /// parenthetical, parallel to how `RestParamMissingName` appends
    /// `(rest marker at position {n}, got {g})` /
    /// `(rest marker at position {n}, none provided)` and how
    /// `SpliceOutsideList` appends `(got ,@{got})`. The `{g}` slot
    /// flows through `SexpWitness::Display`, which writes only the
    /// `display` field, so the rendering is byte-for-byte identical
    /// to the pre-lift `Option<String>` shape. When a future run
    /// gives `Sexp` source spans, `pos: Option<usize>` lands inside
    /// `SexpWitness` in ONE place and every missing-head-symbol site
    /// picks up positional rendering via
    /// `crate::diagnostic::format_diagnostic` mechanically.
    #[error(
        "compile error in {keyword}: missing head symbol{}",
        missing_head_symbol_suffix(got.as_ref().map(|w| w.display.as_str()))
    )]
    MissingHeadSymbol {
        keyword: &'static str,
        got: Option<SexpWitness>,
    },
    /// `compile_named_from_forms::<T>` — driving every `(KEYWORD NAME …)`
    /// positional-name surface (`(defpoint NAME …)`, `(defalertpolicy
    /// NAME …)`) — was passed a list whose head matched `T::KEYWORD` but
    /// whose tail had no NAME slot at all. `(defpoint)` — list.len() == 1
    /// (just the keyword); the gate fires before NAME extraction. The
    /// legacy `LispError::Compile { form: T::KEYWORD.to_string(),
    /// message: format!("expected ({} NAME …)", T::KEYWORD) }` shape
    /// named the failure mode AND the keyword by embedding both into a
    /// formatted message — required authoring tools (REPL, LSP,
    /// `tatara-check`) to substring-grep the rendered diagnostic to
    /// recognize this specific gate. The structural variant carries
    /// `keyword` as a first-class field so consumers pattern-match on
    /// the variant and bind to the keyword directly instead of
    /// substring-parsing.
    ///
    /// Sibling of `NotAListForm { keyword }`, `MissingHeadSymbol
    /// { keyword, got }`, and `HeadMismatch { keyword, got }` — those
    /// close the trait-default `compile_from_sexp` rejection chain
    /// (the keyword-only entry point, `(KEYWORD :k v …)`); this
    /// variant opens the parallel `compile_named_from_forms`
    /// rejection chain (the positional-name entry point, `(KEYWORD
    /// NAME :k v …)`). Walking a malformed `(KEYWORD NAME …)` form
    /// from the outside in:
    ///   1. `NamedFormMissingName { keyword }` — the form passes the
    ///      keyword-head match but has no NAME slot (`(defpoint)`).
    ///   2. `LispError::Compile { form, message: "positional NAME
    ///      must be a symbol or string" }` (NOT YET LIFTED) — the
    ///      form has a NAME slot but it's not a symbol or string
    ///      (`(defpoint 5 …)`, `(defpoint :foo …)`, `(defpoint
    ///      (nested) …)`).
    ///   3. Inside `T::compile_from_args(&list[2..])` — derive-
    ///      generated kwargs handling with its own structural
    ///      variants (`UnknownKwarg`, `MissingKwarg`, etc.).
    ///
    /// This run lifts step 1; step 2 is the next move in the same
    /// rejection chain (its own structural-variant lift, parallel to
    /// how the `compile_from_sexp` chain was lifted gate-by-gate
    /// across `092a2b2` (`NotAListForm`) and `b3e941e`
    /// (`MissingHeadSymbol`)).
    ///
    /// `keyword` is `&'static str` because every call site passes
    /// `T::KEYWORD` from `compile_named_from_forms` — a compile-time
    /// literal sourced from the `#[tatara(keyword = "...")]` derive
    /// attribute (or hand-written const). Using a static slot makes
    /// that compile-time guarantee load-bearing in the type system —
    /// a typo in the keyword can never drift into the diagnostic at
    /// runtime, the type system is the floor, same posture as
    /// `NotAListForm.keyword`, `MissingHeadSymbol.keyword`,
    /// `HeadMismatch.keyword`, `TypeMismatch.expected`, and the
    /// `Defmacro*.head` family. The variant carries no `arity` slot
    /// because the offending form's structure is invariant — every
    /// trigger has list.len() == 1 exactly (list[0] is the keyword,
    /// no list[1] for NAME); naming a fixed value would be
    /// misleading data, parallel to how `NotAListForm` carries no
    /// `got` slot (the form's not-a-list type is itself the
    /// diagnostic).
    ///
    /// Display matches the legacy `Compile`-shaped diagnostic
    /// byte-for-byte — `"compile error in {keyword}: expected
    /// ({keyword} NAME …)"` (note: `…` is the Unicode horizontal
    /// ellipsis U+2026, preserved verbatim from the legacy
    /// `format!("expected ({} NAME …)", T::KEYWORD)` shape) — so
    /// existing consumer assertions (`tatara-check`'s diagnostic
    /// capture, REPL substring-greps) pass unchanged. When a future
    /// run gives `Sexp` source spans, `pos: Option<usize>` lands
    /// here in ONE place and every named-form-missing-name site
    /// picks up positional rendering via
    /// `crate::diagnostic::format_diagnostic` mechanically.
    #[error("compile error in {keyword}: expected ({keyword} NAME …)")]
    NamedFormMissingName { keyword: &'static str },
    /// `compile_named_from_forms::<T>` was passed a `(KEYWORD NAME …)` form
    /// whose NAME slot exists but isn't projectable to a symbol or string —
    /// `(defpoint 5 …)`, `(defpoint :foo …)`, `(defpoint (nested) …)`. Gate
    /// 2 of the same rejection chain `NamedFormMissingName` opens: that
    /// variant fires when there is no NAME slot at all (`(defpoint)` —
    /// list.len() == 1); this variant fires when the NAME slot exists but
    /// is wrong-typed. Together the two close `compile_named_from_forms`'s
    /// outer rejection chain — every typed-entry rejection mode in the
    /// positional-name authoring surface is now a structural variant of
    /// `LispError`, not a `Compile`-shaped substring.
    ///
    /// `keyword` is `&'static str` because every call site passes
    /// `T::KEYWORD` — a compile-time literal sourced from the
    /// `#[tatara(keyword = "...")]` derive attribute (or hand-written
    /// const); a typo in the keyword can never drift into the diagnostic
    /// at runtime. `got` is the typed closed-set `SexpShape` enum —
    /// the twelve reachable Sexp outermost shapes encoded as variant
    /// identities so the SexpShape that the typed-entry gate observed
    /// is load-bearing data in the type system. Same posture as
    /// `TypeMismatch.got: SexpShape`: consumers pattern-match on
    /// `SexpShape::Int` etc. directly instead of substring-matching
    /// `got == "int"`. Encoding the closed set as a TYPE makes the
    /// compile-time guarantee load-bearing, parallel to
    /// `NotAListForm.keyword`, `MissingHeadSymbol.keyword`,
    /// `HeadMismatch.keyword`, and the `Defmacro*.head` family.
    ///
    /// Display preserves the legacy `"positional NAME must be a symbol
    /// or string"` substring AND the `"compile error in {keyword}:"`
    /// prefix byte-for-byte; the structural detail (`(got {got})`) is
    /// appended in a parenthetical, parallel to how `MissingHeadSymbol`
    /// appends `(got {g})` / `(empty list)` and how `RestParamMissingName`
    /// appends `(rest marker at position {n}, got {g})`. When a future
    /// run gives `Sexp` source spans, `pos: Option<usize>` lands here in
    /// ONE place and every named-form-non-symbol-name site picks up
    /// positional rendering via `crate::diagnostic::format_diagnostic`
    /// mechanically.
    #[error("compile error in {keyword}: positional NAME must be a symbol or string (got {got})")]
    NamedFormNonSymbolName {
        keyword: &'static str,
        got: SexpShape,
    },
    /// `rewrite_typed::<T>` — the typed-exit gate of the self-optimization
    /// primitive (THEORY.md §II.1 invariant 3) — was handed a rewriter
    /// closure whose output, after typed round-trip through canonical JSON,
    /// did not project to `Sexp::List`. The round-trip contract is:
    /// serialize `T` → `Sexp::List` (alternating kwargs), hand the list
    /// to the rewriter `F`, re-enter `T::compile_from_args` over the
    /// returned list's items. A non-list result violates that contract —
    /// the gate fires before `compile_from_args` runs, so a wrong-shaped
    /// rewriter output is rejected at the typed-exit boundary rather than
    /// confusingly later inside the kwargs decoder.
    ///
    /// Mirror at the typed-exit boundary of the typed-entry-side
    /// `NamedFormNonSymbolName` lift: the latter rejects a wrong-typed
    /// NAME slot at `compile_named_from_forms::<T>`'s entry; this variant
    /// rejects a wrong-typed rewriter output at `rewrite_typed::<T>`'s
    /// exit. Both round-trip the same compile-time `T::KEYWORD` projection
    /// into the variant's `keyword` slot, so authoring tools (REPL, LSP,
    /// `tatara-check`) bind on variant identity at both boundaries of the
    /// self-optimization primitive rather than substring-grepping the
    /// rendered diagnostic.
    ///
    /// `keyword` is `&'static str` because every call site passes
    /// `T::KEYWORD` from `rewrite_typed::<T>` — a compile-time literal
    /// sourced from the `#[tatara(keyword = "...")]` derive attribute (or
    /// hand-written const). Using a static slot makes that compile-time
    /// guarantee load-bearing in the type system — a typo can never drift
    /// into the diagnostic at runtime, the type system is the floor, same
    /// posture as `NotAListForm.keyword`, `MissingHeadSymbol.keyword`,
    /// `HeadMismatch.keyword`, `NamedFormMissingName.keyword`, and
    /// `NamedFormNonSymbolName.keyword`.
    ///
    /// `got` is `SexpWitness` — the closed-set typed joint identity
    /// pairing the offending rewriter output's `SexpShape` (the twelve
    /// reachable Sexp outermost shapes the rewriter closure can produce)
    /// with its `Sexp::Display` projection (the literal value the rewriter
    /// actually returned — `42`, `:foo`, `"bad"`, `notify-ref`, `()`,
    /// etc.). EIGHTH consumer of the typed `SexpWitness` primitive
    /// introduced in `error.rs`'s `SpliceOutsideList.got` lift, and the
    /// FIRST consumer on the typed-EXIT boundary — sibling lifts of
    /// `SpliceOutsideList.got: SexpWitness`, `NonSymbolUnquoteTarget.got:
    /// SexpWitness`, `NonSymbolParam.got: SexpWitness`,
    /// `DefmacroNonSymbolName.got: SexpWitness`,
    /// `DefmacroNonListParams.got: SexpWitness`,
    /// `RestParamMissingName.got: Option<SexpWitness>`, and
    /// `MissingHeadSymbol.got: Option<SexpWitness>` close the typed-ENTRY
    /// rejection surface across the substrate's seven entry-side gates.
    /// This eighth lift extends the typed-identity unification contract
    /// across BOTH boundaries of the typed-IR algebra
    /// (THEORY.md §II.1 invariant 1 + invariant 3) — every
    /// `Sexp::Display`-source `got` slot in the substrate, regardless of
    /// whether the rejection fires at typed-ENTRY (compile_from_sexp
    /// chain, template-gate, defmacro-syntax-gate, parse_params walker)
    /// or typed-EXIT (rewrite_typed's `Sexp::List`-contract gate), now
    /// shares ONE typed witness identity at the variant slot. Authoring
    /// tools (REPL, LSP, `tatara-check`) bind to BOTH `got.shape`
    /// (structurally pattern-matchable on `SexpShape::Int` etc.) AND
    /// `got.display` (the literal value, renderable verbatim) jointly
    /// for a typed-exit-side rejection too — no projection-to-`String`
    /// at the helper boundary loses the structural identity. Promotes
    /// the legacy `got: String` shape parallel to how the seven entry-
    /// side lifts promoted theirs.
    ///
    /// Display matches the legacy `Compile`-shaped diagnostic byte-for-
    /// byte — `"compile error in {keyword}: rewriter must return a list;
    /// got {got}"` — so existing consumer assertions (`tatara-check`'s
    /// diagnostic capture, REPL substring-greps that match on `"rewriter
    /// must return a list; got "`) pass unchanged across the lift. The
    /// `{got}` slot flows through `SexpWitness::Display`, which writes
    /// only the `display` field, so the rendering is byte-for-byte
    /// identical to the pre-lift `got: String` shape. When a future run
    /// gives `Sexp` source spans, `pos: Option<usize>` lands inside
    /// `SexpWitness` in ONE place and every rewriter-non-list site
    /// picks up positional rendering via
    /// `crate::diagnostic::format_diagnostic` mechanically.
    #[error("compile error in {keyword}: rewriter must return a list; got {got}")]
    RewriterNonList {
        keyword: &'static str,
        got: SexpWitness,
    },
    /// `serde_json::to_value` of a typed `T` value (any registered
    /// `TataraDomain`) errored. Two sites share this failure mode:
    /// `register::<T>`'s registry-dispatch closure (the registered
    /// handler serializes the just-typed value to JSON for the
    /// dispatcher) and `rewrite_typed::<T>`'s round-trip prelude (the
    /// self-optimization primitive serializes its input to JSON before
    /// projecting it to a `Sexp::List` for the rewriter closure). Both
    /// funnel through `serialize_to_json_err::<T>` so the type-level
    /// `T::KEYWORD` projection is mechanically threaded into the
    /// `keyword` slot, parallel to how `rewriter_non_list_err::<T>`
    /// threads `T::KEYWORD` into `RewriterNonList.keyword`.
    ///
    /// Mirror at the typed-exit boundary of the typed-entry-side
    /// `from_value` failure path: `extract_via_serde` /
    /// `extract_optional_via_serde` / `extract_vec_via_serde` route
    /// through `deserialize_err` / `deserialize_item_err`, which now
    /// produce the structural `LispError::KwargDeserialize { key, idx,
    /// message }` variant — the typed-entry-side sibling of this lift.
    /// After both lifts BOTH directions of the JSON-projection round-
    /// trip — `to_value` (typed-exit, keyword-keyed) AND `from_value`
    /// (typed-entry, key-keyed) — are structurally typed; there are
    /// zero `LispError::Compile { ... }` construction sites left in
    /// `tatara-lisp/src/domain.rs`.
    ///
    /// Sibling of `RewriterNonList { keyword, got }` for the
    /// `rewrite_typed::<T>` rejection chain — that variant fires when
    /// the rewriter's OUTPUT is not a list; this variant fires when
    /// the round-trip's INPUT (the typed value) fails to project to
    /// JSON at all. Together with `RewriterNonList`, every distinct
    /// `to_value`-side rejection mode in the self-optimization
    /// primitive and the registry-dispatch closure binds to ONE
    /// structural variant of `LispError`, not a `Compile`-shaped
    /// substring.
    ///
    /// `keyword` is `&'static str` because every call site projects
    /// `T::KEYWORD` via `serialize_to_json_err::<T>` — a compile-time
    /// literal sourced from the `#[tatara(keyword = "...")]` derive
    /// attribute (or hand-written const). Using a static slot makes
    /// that compile-time guarantee load-bearing in the type system —
    /// a typo can never drift into the diagnostic at runtime, the
    /// type system is the floor, same posture as
    /// `RewriterNonList.keyword`, `NamedFormMissingName.keyword`,
    /// `NamedFormNonSymbolName.keyword`, `NotAListForm.keyword`,
    /// `MissingHeadSymbol.keyword`, `HeadMismatch.keyword`, and the
    /// `Defmacro*.head` family. `message` is `String` because it
    /// carries the `serde_json::Error::Display` projection (errors
    /// render `expected … at line L column C` shapes — arbitrary text
    /// from the underlying `serde_json::Error`). Carrying the rendered
    /// message rather than a `#[source] serde_json::Error` keeps the
    /// variant's structural shape parallel to every other String-
    /// carrying variant in this enum — every consumer renders via
    /// Display, none consumes the underlying error chain.
    ///
    /// Display matches the legacy `Compile`-shaped diagnostic byte-
    /// for-byte — `"compile error in {keyword}: serialize: {message}"`
    /// — so existing consumer assertions (`tatara-check`'s diagnostic
    /// capture, REPL substring-greps that match on `"serialize: "`)
    /// pass unchanged across the lift. When a future run gives `Sexp`
    /// source spans, `pos: Option<usize>` lands here in ONE place and
    /// every domain-serialize site picks up positional rendering via
    /// `crate::diagnostic::format_diagnostic` mechanically.
    #[error("compile error in {keyword}: serialize: {message}")]
    DomainSerialize {
        keyword: &'static str,
        message: String,
    },
    /// `serde_json::from_value::<T>` of a kwarg's canonical-JSON projection
    /// errored. Two distinct sites share this failure mode through ONE
    /// structural variant whose data carries the typed closed-set
    /// `KwargPath` enum directly — `KwargPath::Named(key)` for the scalar
    /// / `Option<T>` path, `KwargPath::Item { key, idx }` for the per-item
    /// path inside a `Vec<T>` kwarg. The bifurcation lives inside the
    /// typed enum's variant identity, not in a sibling `idx: Option<usize>`
    /// slot:
    ///
    ///   1. `extract_via_serde` (required) and `extract_optional_via_serde`
    ///      (optional) — kwarg-keyed `from_value` failures at the scalar /
    ///      `Option<T>` path. `path: KwargPath::Named(key)`; the failure
    ///      binds to the kwarg slot identity ONLY (`:{key}`).
    ///   2. `extract_vec_via_serde` (per-item) — kwarg-AND-index-keyed
    ///      `from_value` failures inside a `Vec<T>` kwarg's items.
    ///      `path: KwargPath::Item { key, idx }`; the failure binds to the
    ///      kwarg slot AND the failing item index (`:{key}[{i}]`).
    ///
    /// Mirror at the typed-entry JSON boundary of the typed-exit-side
    /// `DomainSerialize { keyword, message }` lift: the latter rejects a
    /// `to_value::<T>` failure (typed-exit, keyword-keyed, sourced from
    /// `T::KEYWORD` and so `&'static str`); this variant rejects a
    /// `from_value::<T>` failure (typed-entry, kwargs-path-keyed, sourced
    /// from the runtime kwarg lookup and carried as a typed `KwargPath`).
    /// Together the two close the JSON-projection boundary of the
    /// typed-domain surface — every distinct `serde_json` failure mode at
    /// the typed-domain boundary binds to ONE structural variant of
    /// `LispError`, not a `Compile`-shaped substring.
    ///
    /// Sibling of `TypeMismatch.form: KwargPath`: both kwargs-path-keyed
    /// typed-entry rejection modes now carry the SAME typed kwargs-path
    /// identity inside their variant's data shape. The `(key, idx:
    /// Option<usize>)` bifurcation collapses into `KwargPath`'s variant
    /// identity — `Named` vs. `Item` — so the invalid combination
    /// `(key: "", idx: Some(0))` for a scalar path (or any combination that
    /// invented a fourth sub-mode) becomes structurally unrepresentable
    /// rather than re-asserted at the helper boundary via runtime
    /// `Option::is_some` comparison. Same closed-set posture as
    /// `LispError::TypeMismatch.form: KwargPath`,
    /// `LispError::Defmacro*.head: MacroDefHead`,
    /// `LispError::UnboundTemplateVar.prefix: UnquoteForm`,
    /// `LispError::CompilerSpecIo.stage: CompilerSpecIoStage`, and
    /// `LispError::TemplateInvariant.kind: TemplateInvariantKind`.
    ///
    /// `path` is `KwargPath` — the closed-set typed enum whose variants
    /// are EXACTLY the reachable kwargs-path shapes (`Named(String)` /
    /// `Item { key: String, idx: usize }` / `Slot(usize)`). The runtime
    /// `kwarg lookup` source-of-key is carried inside the typed enum's
    /// `String` payload; the per-item-index bifurcation is the enum's
    /// `Named` vs. `Item` variant identity, not a sibling Option slot.
    /// `message` is `String` because it carries the
    /// `serde_json::Error::Display` projection (errors render `expected …
    /// at line L column C` shapes — arbitrary text from the underlying
    /// `serde_json::Error`); carrying the rendered message rather than a
    /// `#[source] serde_json::Error` keeps the variant's structural shape
    /// parallel to every other String-carrying variant in this enum
    /// (`DomainSerialize.message`, `Compile.message`).
    ///
    /// `message` carries the raw `serde_json::Error::Display` projection
    /// — NO `"deserialize: "` prefix in the field, the prefix is in the
    /// `Display` rendering — so consumers that pattern-match on
    /// `message` get the underlying diagnostic unchanged, parallel to how
    /// `DomainSerialize.message` carries the raw `serde_json` projection
    /// (the `"serialize: "` prefix lives in Display, not in the slot).
    ///
    /// Display matches the legacy `Compile`-shaped diagnostic byte-for-
    /// byte across both sub-modes via `KwargPath`'s Display projection:
    /// `"compile error in :{key}: deserialize: {message}"` for
    /// `KwargPath::Named`, `"compile error in :{key}[{idx}]: deserialize:
    /// {message}"` for `KwargPath::Item` — so existing substring-grep
    /// consumers (`tatara-check`'s diagnostic capture, REPL substring-greps
    /// that match on `"deserialize: "`, `":steps[1]"`, `":level"`) pass
    /// unchanged across the lift. When a future run gives `Sexp` source
    /// spans, `pos: Option<usize>` lands here in ONE place and every
    /// kwarg-deserialize site picks up positional rendering via
    /// `crate::diagnostic::format_diagnostic` mechanically.
    #[error("compile error in {path}: deserialize: {message}")]
    KwargDeserialize { path: KwargPath, message: String },
    /// `compiler_spec.rs`'s disk-persistence surface emitted an
    /// I/O or serde failure. Four call sites in `compiler_spec.rs`
    /// share this failure mode through ONE structural variant keyed
    /// on the closed-set `CompilerSpecIoStage` enum (`realize_to_disk`
    /// × {serialize, write} ⊎ `load_from_disk` × {read, deserialize}).
    ///
    /// Encoding the (operation, stage) pair as ONE typed enum (rather
    /// than two `&'static str` slots `operation` × `stage`) makes the
    /// constraint that ONLY 4 of the 2×4 = 8 hypothetical pairs are
    /// reachable load-bearing in the type system — a typo like
    /// `(operation: "load_from_disk", stage: "write")` becomes
    /// structurally unrepresentable rather than re-asserted at the
    /// helper boundary via runtime string comparison. Same posture as
    /// `MacroDefHead` in `macro_expand.rs`: the closed set becomes a
    /// TYPE, and rustc's exhaustiveness check is the future invariant-
    /// keeper. Adding a new disk-persistence operation (e.g.,
    /// `load_from_str`) requires extending `CompilerSpecIoStage`,
    /// which rustc-enforces matching at every projection site
    /// (`operation()` / `label()`).
    ///
    /// Mirror at the disk boundary of the typed-domain JSON-projection
    /// round-trip's `DomainSerialize` / `KwargDeserialize` sibling pair
    /// at the in-memory kwarg boundary: those variants reject
    /// `to_value::<T>` / `from_value::<T>` failures at the typed-domain
    /// boundary; this variant rejects file I/O + top-level JSON
    /// failures at the disk boundary. After this lift, every distinct
    /// failure mode in `tatara-lisp/src/compiler_spec.rs`'s persistence
    /// surface is structurally typed; there are zero
    /// `LispError::Compile { ... }` construction sites left in
    /// `tatara-lisp/src/compiler_spec.rs`.
    ///
    /// `stage` is `CompilerSpecIoStage` — a closed-set typed enum
    /// whose `operation()` and `label()` projections feed the Display
    /// rendering — so the compile-time guarantee on BOTH slots is
    /// load-bearing in the type system. `message` is `String` because
    /// it carries the underlying error's `Display` projection
    /// (`serde_json::Error` for serialize / deserialize, `std::io::Error`
    /// for read / write — arbitrary text); carrying the rendered
    /// message rather than a `#[source]` chain keeps the variant's
    /// structural shape parallel to every other String-carrying variant
    /// in this enum (`DomainSerialize.message`, `KwargDeserialize.message`,
    /// `Compile.message`).
    ///
    /// `message` carries the raw underlying-error `Display` projection
    /// — NO `"{stage}: "` prefix in the field, the prefix is in the
    /// `Display` rendering — so consumers that pattern-match on
    /// `message` get the underlying diagnostic unchanged, parallel to
    /// how `DomainSerialize.message` carries the raw `serde_json`
    /// projection (the `"serialize: "` prefix lives in Display, not in
    /// the slot) and `KwargDeserialize.message` carries the raw
    /// `serde_json` projection (the `"deserialize: "` prefix lives in
    /// Display, not in the slot).
    ///
    /// Display matches the legacy `Compile`-shaped diagnostic byte-for-
    /// byte across all four stages — `"compile error in {operation}:
    /// {stage}: {message}"` where `{operation}` is `stage.operation()`
    /// and `{stage}` is `stage.label()` — so existing consumer
    /// assertions (`tatara-check`'s diagnostic capture, REPL substring-
    /// greps that match on `"realize_to_disk"`, `"load_from_disk"`,
    /// `"serialize: "`, `"write: "`, `"read: "`, `"deserialize: "`)
    /// pass unchanged across the lift. When a future run gives `Sexp`
    /// source spans, `pos: Option<usize>` lands here in ONE place
    /// (though the disk surface is non-positional — failures originate
    /// from file I/O / serde, not from a Sexp slot — so the field
    /// would stay `None` at every call site, the variant joining the
    /// `position_is_none_for_non_positional_variants` cohort).
    #[error("compile error in {}: {}: {message}", stage.operation(), stage.label())]
    CompilerSpecIo {
        stage: CompilerSpecIoStage,
        message: String,
    },
    /// `apply_compiled`'s bytecode-runtime invariant violation. Four call
    /// sites in `macro_expand.rs::apply_compiled` share this failure mode
    /// through ONE structural variant keyed on the closed-set
    /// `TemplateInvariantKind` enum. Every violation here is a
    /// COMPILER-INTERNAL bug — the bytecode that drives `apply_compiled`
    /// is produced by `compile_template` / `compile_node` in this same
    /// module, and a well-formed bytecode never references an
    /// out-of-bounds param index (Subst / Splice gates) nor leaves the
    /// runtime stack unbalanced at the final pop (EndList / no-value
    /// gates).
    ///
    /// Encoding the four failure modes as ONE typed enum (rather than a
    /// free-form `message: String` slot) makes the constraint that ONLY
    /// 4 distinct violations are reachable load-bearing in the type
    /// system — a regression that drifts the failure mode (e.g. a fifth
    /// "wrong opcode" gate added without a `TemplateInvariantKind`
    /// extension) becomes a `match` compile error at the projection site,
    /// not a substring-grep regression that ships. Same posture as
    /// `CompilerSpecIoStage` for `CompilerSpecIo`: the closed set becomes
    /// a TYPE, not a `matches!` literal in the helper. The index slot of
    /// the Subst / Splice gates lives INSIDE the variant
    /// (`SubstBadIndex(usize)` / `SpliceBadIndex(usize)`) rather than on
    /// the outer variant as `op_index: Option<usize>`, so the invalid
    /// combination `EndListEmptyStack { op_index: Some(_) }` is
    /// structurally unrepresentable — the type system encodes "this gate
    /// has an index, that gate does not."
    ///
    /// Display matches the legacy `Compile`-shaped diagnostic
    /// byte-for-byte across all four kinds — `"compile error in
    /// {macro_name}: {kind.message()}"` — so existing consumer assertions
    /// (`tatara-check`'s diagnostic capture, REPL substring-greps that
    /// match on `"compiled template referenced bad param index"`,
    /// `"compiled template referenced bad splice index"`, `"compiled
    /// template: EndList with empty stack"`, `"compiled template produced
    /// no value"`) pass unchanged across the lift.
    ///
    /// `macro_name` is `String` because it comes from arbitrary source
    /// (the call-site head symbol). `kind` is `TemplateInvariantKind` —
    /// a closed-set typed enum whose `message()` projection feeds the
    /// Display rendering.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the closed set
    /// of bytecode-invariant failure modes becomes a TYPE rather than a
    /// runtime string-comparison-and-format dance. THEORY.md §VI.1 —
    /// generation over composition; the typed enum lands the structural-
    /// completeness floor for the bytecode-runtime surface, parallel to
    /// how `CompilerSpecIoStage` lands the structural-completeness floor
    /// for the disk-persistence surface and `MacroDefHead` lands it for
    /// the macro-definition-head closed set. THEORY.md §II.1 invariant 5
    /// (composition preserves proofs): a well-formed bytecode invariant
    /// is the proof that drives the interpreter; the structural variant
    /// makes the proof's REJECTION shape first-class.
    #[error("compile error in {macro_name}: {}", kind.message())]
    TemplateInvariant {
        macro_name: String,
        kind: TemplateInvariantKind,
    },
    /// `Expander::expand` recursed past its configured ceiling
    /// (`Expander::max_expansion_depth`, default
    /// `crate::macro_expand::DEFAULT_MAX_EXPANSION_DEPTH = 256`). Fires
    /// on the runaway `(defmacro loop (x) `(loop ,x))` — a macro
    /// whose expansion contains another call to itself — which pre-
    /// lift stack-overflowed the process (a below-floor failure with
    /// no `Result` witness). The typed-entry gate turns "we abort" into
    /// "we reject at the expansion boundary" so authoring surfaces
    /// (REPL, LSP, `tatara-check`) see a `Result::Err` at the same
    /// call boundary as every other macro-expansion failure and can
    /// pattern-match on the variant identity to route diagnostics
    /// through the same channel as `TooManyMacroArgs` /
    /// `MissingMacroArg` / `UnboundTemplateVar`.
    ///
    /// `macro_name` is `String` because it comes from arbitrary
    /// source — the head symbol of the offending call at the moment
    /// the ceiling is hit; `limit` is `usize` because it is the
    /// configured ceiling the expander enforced at that call. The
    /// pair names BOTH the offending macro AND the ceiling it
    /// breached, so an LSP that wants to surface "your macro `loop`
    /// re-expanded past 256 levels; is it recursive without a base
    /// case?" has both halves at the variant boundary without
    /// substring-parsing the rendered diagnostic.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the
    /// runaway-macro-expansion failure mode becomes a first-class
    /// typed rejection at the expander boundary instead of an
    /// unhandled stack overflow that aborts the process without
    /// producing a `Result` at all. THEORY.md §II.1 invariant 1 —
    /// typed entry; every macro-expansion failure mode the expander
    /// admits is a variant of `LispError`, so the below-floor abort
    /// is the last un-typed rejection in the expander's dispatch
    /// chain — closing it moves the expansion surface fully into the
    /// `Result` algebra.
    #[error(
        "compile error in call to {macro_name}: macro expansion depth exceeded (limit: {limit})"
    )]
    ExpansionDepthExceeded { macro_name: String, limit: usize },
    /// `Expander::expand`'s freshly-applied macro output crossed the
    /// configured node-count ceiling (`Expander::max_expansion_size`,
    /// default `crate::macro_expand::DEFAULT_MAX_EXPANSION_SIZE`).
    /// Peer to [`Self::ExpansionDepthExceeded`] one RESOURCE axis over:
    /// where the depth ceiling bounds RECURSION LENGTH (how many times
    /// a macro re-expands into itself before the process aborts) and
    /// [`crate::macro_expand::DEFAULT_MAX_CACHE_ENTRIES`] bounds
    /// MEMOIZATION WIDTH (how many distinct `(name, args)` pairs the
    /// cache retains), this variant bounds OUTPUT SIZE (how many
    /// [`crate::ast::Sexp`] nodes a single macro `apply` may produce
    /// before the expander rejects rather than descending into a
    /// runaway tree). Fires on the canonical "expansion bomb"
    /// `(defmacro bomb (x) `(list ,x ,x ,x ,x ,x ,x))` — a well-defined
    /// but exponentially-productive macro whose depth stays small
    /// while the produced tree grows past any reasonable working-set
    /// budget. Pre-lift the runaway ran until the process exhausted
    /// its heap; post-lift the expander returns this typed rejection
    /// at the first `apply` output whose `node_count` exceeds the
    /// ceiling, with `macro_name` populated from the offending call,
    /// `size` populated from the observed node count, and `limit`
    /// populated from the enforced ceiling — so authoring surfaces
    /// (REPL, LSP, `tatara-check`) see BOTH halves at the variant
    /// boundary rather than substring-parsing free-form text.
    ///
    /// The three-field shape names BOTH the offending macro AND the
    /// observed size AND the configured ceiling. An LSP that wants to
    /// surface "your macro `bomb` produced a 512-node result past the
    /// 256-node ceiling; is it exponentially productive?" reads all
    /// three from the typed variant without substring parsing. Joins
    /// the [`Self::ExpansionDepthExceeded`] cohort so the
    /// [`Self::position`] projection routes both resource-ceiling
    /// rejections through the SAME `None` arm — the offending macro's
    /// byte offset is not what a runaway diagnostic anchors to; the
    /// (macro name, observed resource, ceiling) triple is.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the
    /// expansion-bomb failure mode becomes a first-class typed
    /// rejection at the expander boundary rather than a heap-exhausted
    /// abort that never reaches a `Result`. THEORY.md §II.1 invariant
    /// 1 — typed entry; every resource-ceiling failure mode the
    /// expander admits (recursion, memory, output size) is now a
    /// variant of `LispError`, closing the "runaway macro" surface at
    /// three RESOURCE-DIMENSION axes.
    #[error(
        "compile error in call to {macro_name}: macro expansion output size exceeded (size: {size}, limit: {limit})"
    )]
    ExpansionSizeExceeded {
        macro_name: String,
        size: usize,
        limit: usize,
    },
    /// `Expander::register_macro_def` rejected a macro definition whose
    /// body's [`crate::ast::Sexp::node_count`] exceeded the configured
    /// ceiling (`Expander::max_macro_body_size`, default
    /// `crate::macro_expand::DEFAULT_MAX_MACRO_BODY_SIZE`). Peer to
    /// [`Self::ExpansionSizeExceeded`] one PIPELINE-STAGE axis over:
    /// where `ExpansionSizeExceeded` bounds a macro `apply`'s OUTPUT
    /// size at EXPAND time (the runtime bomb — `(defmacro bomb (x) `(list ,x ,x ,x ,x))`
    /// producing a large tree from a small input), this variant bounds
    /// a macro's BODY size at REGISTER time (the authoring bomb —
    /// `(defmacro huge (x) `<template-of-N-million-nodes>)` whose
    /// storage in the `Expander::macros` table alone would exhaust
    /// memory before a single `apply` ran). Fires at
    /// [`crate::macro_expand::Expander::register_macro_def`] BEFORE
    /// `compile_template` walks the body or the entry lands in the
    /// macros table — a failed registration leaves both tables exactly
    /// as they were, matching the ordering `TemplateInvariant` /
    /// `UnboundTemplateVar` already enjoy on the compile-time reject
    /// path.
    ///
    /// The three-field shape names BOTH the offending macro AND the
    /// observed body size AND the configured ceiling — same shape as
    /// `ExpansionSizeExceeded` (its EXPAND-time peer) so authoring
    /// surfaces that route resource-ceiling rejections through one
    /// diagnostic channel bind to ONE structural pattern. `macro_name`
    /// is `String` because it comes from arbitrary source — the
    /// `(defmacro NAME …)` head at the moment the ceiling is hit;
    /// `size` is the observed `body.node_count()`; `limit` is the
    /// configured ceiling.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the
    /// authoring-bomb failure mode (a macro body large enough to hurt
    /// storage or template-compile time) becomes a first-class typed
    /// rejection at the REGISTRATION boundary. THEORY.md §II.1
    /// invariant 1 — typed entry; every resource-ceiling failure mode
    /// the expander admits (expand-time recursion, expand-time
    /// memoization width, expand-time output size, register-time body
    /// size) is now a variant of `LispError`, closing the "runaway
    /// macro" surface at FOUR RESOURCE-DIMENSION axes across TWO
    /// pipeline stages (register + expand).
    #[error(
        "compile error in defmacro {macro_name}: macro body size exceeded (size: {size}, limit: {limit})"
    )]
    MacroBodySizeExceeded {
        macro_name: String,
        size: usize,
        limit: usize,
    },
    /// `Expander::register_macro_def` rejected a fresh (non-overwrite)
    /// registration because the [`Expander::macros`] table already held
    /// `Expander::max_registered_macros` entries (default
    /// `crate::macro_expand::DEFAULT_MAX_REGISTERED_MACROS`). Peer to
    /// [`Self::MacroBodySizeExceeded`] one RESOURCE-DIMENSION axis over
    /// on the REGISTER-time surface — where `MacroBodySizeExceeded`
    /// bounds a single macro's BODY SIZE (the per-registration
    /// authoring bomb — one huge template landing in
    /// `Expander::macros`), this variant bounds the TABLE ENTRY COUNT
    /// (the cumulative registration bomb — a code-generator emitting
    /// unbounded `(defmacro fresh-N (x) `(list ,x))` heads at REGISTER
    /// time whose bodies each sit comfortably under
    /// `Expander::max_macro_body_size` yet collectively saturate
    /// process memory). Also peer to
    /// [`crate::macro_expand::DEFAULT_MAX_CACHE_ENTRIES`] one
    /// PIPELINE-STAGE axis over: where the cache-entries ceiling
    /// bounds EXPAND-time memoization width, this ceiling bounds
    /// REGISTER-time macro-table width — the two entry-count guards
    /// close the two pipeline stages symmetrically.
    ///
    /// A re-registration of an already-registered key (`self.macros`
    /// contains `macro_name` before the call) is an OVERWRITE, which
    /// does not grow the table and therefore never fires this variant
    /// — operators can redefine a macro at capacity without hitting
    /// the ceiling, and only FRESH keys are gated. The gate fires
    /// BEFORE [`compile_template`] walks the body or the entry lands
    /// in the [`crate::macro_expand::Expander::macros`] /
    /// `templates` tables — a failed registration leaves both tables
    /// exactly as they were, matching the pristine-tables invariant
    /// [`Self::MacroBodySizeExceeded`] holds on the body-size axis.
    ///
    /// The three-field shape names BOTH the offending macro AND the
    /// observed table count AND the configured ceiling — same shape
    /// as `MacroBodySizeExceeded` / `ExpansionSizeExceeded` (its
    /// pipeline-stage peers) so authoring surfaces that route
    /// resource-ceiling rejections through one diagnostic channel
    /// bind to ONE structural pattern. `macro_name` is `String`
    /// because it comes from arbitrary source — the `(defmacro NAME
    /// …)` head at the moment the ceiling is hit; `count` is the
    /// observed `self.macros.len()` (which equals `limit` at
    /// rejection in the common case, or exceeds it if `limit` was
    /// lowered mid-run past the current table size); `limit` is the
    /// configured ceiling.
    ///
    /// Joins the [`Self::ExpansionDepthExceeded`] cohort in
    /// [`Self::position`] so all four resource-ceiling rejections
    /// route through the SAME `None` arm — the offending macro's
    /// byte offset is not what a registration-bomb diagnostic
    /// anchors to; the (macro name, observed table count, ceiling)
    /// triple is.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the
    /// registration-bomb failure mode (unbounded macro-table growth)
    /// becomes a first-class typed rejection at the REGISTRATION
    /// boundary rather than an unhandled resource-drift that no
    /// `Result` witnesses. THEORY.md §II.1 invariant 1 — typed entry;
    /// every resource-ceiling failure mode the expander admits
    /// (expand-time recursion, expand-time memoization width,
    /// expand-time output size, register-time body size, register-
    /// time table width) is now a variant of `LispError`, closing the
    /// "runaway macro" surface at FIVE RESOURCE-DIMENSION axes across
    /// TWO pipeline stages — the register-time surface is now a
    /// two-dimensional (size × count) closure symmetric with the
    /// expand-time (depth + count + size) triple.
    #[error(
        "compile error in defmacro {macro_name}: registered macros count exceeded (count: {count}, limit: {limit})"
    )]
    RegisteredMacrosExceeded {
        macro_name: String,
        count: usize,
        limit: usize,
    },
    /// `Expander::register_macro_def` rejected a macro definition whose
    /// lambda-list arity — the [`crate::macro_expand::MacroParams::total_arity`]
    /// projection: `required.len() + optional.len() + rest.is_some() as
    /// usize` — exceeded the configured ceiling
    /// (`Expander::max_macro_arity`, default
    /// `crate::macro_expand::DEFAULT_MAX_MACRO_ARITY`). Peer to
    /// [`Self::MacroBodySizeExceeded`] one RESOURCE-DIMENSION axis over
    /// on the REGISTER-time surface — where `MacroBodySizeExceeded`
    /// bounds a per-registration BODY node count (the AST-nodes of the
    /// template a macro rewrites INTO), this variant bounds a
    /// per-registration PARAM slot count (the fresh symbols
    /// `compile_template`'s `,name`-index resolution AND
    /// `MacroParams::bind`'s per-index binder walk have to thread
    /// through on every call). Also peer to
    /// [`Self::RegisteredMacrosExceeded`] one RESOURCE-DIMENSION axis
    /// over on the REGISTER-time surface — where `RegisteredMacrosExceeded`
    /// bounds cumulative registration COUNT (the table-scoped
    /// resource), this variant bounds a per-registration PARAM-LIST
    /// WIDTH (the per-entry resource). Together the three
    /// REGISTER-time variants (this one +
    /// [`Self::MacroBodySizeExceeded`] + [`Self::RegisteredMacrosExceeded`])
    /// close the (per-body SIZE, per-body ARITY, per-table COUNT)
    /// three-corner surface. Fires at
    /// [`crate::macro_expand::Expander::register_macro_def`] BETWEEN the
    /// table-count gate (cheapest — O(1) `HashMap::len`) and the
    /// body-size gate (O(N) on `def.body.node_count()`) — the arity
    /// projection is a three-arm addition on `def.params` fields, no
    /// AST walk, so it sits BEFORE the body-size gate on the
    /// O(1)-first ordering of the REGISTER-time chain. A failed
    /// registration leaves BOTH `self.macros` AND `self.templates`
    /// tables exactly as they were, matching the pristine-tables
    /// invariant [`Self::MacroBodySizeExceeded`] and
    /// [`Self::RegisteredMacrosExceeded`] hold on their axes.
    ///
    /// Fires on the canonical arity-bomb `(defmacro huge (a-1 a-2 …
    /// a-N-million) `,a-1)` — a code-generator whose macro body sits
    /// at ONE node (`Sexp::Quasiquote` wrapping a single `,a-1`
    /// unquote is 3 nodes total, well under
    /// `Expander::max_macro_body_size`) yet whose param list carries
    /// millions of fresh names each subsequent call would have to
    /// walk in the per-index binder — a below-floor resource-drift
    /// the two prior REGISTER-time guards admit through because
    /// neither of them fires against the PER-REGISTRATION PARAM-LIST
    /// WIDTH.
    ///
    /// The three-field shape names BOTH the offending macro AND the
    /// observed arity AND the configured ceiling — same shape as
    /// `MacroBodySizeExceeded` / `ExpansionSizeExceeded` (its
    /// register-time peer and expand-time peer). `macro_name` is
    /// `String` because it comes from arbitrary source — the
    /// `(defmacro NAME …)` head at the moment the ceiling is hit;
    /// `arity` is the observed `def.params.total_arity()`; `limit` is
    /// the configured ceiling. An LSP that wants to surface "your
    /// macro `huge` declares 512 params past the 128-param ceiling;
    /// is it a `Vec<TypedEntity>`-unroller?" reads all three from the
    /// typed variant without substring parsing.
    ///
    /// Joins the [`Self::ExpansionDepthExceeded`] cohort in
    /// [`Self::position`] so all six resource-ceiling rejections
    /// route through the SAME `None` arm — the offending macro's byte
    /// offset is not what an arity-bomb diagnostic anchors to; the
    /// (macro name, observed arity, ceiling) triple is.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the
    /// arity-bomb failure mode (an unbounded per-registration param
    /// list) becomes a first-class typed rejection at the REGISTRATION
    /// boundary rather than an unhandled per-call binder-walk cost
    /// that no `Result` witnesses. THEORY.md §II.1 invariant 1 —
    /// typed entry; every resource-ceiling failure mode the expander
    /// admits (expand-time recursion, expand-time memoization width,
    /// expand-time output size, register-time body size, register-
    /// time table width, register-time param-list width) is now a
    /// variant of `LispError`, closing the "runaway macro" surface at
    /// SIX RESOURCE-DIMENSION axes across TWO pipeline stages — the
    /// register-time surface is now a three-dimensional (size × arity
    /// × count) closure symmetric with the expand-time (depth + count
    /// + size) triple.
    ///
    /// Frontier inspiration: Common Lisp's `LAMBDA-PARAMETERS-LIMIT`
    /// standard variable (CLHS §3.4.1) — the runtime-reflectable
    /// "upper exclusive bound on the number of parameters that may
    /// appear in a lambda list" every conforming implementation
    /// carries; this variant is the substrate's typed-Rust peer at
    /// compile time, translated through pleme-io primitives: a typed
    /// `LispError` variant rather than an implementation-defined
    /// condition, wired into the substrate's `Result` algebra at
    /// [`crate::macro_expand::Expander::register_macro_def`] rather
    /// than raised at eval time.
    #[error(
        "compile error in defmacro {macro_name}: macro arity exceeded (arity: {arity}, limit: {limit})"
    )]
    MacroArityExceeded {
        macro_name: String,
        arity: usize,
        limit: usize,
    },
}

/// Closed-set identifier for the (operation, stage) pair of a
/// `LispError::CompilerSpecIo` failure. Encodes the four reachable
/// pairs in `tatara-lisp/src/compiler_spec.rs`'s disk-persistence
/// surface — `realize_to_disk` × {serialize, write} ⊎ `load_from_disk`
/// × {read, deserialize} — as a typed enum, so invalid combinations
/// like `(load_from_disk, write)` or `(realize_to_disk, deserialize)`
/// are structurally unrepresentable rather than re-asserted at the
/// helper boundary via runtime string comparison.
///
/// Same posture as `MacroDefHead` in `macro_expand.rs`: the closed set
/// becomes a TYPE, not a `matches!` literal AND a triplicate
/// `match operation { ... }` projection inside each error helper. The
/// `operation()` / `label()` projections feed the
/// `LispError::CompilerSpecIo` Display rendering directly via the
/// `#[error(...)]` annotation; adding a new disk-persistence operation
/// (e.g., `load_from_str` for in-memory loads) requires extending this
/// enum, which rustc-enforces matching at every projection site.
///
/// Theory anchor: THEORY.md §V.1 — knowable platform; the closed set
/// of (operation, stage) pairs becomes a TYPE rather than a runtime
/// string-comparison-and-format dance. THEORY.md §VI.1 — generation
/// over composition; the typed enum lands the structural-completeness
/// floor for the disk-persistence surface, parallel to how
/// `MacroDefHead` lands the structural-completeness floor for the
/// macro-definition-head closed set.
///
/// `#[derive(tatara_closed_set::DeriveClosedSet)]` emits the
/// substrate-wide `impl tatara_closed_set::ClosedSet for CompilerSpecIoStage` +
/// the `pub struct UnknownCompilerSpecIoStage(pub String)`
/// parse-rejection carrier alongside the enum declaration. The
/// `#[closed_set(no_from_str)]` axis suppresses the auto-emitted
/// `FromStr` delegation — this enum's parse surface is the
/// compound `"{operation}: {label}"` key (a projection PAIR
/// rather than a single label), so the FromStr body below stays
/// hand-rolled. The `#[closed_set(generate_unknown)]` axis emits
/// the `UnknownCompilerSpecIoStage` carrier with the
/// auto-projected `"unknown compiler spec io stage: {0}"`
/// `#[error(...)]` annotation (matching the pre-lift wording
/// byte-for-byte via `pascal_to_spaced_lowercase`). `via` defaults
/// to `"label"` so the trait's `ClosedSet::label` projection
/// delegates to the inherent `label()` method — generic
/// consumers walking `ALL` and stringifying through the trait see
/// the singular labels (`"serialize"` / `"write"` / `"read"` /
/// `"deserialize"`) while the operator-facing `Display` rendering
/// stays at the compound `"{operation}: {label}"` shape via the
/// hand-rolled block.
#[derive(Debug, Clone, Copy, PartialEq, Eq, tatara_closed_set::DeriveClosedSet)]
#[closed_set(no_from_str, generate_unknown)]
pub enum CompilerSpecIoStage {
    /// `serde_json::to_string_pretty` of a `CompilerSpec` errored
    /// inside `realize_to_disk`.
    RealizeToDiskSerialize,
    /// `std::fs::write` of the serialized `CompilerSpec` JSON errored
    /// inside `realize_to_disk`.
    RealizeToDiskWrite,
    /// `std::fs::read_to_string` of the on-disk `CompilerSpec` JSON
    /// errored inside `load_from_disk`.
    LoadFromDiskRead,
    /// `serde_json::from_str` of the on-disk `CompilerSpec` JSON
    /// errored inside `load_from_disk`.
    LoadFromDiskDeserialize,
}

impl CompilerSpecIoStage {
    /// The canonical `&'static str` bytes returned by
    /// [`Self::operation`] for the [`Self::RealizeToDiskSerialize`]
    /// and [`Self::RealizeToDiskWrite`] variants — the
    /// `"realize_to_disk"` `{operation}` slot of the legacy
    /// `Compile`-shaped triple emitted by the public
    /// `CompilerSpec::realize_to_disk` entry point.
    ///
    /// Sibling posture to [`Self::LOAD_FROM_DISK_OPERATION`]
    /// (`"load_from_disk"`) on the same disk-persistence
    /// operation-label algebra, and to
    /// [`Self::REALIZE_TO_DISK_SERIALIZE_LABEL`] /
    /// [`Self::REALIZE_TO_DISK_WRITE_LABEL`] /
    /// [`Self::LOAD_FROM_DISK_READ_LABEL`] /
    /// [`Self::LOAD_FROM_DISK_DESERIALIZE_LABEL`] on the paired
    /// stage-label algebra — together the two axes span the
    /// (operation × stage) compound-key surface every
    /// [`CompilerSpecIoStage`] variant projects through.
    ///
    /// Pre-lift the same `"realize_to_disk"` bytes lived inline at
    /// the [`Self::operation`] match arm plus at the paired
    /// `compiler_spec_io_stage_operation_projects_realize_for_serialize_and_write`
    /// truth-table test plus at every `operation="realize_to_disk"`
    /// metric-label pin. Post-lift the (`RealizeToDiskSerialize |
    /// RealizeToDiskWrite`, canonical `&'static str`) pairing binds
    /// at ONE `pub const` on the typed [`CompilerSpecIoStage`]
    /// algebra — the pre-lift ≥2 PRIME-DIRECTIVE trigger becomes ONE
    /// typed source of truth. Consumers that need the
    /// `"realize_to_disk"` bytes at compile time (`disallowed_names`
    /// clippy config; static-dispatch metric-label tables in
    /// Prometheus recorders; `tatara-check` grep budgets) bind
    /// against `CompilerSpecIoStage::REALIZE_TO_DISK_OPERATION`
    /// rather than re-typing the literal.
    pub const REALIZE_TO_DISK_OPERATION: &'static str = "realize_to_disk";

    /// The canonical `&'static str` bytes returned by
    /// [`Self::operation`] for the [`Self::LoadFromDiskRead`] and
    /// [`Self::LoadFromDiskDeserialize`] variants — the
    /// `"load_from_disk"` `{operation}` slot of the legacy
    /// `Compile`-shaped triple emitted by the public
    /// `CompilerSpec::load_from_disk` entry point.
    ///
    /// Sibling posture to [`Self::REALIZE_TO_DISK_OPERATION`]
    /// (`"realize_to_disk"`) on the same disk-persistence
    /// operation-label algebra.
    pub const LOAD_FROM_DISK_OPERATION: &'static str = "load_from_disk";

    /// The closed set of four canonical `&'static str` operation
    /// labels — one per variant of [`Self::ALL`] in the SAME
    /// declaration order, so `Self::OPERATIONS[i] ==
    /// Self::ALL[i].operation()` element-wise (pinned by
    /// `compiler_spec_io_stage_operations_align_with_all_by_index`).
    ///
    /// Unlike [`Self::LABELS`] — whose four elements are pairwise
    /// distinct because each `label()` projection is bijective with
    /// its variant — [`Self::OPERATIONS`] contains DUPLICATES by
    /// construction: the operation projection is 2-of-2-to-2 (both
    /// `Realize…` variants share `"realize_to_disk"`, both `Load…`
    /// variants share `"load_from_disk"`), pinned by
    /// `compiler_spec_io_stage_operations_partition_all_two_ways`.
    /// This asymmetry between the two projection axes IS the load-
    /// bearing structural property of the (operation × label)
    /// compound-key surface — a naive lift that omits it would
    /// silently collapse the two-way partition on the operation
    /// axis by pinning distinctness where it doesn't hold.
    ///
    /// Sibling posture to [`Self::LABELS`] (`[&'static str; 4]`) on
    /// the same disk-persistence stage-label algebra —
    /// [`Self::OPERATIONS`] and [`Self::LABELS`] together span the
    /// (operation, label) compound-key rendering surface every
    /// [`Display`] / [`FromStr`] round-trip walks, with rustc's
    /// forced-arity `[&'static str; 4]` check on BOTH arrays
    /// enforcing that any future fifth pair (`LoadFromStrDeserialize`
    /// once an in-memory `load_from_str` lands, `RealizeToDiskAtomicReplace`
    /// if the realize path grows a crash-safe-rename stage) extends
    /// [`Self::ALL`] ONCE + [`Self::operation`] ONCE +
    /// [`Self::OPERATIONS`] ONCE + [`Self::label`] ONCE +
    /// [`Self::LABELS`] ONCE + adds ONE per-role label `pub const`
    /// — the (variant → (operation, label)) product surface picks
    /// up the extension mechanically at every downstream consumer.
    ///
    /// Future consumers that compose against [`Self::OPERATIONS`]:
    /// an LSP / REPL completion provider surfacing every legal
    /// operation label in an `operation=` metrics query bar
    /// ([`Self::OPERATIONS`] deduped is the ONE typed sweep over
    /// every legal disk-persistence entry-point name); a
    /// `tatara-check` coverage assertion (every workspace `.lisp`
    /// file's `CompilerSpec` rejection must classify to some
    /// entry of [`Self::OPERATIONS`]); a Sekiban audit-trail metric
    /// jointly labeled by [`Self::operation`] × [`Self::label`]
    /// whose `operation=` label set IS the deduped
    /// [`Self::OPERATIONS`] (e.g.
    /// `tatara_lisp_compiler_spec_io_total{operation="realize_to_disk",
    /// stage="serialize"}`).
    pub const OPERATIONS: [&'static str; 4] = [
        Self::REALIZE_TO_DISK_OPERATION,
        Self::REALIZE_TO_DISK_OPERATION,
        Self::LOAD_FROM_DISK_OPERATION,
        Self::LOAD_FROM_DISK_OPERATION,
    ];

    /// The public entry point's name — the `{form}` slot of the legacy
    /// `Compile`-shaped diagnostic. `realize_to_disk` for the
    /// serialize / write variants; `load_from_disk` for the read /
    /// deserialize variants.
    ///
    /// Body routes each arm through the per-role
    /// [`Self::REALIZE_TO_DISK_OPERATION`] /
    /// [`Self::LOAD_FROM_DISK_OPERATION`] `pub const` so the two
    /// canonical `&'static str` operation labels live at ONE
    /// `pub const` per role rather than at TWO sites (the per-role
    /// `pub const` AND an inline arm literal). Sibling posture to
    /// [`Self::label`]'s arms routing through the per-role
    /// [`Self::REALIZE_TO_DISK_SERIALIZE_LABEL`] /
    /// [`Self::REALIZE_TO_DISK_WRITE_LABEL`] /
    /// [`Self::LOAD_FROM_DISK_READ_LABEL`] /
    /// [`Self::LOAD_FROM_DISK_DESERIALIZE_LABEL`] constants on the
    /// paired stage-label algebra.
    #[must_use]
    pub fn operation(self) -> &'static str {
        match self {
            Self::RealizeToDiskSerialize | Self::RealizeToDiskWrite => {
                Self::REALIZE_TO_DISK_OPERATION
            }
            Self::LoadFromDiskRead | Self::LoadFromDiskDeserialize => {
                Self::LOAD_FROM_DISK_OPERATION
            }
        }
    }

    /// The canonical `&'static str` bytes returned by
    /// [`Self::label`] for the [`Self::RealizeToDiskSerialize`]
    /// variant — the `"serialize"` `{stage}` slot of the legacy
    /// `"{stage}: {error}"` message shape emitted when
    /// `serde_json::to_string_pretty` errors inside `realize_to_disk`.
    /// Sibling posture to [`Self::REALIZE_TO_DISK_WRITE_LABEL`]
    /// (`"write"`), [`Self::LOAD_FROM_DISK_READ_LABEL`] (`"read"`),
    /// and [`Self::LOAD_FROM_DISK_DESERIALIZE_LABEL`]
    /// (`"deserialize"`) on the same disk-persistence stage-label
    /// algebra.
    ///
    /// Pre-lift the same `"serialize"` bytes lived inline at the
    /// [`Self::label`] match arm plus at the paired
    /// `compiler_spec_io_stage_label_projects_canonical_stage_strings`
    /// truth-table test plus at the `stage="serialize"` metric-label
    /// pin. Post-lift the (`RealizeToDiskSerialize` variant, canonical
    /// `&'static str`) pairing binds at ONE `pub const` on the typed
    /// [`CompilerSpecIoStage`] algebra — the pre-lift ≥2 PRIME-
    /// DIRECTIVE trigger becomes ONE typed source of truth. Consumers
    /// that need the `"serialize"` bytes at compile time
    /// (`disallowed_names` clippy config; static-dispatch metric-label
    /// tables in Prometheus recorders; `tatara-check` grep budgets)
    /// bind against `CompilerSpecIoStage::REALIZE_TO_DISK_SERIALIZE_LABEL`
    /// rather than re-typing the literal.
    pub const REALIZE_TO_DISK_SERIALIZE_LABEL: &'static str = "serialize";

    /// The canonical `&'static str` bytes returned by
    /// [`Self::label`] for the [`Self::RealizeToDiskWrite`] variant —
    /// the `"write"` `{stage}` slot of the legacy `"{stage}: {error}"`
    /// message shape emitted when `std::fs::write` of the serialized
    /// `CompilerSpec` JSON errors inside `realize_to_disk`. Sibling
    /// posture to [`Self::REALIZE_TO_DISK_SERIALIZE_LABEL`]
    /// (`"serialize"`), [`Self::LOAD_FROM_DISK_READ_LABEL`]
    /// (`"read"`), and [`Self::LOAD_FROM_DISK_DESERIALIZE_LABEL`]
    /// (`"deserialize"`) on the same disk-persistence stage-label
    /// algebra.
    pub const REALIZE_TO_DISK_WRITE_LABEL: &'static str = "write";

    /// The canonical `&'static str` bytes returned by
    /// [`Self::label`] for the [`Self::LoadFromDiskRead`] variant —
    /// the `"read"` `{stage}` slot of the legacy `"{stage}: {error}"`
    /// message shape emitted when `std::fs::read_to_string` of the
    /// on-disk `CompilerSpec` JSON errors inside `load_from_disk`.
    /// Sibling posture to [`Self::REALIZE_TO_DISK_SERIALIZE_LABEL`]
    /// (`"serialize"`), [`Self::REALIZE_TO_DISK_WRITE_LABEL`]
    /// (`"write"`), and [`Self::LOAD_FROM_DISK_DESERIALIZE_LABEL`]
    /// (`"deserialize"`) on the same disk-persistence stage-label
    /// algebra.
    pub const LOAD_FROM_DISK_READ_LABEL: &'static str = "read";

    /// The canonical `&'static str` bytes returned by
    /// [`Self::label`] for the [`Self::LoadFromDiskDeserialize`]
    /// variant — the `"deserialize"` `{stage}` slot of the legacy
    /// `"{stage}: {error}"` message shape emitted when
    /// `serde_json::from_str` of the on-disk `CompilerSpec` JSON
    /// errors inside `load_from_disk`. Sibling posture to
    /// [`Self::REALIZE_TO_DISK_SERIALIZE_LABEL`] (`"serialize"`),
    /// [`Self::REALIZE_TO_DISK_WRITE_LABEL`] (`"write"`), and
    /// [`Self::LOAD_FROM_DISK_READ_LABEL`] (`"read"`) on the same
    /// disk-persistence stage-label algebra.
    pub const LOAD_FROM_DISK_DESERIALIZE_LABEL: &'static str = "deserialize";

    /// The closed set of four canonical `&'static str` stage labels —
    /// the [`Self::REALIZE_TO_DISK_SERIALIZE_LABEL`] (`"serialize"`)
    /// `serde_json::to_string_pretty` failure followed by the
    /// [`Self::REALIZE_TO_DISK_WRITE_LABEL`] (`"write"`)
    /// `std::fs::write` failure followed by the
    /// [`Self::LOAD_FROM_DISK_READ_LABEL`] (`"read"`)
    /// `std::fs::read_to_string` failure followed by the
    /// [`Self::LOAD_FROM_DISK_DESERIALIZE_LABEL`] (`"deserialize"`)
    /// `serde_json::from_str` failure. Canonical declaration order
    /// matches [`Self::ALL`] so `Self::LABELS[i] == Self::ALL[i].label()`
    /// element-wise — pinned by
    /// `compiler_spec_io_stage_labels_align_with_all_by_index`.
    ///
    /// Sibling posture to [`KwargPathKind::LABELS`]
    /// (`[&'static str; 3]`), [`ExpectedKwargShape::LABELS`]
    /// (`[&'static str; 7]`), and [`MacroDefHead::KEYWORDS`]
    /// (`[&'static str; 3]`) — every closed-set algebra now pins its
    /// label-projection ALL array at the declaration site via a
    /// forced-arity `[&'static str; N]` array whose length fails
    /// compilation if a new variant lands without being added to the
    /// set. Adding a hypothetical fifth pair (a
    /// `LoadFromStrDeserialize` once an in-memory `load_from_str`
    /// lands, a `RealizeToDiskAtomicReplace` if the realize path grows
    /// a crash-safe-rename stage) extends [`Self::ALL`] ONCE +
    /// [`Self::label`] ONCE + [`Self::LABELS`] ONCE + adds ONE
    /// per-role label `pub const` — rustc's forced-arity check on the
    /// `[Self; N]` array + `[&'static str; N]` array pair enforces
    /// every downstream consumer picks up the extension mechanically.
    ///
    /// Future consumers that compose against [`Self::LABELS`]: an
    /// LSP / REPL completion provider surfacing every legal stage
    /// label in a `stage=` metrics query bar (`Self::LABELS.iter()` is
    /// the ONE typed sweep over every legal disk-persistence stage
    /// label), a `tatara-check` coverage assertion (every workspace
    /// `.lisp` file's `CompilerSpec` rejection must classify to some
    /// entry of `Self::LABELS`), a Sekiban audit-trail metric jointly
    /// labeled by [`Self::label`] whose metric-label set IS
    /// `Self::LABELS` (e.g.
    /// `tatara_lisp_compiler_spec_io_total{operation="realize_to_disk",
    /// stage="serialize"}`).
    pub const LABELS: [&'static str; 4] = [
        Self::REALIZE_TO_DISK_SERIALIZE_LABEL,
        Self::REALIZE_TO_DISK_WRITE_LABEL,
        Self::LOAD_FROM_DISK_READ_LABEL,
        Self::LOAD_FROM_DISK_DESERIALIZE_LABEL,
    ];

    /// The step within the operation that failed — the `{stage}` slot
    /// of the legacy `"{stage}: {error}"` message shape. One of
    /// `"serialize"`, `"write"`, `"read"`, `"deserialize"`.
    ///
    /// Body routes each arm through the per-role
    /// [`Self::REALIZE_TO_DISK_SERIALIZE_LABEL`] /
    /// [`Self::REALIZE_TO_DISK_WRITE_LABEL`] /
    /// [`Self::LOAD_FROM_DISK_READ_LABEL`] /
    /// [`Self::LOAD_FROM_DISK_DESERIALIZE_LABEL`] `pub const` so the
    /// four canonical `&'static str` labels live at ONE `pub const`
    /// per variant rather than at TWO sites (the per-role `pub const`
    /// AND an inline arm literal). Sibling posture to
    /// [`KwargPathKind::label`]'s arms routing through the per-role
    /// [`KwargPathKind::NAMED_LABEL`] / [`KwargPathKind::ITEM_LABEL`]
    /// / [`KwargPathKind::SLOT_LABEL`] constants, and to
    /// [`ExpectedKwargShape::label`]'s arms routing through
    /// [`ExpectedKwargShape::KEYWORD_LABEL`] etc.
    #[must_use]
    pub fn label(self) -> &'static str {
        match self {
            Self::RealizeToDiskSerialize => Self::REALIZE_TO_DISK_SERIALIZE_LABEL,
            Self::RealizeToDiskWrite => Self::REALIZE_TO_DISK_WRITE_LABEL,
            Self::LoadFromDiskRead => Self::LOAD_FROM_DISK_READ_LABEL,
            Self::LoadFromDiskDeserialize => Self::LOAD_FROM_DISK_DESERIALIZE_LABEL,
        }
    }

    /// Closed-set enumeration of every reachable [`CompilerSpecIoStage`]
    /// variant — the four (operation, label) pairs the disk-persistence
    /// surface emits (`realize_to_disk` × {`serialize`, `write`} ⊎
    /// `load_from_disk` × {`read`, `deserialize`}). The `[Self; 4]`
    /// array literal forces the arity so a fifth pair — a hypothetical
    /// `LoadFromStrDeserialize` once an in-memory `load_from_str` lands,
    /// or a `RealizeToDiskAtomicReplace` if the realize path grows a
    /// crash-safe-rename stage — cannot be added at the type without
    /// extending this constant.
    ///
    /// Sibling closed-set lift to every other typed-shape enum the
    /// substrate carries: this crate's own [`ExpectedKwargShape::ALL`]
    /// (the seven reachable expected-kwarg shapes — single-projection
    /// closed set), [`SexpShape::ALL`] (the twelve reachable observed-
    /// Sexp shapes — single-projection closed set), [`MacroDefHead::ALL`]
    /// (the three reachable macro-definition heads), [`UnquoteForm::ALL`]
    /// (the two reachable template-marker forms),
    /// [`crate::ast::AtomKind::ALL`], [`crate::ast::QuoteForm::ALL`], and
    /// across the workspace `ConditionKind::ALL`, `ProcessPhase::ALL`,
    /// `RequestorKind::ALL`, `ReceiptKind::ALL`, … . What's distinct here:
    /// this is the substrate's first *compound-key* closed set — the
    /// reachable identity is the PAIR `(operation, label)`, not either
    /// projection alone (`operation` partitions ALL into 2-of-2 halves,
    /// `label` is bijective with ALL by accident of the current four
    /// variants). [`FromStr`] keys on the compound rendering so the
    /// cross-product reachability constraint — only 4 of the 8
    /// conceivable `(operation, label)` pairs are reachable, e.g.
    /// `(load_from_disk, write)` is structurally absurd — becomes a
    /// load-bearing property of the parse boundary, not a runtime
    /// re-assertion at the helper.
    ///
    /// Future consumers that compose against [`Self::ALL`]: LSP / REPL
    /// completion for the operator-facing rendered (operation, label)
    /// pairs (every `compile error in X: Y: ...` substring in
    /// `LispError::CompilerSpecIo` keys on this set's projection through
    /// [`Self::operation`] and [`Self::label`]); `tatara-check` coverage
    /// assertions over which disk-persistence stages reach a
    /// [`LispError::CompilerSpecIo`] site at all — the typed sweep
    /// replaces a hand-rolled `match`-over-string vocabulary at consumer
    /// boundaries; any future audit-trail metric jointly labeled by
    /// [`Self::operation`] × [`Self::label`] (e.g.
    /// `tatara_lisp_compiler_spec_io_total{operation="realize_to_disk",
    /// stage="serialize"}`) — the metric label set IS [`Self::ALL`]
    /// mapped through the projection pair.
    pub const ALL: [Self; 4] = [
        Self::RealizeToDiskSerialize,
        Self::RealizeToDiskWrite,
        Self::LoadFromDiskRead,
        Self::LoadFromDiskDeserialize,
    ];

    /// The canonical `&'static str` bytes that separate the
    /// [`Self::operation`] slot from the [`Self::label`] slot in the
    /// compound-key rendering `"{operation}{SEP}{label}"` — literally
    /// `": "` (a colon followed by ONE ASCII space, no more, no less).
    /// This is the sole load-bearing separator on the compound-key
    /// projection axis: [`Display`] composes through it, [`FromStr`]
    /// splits on it, and every doc-comment reference to the compound
    /// shape (`"realize_to_disk: read"`, `"load_from_disk: write"`, …)
    /// silently threads the same three bytes.
    ///
    /// Pre-lift the same `": "` bytes lived inline at three sites — the
    /// [`Display`] `write!` format string, the [`FromStr`] `split_once`
    /// argument, and two doc-comment references — with no typed source
    /// of truth binding them together. Post-lift the (`Self`, compound-
    /// key separator bytes) pairing binds at ONE `pub const` on the
    /// typed [`CompilerSpecIoStage`] algebra — the pre-lift ≥2 PRIME-
    /// DIRECTIVE trigger becomes ONE typed source of truth. A future
    /// refactor that changes the separator (e.g. to `" — "` on the way
    /// to a richer diagnostic surface) touches ONE `pub const` rather
    /// than THREE unrelated inline literals; a future refactor that
    /// silently drifts one call site (e.g. leaves `Display` at `": "`
    /// but drops the space from `split_once` after a `clippy::single_char_pattern`
    /// suggestion) fails the round-trip test loudly at the parse
    /// boundary rather than silently bifurcating the compound key.
    ///
    /// Sibling posture to [`Self::REALIZE_TO_DISK_OPERATION`] +
    /// [`Self::LOAD_FROM_DISK_OPERATION`] (operation-slot bytes) and
    /// [`Self::REALIZE_TO_DISK_SERIALIZE_LABEL`] etc. (label-slot bytes)
    /// on the same disk-persistence compound-key algebra — the three
    /// canonical slot-byte families together (operation × separator ×
    /// label) span the every-byte-of-the-compound-key surface; no
    /// character of a rendered `CompilerSpecIoStage` compound key lives
    /// at more than ONE typed constant on the algebra.
    ///
    /// Distinct from the substrate-wide `unknown {SET_LABEL}: {input}`
    /// separator in [`crate::closed_set`]'s well-formed-carrier
    /// rendering: those bytes happen to be identical (`": "`) but live
    /// at a distinct algebraic level (the ClosedSet trait's error-
    /// carrier composition, not the per-type compound-key surface).
    /// Two distinct separators that happen to be equal bytes; a future
    /// diagnostic-surface change that touches one must not touch the
    /// other by accident, so keeping them at separate `pub const` /
    /// hand-composed sites is load-bearing structure, not duplication.
    ///
    /// Consumers that need the compound-key separator bytes at compile
    /// time bind against `CompilerSpecIoStage::COMPOUND_KEY_SEPARATOR`
    /// rather than re-typing the literal — this includes the
    /// hand-rolled [`Display`] / [`FromStr`] pair below and any future
    /// LSP / REPL diagnostic-substring extractor that needs to
    /// `rsplit_once(CompilerSpecIoStage::COMPOUND_KEY_SEPARATOR)` a
    /// captured operator-facing `"compile error in {operation}: {label}:
    /// {message}"` prefix.
    pub const COMPOUND_KEY_SEPARATOR: &'static str = ": ";
}

/// Standalone rendering of a [`CompilerSpecIoStage`] in the canonical
/// compound `"{operation}{SEP}{label}"` form — byte-for-byte the same
/// substring that lands inside the
/// [`LispError::CompilerSpecIo`] diagnostic between `"compile error in
/// "` and `": {message}"`, where `{SEP}` is
/// [`CompilerSpecIoStage::COMPOUND_KEY_SEPARATOR`] (`": "`). Pinning
/// Display to the compound form means a consumer that extracts the
/// (operation, label) prefix from a rendered diagnostic — for example
/// by `s.strip_prefix("compile error in ")
/// .and_then(|t| t.rsplit_once(CompilerSpecIoStage::COMPOUND_KEY_SEPARATOR))`
/// — round-trips the captured substring through [`FromStr`] back into
/// the typed variant exactly.
///
/// The compound form is load-bearing: `label` alone would be bijective
/// with the current four variants (`"serialize"` / `"write"` / `"read"`
/// / `"deserialize"`) but a future fifth variant like
/// `LoadFromStrDeserialize` would collide with `LoadFromDiskDeserialize`
/// on `label` alone. Display-ing the compound key means the bijection
/// survives the closed-set extension without a label-disambiguation
/// dance.
///
/// The body composes through [`CompilerSpecIoStage::COMPOUND_KEY_SEPARATOR`]
/// so the exact separator bytes bind at ONE `pub const` on the typed
/// algebra rather than at TWO sites (the [`Display`] `write!` format
/// string AND the [`FromStr`] `split_once` argument) — a lift symmetric
/// to how [`Self::operation`] and [`Self::label`] route through their
/// per-role slot-byte constants.
impl std::fmt::Display for CompilerSpecIoStage {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.operation())?;
        f.write_str(Self::COMPOUND_KEY_SEPARATOR)?;
        f.write_str(self.label())
    }
}

/// Decode a canonical [`CompilerSpecIoStage`] compound key
/// `"{operation}: {label}"` back into the typed variant — `Ok(stage)`
/// when the input matches the [`Display`] rendering of one of the four
/// variants in [`CompilerSpecIoStage::ALL`] byte-for-byte (case-sensitive
/// because the labels are the rendered diagnostic surface and any case
/// drift would silently bifurcate the round-trip), and
/// [`Err(UnknownCompilerSpecIoStage)`] for every other string.
///
/// Crucially the decode REJECTS the four conceivable-but-unreachable
/// cross-product pairs — `"realize_to_disk: read"`,
/// `"realize_to_disk: deserialize"`, `"load_from_disk: serialize"`,
/// `"load_from_disk: write"` — because none of those pairs appears in
/// [`CompilerSpecIoStage::ALL`]. The cross-product reachability
/// constraint, previously a Code-level invariant (only the four call
/// sites in `compiler_spec.rs` construct stages, each construction
/// site pairs the correct operation with the correct stage), becomes
/// a type-level invariant: the parse boundary refuses to deserialize
/// an unreachable pair.
///
/// Partial keys — `"serialize"` alone, `"realize_to_disk"` alone — also
/// reject. The [`CompilerSpecIoStage::COMPOUND_KEY_SEPARATOR`] (`": "`)
/// bytes must appear at least once for the decode to consider any
/// variant; otherwise the diagnostic substring shape isn't a compound
/// key at all.
///
/// Round-trip invariant pinned by
/// `compiler_spec_io_stage_compound_key_round_trips_through_from_str`:
/// for every variant `s` in [`CompilerSpecIoStage::ALL`],
/// `s.to_string().parse() == Ok(s)`. The compound-rendering site is
/// singular (the [`Display`] impl projects through [`Self::operation`]
/// and [`Self::label`]) so the round-trip is the only way the typed
/// surface and the rendered diagnostic literal can drift apart —
/// pinning it here means they cannot. Mirror of every sibling
/// closed-set round-trip in the workspace ([`SexpShape::from_str`],
/// [`ExpectedKwargShape::from_str`], [`MacroDefHead::from_str`],
/// [`UnquoteForm::from_str`], `RequestorKind::from_str`,
/// `ReceiptKind::from_str`, `ConditionKind::from_str`,
/// `ProcessPhase::from_str`, …) — the difference is the compound-key
/// shape rather than a single label, which sharpens the closed-set
/// constraint from "cardinality matches the variant count" to
/// "cardinality matches the variant count AND the projection product
/// is partial, not total."
impl std::str::FromStr for CompilerSpecIoStage {
    type Err = UnknownCompilerSpecIoStage;
    fn from_str(s: &str) -> std::result::Result<Self, Self::Err> {
        let Some((op, lbl)) = s.split_once(Self::COMPOUND_KEY_SEPARATOR) else {
            return Err(UnknownCompilerSpecIoStage(s.to_owned()));
        };
        for stage in Self::ALL {
            if op == stage.operation() && lbl == stage.label() {
                return Ok(stage);
            }
        }
        Err(UnknownCompilerSpecIoStage(s.to_owned()))
    }
}

// `pub struct UnknownCompilerSpecIoStage(pub String)` is generated by
// `#[derive(tatara_closed_set::DeriveClosedSet)]` on the `CompilerSpecIoStage`
// declaration above through `#[closed_set(generate_unknown)]`. The
// auto-projected `#[error("unknown compiler spec io stage: {0}")]`
// annotation (via `pascal_to_spaced_lowercase("CompilerSpecIoStage")` →
// `"compiler spec io stage"` — pinned by
// `pascal_to_spaced_lowercase_tests::contiguous_uppercase_runs_collapse_to_lowercase_without_inner_spaces`)
// matches the pre-lift hand-rolled wording byte-for-byte; LSP / REPL
// substring-matching `"unknown compiler spec io stage: "` continues to
// filter this rejection class without binding to the specific input.
// The substrate-wide carrier shape (`Debug + Clone + PartialEq + Eq +
// thiserror::Error` derives, `pub struct UnknownX(pub String)` with the
// `#[error("unknown <thing>: {0}")]` annotation) — symmetric to every
// sibling `Unknown*` error in the workspace
// (`UnknownExpectedKwargShape`, `UnknownSexpShape`,
// `UnknownMacroDefHead`, `UnknownUnquoteForm`,
// `crate::ast::UnknownAtomKind`, `crate::ast::UnknownQuoteForm`,
// `tatara_process::allocation::UnknownRequestorKind`,
// `tatara_process::receipt::UnknownReceiptKind`,
// `tatara_process::phase::UnknownPhase`,
// `tatara_process::boundary::UnknownConditionKind`,
// `tatara_process::lifetime::UnknownTeardownPolicy`, …) — emits from
// the derive rather than from a per-declaration hand-roll.

/// Closed-set identifier for a bytecode-runtime invariant violation
/// surfaced by `macro_expand.rs::apply_compiled`. Encodes the four
/// reachable failure modes — Subst with an out-of-bounds param index,
/// Splice with an out-of-bounds param index, EndList against an empty
/// stack, and a final pop yielding no value — as a typed enum, so the
/// invalid combination of "stack-gate kind with an op-index payload"
/// (e.g. `EndListEmptyStack` carrying a `usize`) is structurally
/// unrepresentable: the index payload lives INSIDE the variants that
/// actually carry one (`SubstBadIndex(usize)` / `SpliceBadIndex(usize)`).
///
/// Same posture as `CompilerSpecIoStage`: the closed set becomes a
/// TYPE, not a free-form `message: String` slot inside the helper. The
/// `message()` projection feeds the `LispError::TemplateInvariant`
/// Display rendering directly via the `#[error(...)]` annotation;
/// adding a new bytecode-runtime invariant (e.g. a future `WrongOpcode`
/// gate that names a malformed bytecode header at the type level)
/// requires extending this enum, which rustc-enforces matching at the
/// projection site.
///
/// Theory anchor: THEORY.md §V.1 — knowable platform; the closed set
/// of bytecode-invariant failure modes becomes a TYPE rather than a
/// runtime string-format dance. THEORY.md §VI.1 — generation over
/// composition; the typed enum lands the structural-completeness floor
/// for the bytecode-runtime surface, parallel to how `CompilerSpecIoStage`
/// lands the structural-completeness floor for the disk-persistence
/// surface.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TemplateInvariantKind {
    /// `TemplateOp::Subst(idx)` referenced a param index that
    /// `args_by_index.get(idx)` returned `None` for — the compiled
    /// bytecode referenced an out-of-bounds required-param slot.
    SubstBadIndex(usize),
    /// `TemplateOp::Splice(idx)` referenced a param index that
    /// `args_by_index.get(idx)` returned `None` for — the compiled
    /// bytecode referenced an out-of-bounds splice-target param slot.
    SpliceBadIndex(usize),
    /// `TemplateOp::EndList` ran against an empty runtime stack —
    /// `stack.pop()` returned `None`, meaning the compiled bytecode
    /// emitted an `EndList` without a matching `BeginList`. The stack
    /// is the proof artifact; an unbalanced stack is the bytecode
    /// compiler's proof obligation having been silently dropped.
    EndListEmptyStack,
    /// The final `stack.pop()` after the bytecode loop yielded `None`
    /// — the compiled bytecode produced no value at all (an empty op
    /// list, or a body that consumes its own output). Distinct from
    /// `EndListEmptyStack`: that fires mid-loop on an explicit
    /// `EndList`; this fires after the loop on the implicit final
    /// pop.
    FinalNoValue,
}

impl TemplateInvariantKind {
    /// Canonical `&'static str` bytes for [`Self::EndListEmptyStack`] —
    /// the mid-loop stack-gate invariant fired inside the bytecode
    /// runtime when `TemplateOp::EndList` runs against an empty stack.
    /// Per-role peer of `Self::EndListEmptyStack` on the STATIC 2-of-4
    /// subset carving of the four-arm closed set.
    ///
    /// Pre-lift the same `"compiled template: EndList with empty stack"`
    /// bytes lived inline at [`Self::message`]'s match arm plus at the
    /// truth-table test `template_invariant_kind_message_for_endlist_empty_stack`
    /// — the ≥2 PRIME-DIRECTIVE trigger. Post-lift the
    /// (`EndListEmptyStack` variant, canonical `&'static str`) pairing
    /// binds at ONE `pub const` on the typed [`TemplateInvariantKind`]
    /// algebra: the [`Self::message`] arm routes through this constant
    /// via [`Self::message_static`], the peer [`Self::STATIC_MESSAGES`]
    /// array composes it into a forced-arity `[&'static str; 2]` at ONE
    /// site, and every downstream consumer that pins the exact bytes
    /// (an LSP quick-fix that surfaces the invariant-name inline, a
    /// Sekiban audit-trail metric labeled by the invariant identity)
    /// binds through here.
    ///
    /// Sibling posture to the closed set of per-role canonical
    /// `pub const` bytes on the substrate's other closed-set outer
    /// algebras: [`MacroDefHead::DEFMACRO_KEYWORD`] (`"defmacro"`),
    /// [`CompilerSpecIoStage::REALIZE_TO_DISK_OPERATION`] (`"realize
    /// to disk"`), [`UnquoteForm::UNQUOTE_LABEL`] (`","`),
    /// [`SexpShape::NIL_LABEL`] (`"nil"`). Each closed-set enum in the
    /// substrate now names its canonical per-variant bytes at ONE
    /// `pub const` per role rather than at TWO sites (the projection-
    /// method arm AND at least one truth-table test).
    pub const END_LIST_EMPTY_STACK_MESSAGE: &'static str =
        "compiled template: EndList with empty stack";

    /// Canonical `&'static str` bytes for [`Self::FinalNoValue`] — the
    /// post-loop final-pop invariant fired after the bytecode runtime
    /// exhausts its op stream and the final `stack.pop()` yields no
    /// value. Per-role peer of `Self::FinalNoValue` on the STATIC
    /// 2-of-4 subset carving of the four-arm closed set.
    ///
    /// Pre-lift the same `"compiled template produced no value"` bytes
    /// lived inline at [`Self::message`]'s match arm plus at the truth-
    /// table test `template_invariant_kind_message_for_final_no_value`.
    /// Post-lift the (`FinalNoValue` variant, canonical `&'static str`)
    /// pairing binds at ONE `pub const` on the typed
    /// [`TemplateInvariantKind`] algebra: the [`Self::message`] arm
    /// routes through this constant via [`Self::message_static`], the
    /// peer [`Self::STATIC_MESSAGES`] array composes it into a forced-
    /// arity `[&'static str; 2]` at ONE site.
    ///
    /// Sibling posture to [`Self::END_LIST_EMPTY_STACK_MESSAGE`] on
    /// the same STATIC 2-of-4 subset carving — the dynamic arms
    /// (`SubstBadIndex(usize)` / `SpliceBadIndex(usize)`) format their
    /// `usize` payload into the message and cannot bind to a
    /// `&'static str` on this axis. The 2-of-4 STATIC subset is where
    /// the `Option<&'static str>` typed subset projection
    /// [`Self::message_static`] lives.
    pub const FINAL_NO_VALUE_MESSAGE: &'static str = "compiled template produced no value";

    /// The closed set of two canonical `&'static str` bytes on the
    /// STATIC 2-of-4 subset carving of [`TemplateInvariantKind`]'s
    /// four-arm closed set — the [`Self::END_LIST_EMPTY_STACK_MESSAGE`]
    /// (`"compiled template: EndList with empty stack"`) mid-loop
    /// stack-gate invariant followed by the [`Self::FINAL_NO_VALUE_MESSAGE`]
    /// (`"compiled template produced no value"`) post-loop final-pop
    /// invariant. Canonical declaration order matches
    /// [`Self::message_static`]'s arm order so
    /// `Self::STATIC_MESSAGES[0] == Self::message_static(Self::EndListEmptyStack).unwrap()`
    /// and `Self::STATIC_MESSAGES[1] == Self::message_static(Self::FinalNoValue).unwrap()`
    /// element-wise — pinned by
    /// `template_invariant_kind_static_messages_align_with_message_static_by_index`.
    ///
    /// Sibling posture to every other closed-set STATIC-subset ALL
    /// array on the substrate: peer 2-of-4 carving to
    /// [`OptionalParamMalformedReason`]'s hypothetical STATIC subset
    /// (`EmptyList` / `MissingDefault` / `NonSymbolName` — a 3-of-4
    /// static carving on the sibling optional-section-malformed
    /// surface), 3-of-3 total to [`KwargPathKind::LABELS`],
    /// [`MacroDefHead::KEYWORDS`], and 7-of-7 to
    /// [`ExpectedKwargShape::LABELS`]. Adding a hypothetical fifth
    /// static invariant (e.g. `WrongOpcode` — a bytecode-header gate
    /// naming a malformed bytecode header at the type level with a
    /// `&'static str` message payload) extends [`Self::STATIC_MESSAGES`]
    /// ONCE + [`Self::message_static`]'s arms ONCE + adds ONE per-role
    /// message `pub const` — rustc's forced-arity check on the
    /// `[&'static str; N]` array fails compilation if the array grows
    /// without the projection method being extended.
    ///
    /// Future consumers that compose against [`Self::STATIC_MESSAGES`]:
    /// an LSP quick-fix that surfaces the static-message vocabulary
    /// inline at every `LispError::TemplateInvariant` diagnostic
    /// (`Self::STATIC_MESSAGES.iter()` is the ONE typed sweep over
    /// every legal static bytecode-invariant message); a
    /// `tatara-check` coverage assertion (every workspace `.lisp`
    /// file's macro-body must expand without producing a
    /// `TemplateInvariantKind` rejection whose message lies OUTSIDE
    /// [`Self::STATIC_MESSAGES`] ∪ formatted-dynamic-arm messages —
    /// the typed sweep replaces the per-call-site vocabulary of two
    /// `&'static str` literals); a Sekiban audit-trail metric jointly
    /// labeled by the STATIC-subset invariant message (e.g.
    /// `tatara_lisp_template_invariant_total{message="compiled
    /// template produced no value"}` — the metric label set on the
    /// STATIC subset IS [`Self::STATIC_MESSAGES`]).
    pub const STATIC_MESSAGES: [&'static str; 2] = [
        Self::END_LIST_EMPTY_STACK_MESSAGE,
        Self::FINAL_NO_VALUE_MESSAGE,
    ];

    /// Canonical `&'static str` descriptor bytes for the
    /// [`Self::SubstBadIndex`] rejection — the noun-slot bytes `"param"`
    /// naming the required-param slot the compiled bytecode indexed
    /// out-of-bounds. Per-role peer of [`Self::SubstBadIndex`] on the
    /// DYNAMIC 2-of-4 subset carving of the four-arm closed set — the
    /// two arms whose diagnostic bytes format their `usize` payload
    /// into the shared message template rather than binding to a fixed
    /// `&'static str` on the STATIC axis.
    ///
    /// Pre-lift the same `"param"` bytes lived inline at
    /// [`Self::message`]'s `SubstBadIndex(idx)` match arm as the
    /// literal noun slot of `format!("compiled template referenced bad
    /// param index {idx}")` plus at the truth-table tests
    /// `template_invariant_kind_message_for_subst_bad_idx` and
    /// `template_invariant_display_renders_legacy_compile_shape_for_subst_bad_idx`
    /// — the ≥2 PRIME-DIRECTIVE trigger. Post-lift the (`SubstBadIndex`
    /// variant, canonical `&'static str` descriptor) pairing binds at
    /// ONE `pub const` on the typed [`TemplateInvariantKind`] algebra:
    /// [`Self::message_dynamic`] routes through this constant plus the
    /// [`Self::SPLICE_BAD_INDEX_DESCRIPTOR`] peer via
    /// [`Self::descriptor_dynamic`], the peer [`Self::DYNAMIC_DESCRIPTORS`]
    /// array composes it into a forced-arity `[&'static str; 2]` at ONE
    /// site, and the shared `format!("compiled template referenced bad
    /// {descriptor} index {idx}")` template binds at ONE site inside
    /// [`Self::message_dynamic`] rather than at TWO byte-for-byte
    /// duplicated `format!(...)` arms (the pre-lift `SubstBadIndex(idx)`
    /// arm's `"…bad param index {idx}"` AND the `SpliceBadIndex(idx)`
    /// arm's `"…bad splice index {idx}"`).
    ///
    /// Sibling posture to the closed-set per-role canonical `pub const`
    /// bytes on peer STATIC-subset carvings: this axis is the DYNAMIC
    /// 2-of-4 peer to [`Self::END_LIST_EMPTY_STACK_MESSAGE`] +
    /// [`Self::FINAL_NO_VALUE_MESSAGE`]'s STATIC 2-of-4 carving —
    /// together the four per-role `pub const`s partition the four-arm
    /// closed set into its STATIC ⊕ DYNAMIC halves, each with its own
    /// typed subset projection ([`Self::message_static`],
    /// [`Self::descriptor_dynamic`]). Cross-axis peer to
    /// [`OptionalParamMalformedReason::OPTIONAL_PARAM_SPEC_ARITY`] on
    /// the sibling algebra's `ExtraElements` dynamic arm — both name
    /// the load-bearing typed slot that the pre-lift `format!(...)`
    /// arm embedded as a bare literal.
    ///
    /// Future consumers keyed on the descriptor: LSP quick-fix for the
    /// out-of-bounds Subst rejection (surface `"the compiled template
    /// referenced a bad {descriptor} index"` where `{descriptor}`
    /// binds to this const); a Sekiban audit-trail metric jointly
    /// labeled by the DYNAMIC-subset descriptor
    /// (`tatara_lisp_template_invariant_total{descriptor="param"}` —
    /// the metric label set on the DYNAMIC subset IS
    /// [`Self::DYNAMIC_DESCRIPTORS`]).
    pub const SUBST_BAD_INDEX_DESCRIPTOR: &'static str = "param";

    /// Canonical `&'static str` descriptor bytes for the
    /// [`Self::SpliceBadIndex`] rejection — the noun-slot bytes
    /// `"splice"` naming the splice-target param slot the compiled
    /// bytecode indexed out-of-bounds. Per-role peer of
    /// [`Self::SpliceBadIndex`] on the DYNAMIC 2-of-4 subset carving of
    /// the four-arm closed set.
    ///
    /// Sibling of [`Self::SUBST_BAD_INDEX_DESCRIPTOR`] on the same
    /// DYNAMIC 2-of-4 carving — see that constant's doc for the
    /// algebra-level pre-lift/post-lift contract every DYNAMIC-subset
    /// per-role descriptor shares. Post-lift the shared
    /// `format!("compiled template referenced bad {descriptor} index
    /// {idx}")` template inside [`Self::message_dynamic`] binds
    /// `{descriptor}` to whichever per-role const the DYNAMIC arm
    /// projects through [`Self::descriptor_dynamic`].
    pub const SPLICE_BAD_INDEX_DESCRIPTOR: &'static str = "splice";

    /// The closed set of two canonical `&'static str` descriptor bytes
    /// on the DYNAMIC 2-of-4 subset carving of
    /// [`TemplateInvariantKind`]'s four-arm closed set — the
    /// [`Self::SUBST_BAD_INDEX_DESCRIPTOR`] (`"param"`) noun for the
    /// required-param slot followed by the
    /// [`Self::SPLICE_BAD_INDEX_DESCRIPTOR`] (`"splice"`) noun for the
    /// splice-target param slot. Canonical declaration order matches
    /// [`Self::descriptor_dynamic`]'s arm order so
    /// `Self::DYNAMIC_DESCRIPTORS[0] == Self::descriptor_dynamic(Self::SubstBadIndex(_)).unwrap()`
    /// and `Self::DYNAMIC_DESCRIPTORS[1] == Self::descriptor_dynamic(Self::SpliceBadIndex(_)).unwrap()`
    /// element-wise — pinned by
    /// `template_invariant_kind_dynamic_descriptors_align_with_descriptor_dynamic_by_index`.
    ///
    /// Peer 2-of-4 carving to [`Self::STATIC_MESSAGES`] — together the
    /// STATIC + DYNAMIC 2-of-4 arrays partition the four-arm closed
    /// set into its `&'static str`-projectable halves: the STATIC array
    /// carries the two arms whose FULL message is `&'static str`, the
    /// DYNAMIC array carries the two arms whose NOUN slot is
    /// `&'static str` and whose full message is a
    /// `format!("compiled template referenced bad {descriptor} index
    /// {idx}")` composition. Adding a hypothetical fifth static
    /// invariant lands only on the STATIC array; adding a hypothetical
    /// fifth dynamic invariant (e.g. a `KwargBadIndex(usize)` gate
    /// naming a keyword-param slot the compiled bytecode indexed
    /// out-of-bounds) lands only on this array — rustc's forced-arity
    /// check on the `[&'static str; N]` shape fails compilation if the
    /// array grows without the corresponding per-role descriptor +
    /// [`Self::descriptor_dynamic`] arm being extended in lockstep.
    ///
    /// Sibling posture to [`OptionalParamMalformedReason::STATIC_LABELS`]
    /// (peer algebra's STATIC 3-of-4 carving) — every closed-set outer
    /// algebra the substrate carries now pins BOTH its STATIC-subset
    /// canonical-bytes array AND its DYNAMIC-subset per-role-slot array
    /// at ONE `pub const` per axis rather than at N inline literals
    /// scattered across projections and tests. The DYNAMIC axis is
    /// what this array lands for `TemplateInvariantKind`.
    ///
    /// Future consumers that compose against
    /// [`Self::DYNAMIC_DESCRIPTORS`]: a `tatara-check` coverage
    /// assertion over the workspace corpus (every rendered
    /// `TemplateInvariant` diagnostic with a DYNAMIC-arm shape must
    /// substring-match one of the two descriptor bytes —
    /// `Self::DYNAMIC_DESCRIPTORS.iter()` is the ONE typed sweep over
    /// every legal dynamic-arm noun); a Sekiban audit-trail metric
    /// keyed on the descriptor slot; an LSP quick-fix that pluralizes
    /// the descriptor into a suggestion.
    #[allow(dead_code)]
    pub const DYNAMIC_DESCRIPTORS: [&'static str; 2] = [
        Self::SUBST_BAD_INDEX_DESCRIPTOR,
        Self::SPLICE_BAD_INDEX_DESCRIPTOR,
    ];

    /// Typed `Option<&'static str>` zero-allocation projection over the
    /// STATIC 2-of-4 subset carving of [`TemplateInvariantKind`]'s
    /// four-arm closed set. Returns `Some(bytes)` for the two arms
    /// whose diagnostic bytes bind at a per-role `pub const &'static
    /// str` ([`Self::EndListEmptyStack`] →
    /// [`Self::END_LIST_EMPTY_STACK_MESSAGE`], [`Self::FinalNoValue`] →
    /// [`Self::FINAL_NO_VALUE_MESSAGE`]) and `None` for the two arms
    /// whose bytes format their `usize` payload dynamically
    /// ([`Self::SubstBadIndex`] / [`Self::SpliceBadIndex`]) and
    /// cannot bind to a `&'static str` on this axis.
    ///
    /// The `const fn` posture matches [`MacroDefHead::keyword`],
    /// [`UnquoteForm::label`], [`SexpShape::label`], and every peer
    /// closed-set projection method on the substrate — the projection
    /// evaluates at rustc const-eval time when the variant is a
    /// const, so a future const-context consumer (an
    /// `#[allow(dead_code)] const _: Option<&'static str> = ...`
    /// static assertion, a `tatara-check` predicate binding at
    /// module-init time) picks up the STATIC-subset selector without
    /// runtime dispatch.
    ///
    /// Sibling posture to a hypothetical
    /// `OptionalParamMalformedReason::label_static` on the peer
    /// 3-of-4 static carving of the sibling optional-section-malformed
    /// four-arm closed set: both project the STATIC subset of a
    /// mixed-payload closed set (payload-carrying dynamic arms
    /// project to `None`) into a typed `Option<&'static str>` — the
    /// same idiom applied at two peer boundaries of the substrate's
    /// bytecode-runtime and macro-authoring surfaces.
    ///
    /// Post-lift the substrate's STATIC-subset selector over the
    /// four-arm closed set binds at ONE typed function on the algebra
    /// rather than at zero-primitive-plus-runtime-dispatch through
    /// [`Self::message`]'s match body (which pre-lift owned the
    /// selector by matching two `&'static str` literals inline). A
    /// hypothetical fifth arm on the STATIC subset (e.g.
    /// `WrongOpcode` — a bytecode-header gate) extends
    /// [`Self::STATIC_MESSAGES`] AND [`Self::message_static`]'s arms
    /// AND adds ONE per-role message `pub const` in lockstep —
    /// rustc's exhaustive-match check on the four-arm closed set
    /// fails compilation without the new arm's inclusion.
    #[must_use]
    pub const fn message_static(self) -> Option<&'static str> {
        match self {
            Self::EndListEmptyStack => Some(Self::END_LIST_EMPTY_STACK_MESSAGE),
            Self::FinalNoValue => Some(Self::FINAL_NO_VALUE_MESSAGE),
            Self::SubstBadIndex(_) | Self::SpliceBadIndex(_) => None,
        }
    }

    /// Typed `Option<&'static str>` zero-allocation projection over the
    /// DYNAMIC 2-of-4 subset carving of [`TemplateInvariantKind`]'s
    /// four-arm closed set — returns `Some(descriptor)` for the two
    /// arms whose diagnostic bytes carry a `usize` payload and format
    /// through the shared `"compiled template referenced bad
    /// {descriptor} index {idx}"` template ([`Self::SubstBadIndex`] →
    /// [`Self::SUBST_BAD_INDEX_DESCRIPTOR`] (`"param"`),
    /// [`Self::SpliceBadIndex`] → [`Self::SPLICE_BAD_INDEX_DESCRIPTOR`]
    /// (`"splice"`)), and `None` for the two arms whose full diagnostic
    /// bytes bind at a `&'static str` on the STATIC axis
    /// ([`Self::EndListEmptyStack`], [`Self::FinalNoValue`]) and carry
    /// no per-role descriptor slot.
    ///
    /// Peer projection to [`Self::message_static`] on the sibling
    /// STATIC 2-of-4 subset carving — the two projections together
    /// partition the four-arm closed set into its STATIC ⊕ DYNAMIC
    /// halves at zero allocation cost. Callers holding a variant of
    /// unknown identity thread it through BOTH projections; exactly ONE
    /// of `message_static(self)` and `descriptor_dynamic(self)` returns
    /// `Some` for every legal variant (`message_static` on the
    /// two-arm STATIC subset, `descriptor_dynamic` on the two-arm
    /// DYNAMIC subset). The partition is pinned by the truth-table
    /// test `template_invariant_kind_static_dynamic_projections_partition_closed_set`.
    ///
    /// The `const fn` posture matches [`Self::message_static`],
    /// [`OptionalParamMalformedReason::label_static`], and every peer
    /// closed-set projection method on the substrate — evaluates at
    /// rustc const-eval time when the variant is a const.
    ///
    /// Sibling posture to a hypothetical
    /// `OptionalParamMalformedReason::descriptor_dynamic` projecting
    /// `Self::ExtraElements` into its "elements" descriptor bytes on
    /// the peer algebra's 1-of-4 dynamic carving — the same idiom
    /// applied at two peer boundaries of the substrate's bytecode-
    /// runtime and macro-authoring surfaces.
    ///
    /// Future consumers that compose against this projection: an LSP
    /// quick-fix keyed on the DYNAMIC-subset descriptor slot (surfaces
    /// `"the compiled template referenced a bad {descriptor} index"`
    /// with `{descriptor}` bound to whatever this projection returns);
    /// a `tatara-check` predicate that filters a corpus's
    /// `TemplateInvariant` rejections into static-arm vs dynamic-arm
    /// buckets in ONE typed subset selector rather than three inline
    /// `matches!(kind, Self::SubstBadIndex(_) | Self::SpliceBadIndex(_))`
    /// gates threaded through per-consumer allocation.
    #[must_use]
    pub const fn descriptor_dynamic(self) -> Option<&'static str> {
        match self {
            Self::SubstBadIndex(_) => Some(Self::SUBST_BAD_INDEX_DESCRIPTOR),
            Self::SpliceBadIndex(_) => Some(Self::SPLICE_BAD_INDEX_DESCRIPTOR),
            Self::EndListEmptyStack | Self::FinalNoValue => None,
        }
    }

    /// Typed `Option<String>` projection over the DYNAMIC 2-of-4 subset
    /// carving of [`TemplateInvariantKind`]'s four-arm closed set —
    /// returns `Some(message)` for the two arms whose diagnostic bytes
    /// format their `usize` payload through the SHARED
    /// `"compiled template referenced bad {descriptor} index {idx}"`
    /// template, and `None` for the two STATIC arms whose full bytes
    /// bind on the [`Self::message_static`] axis.
    ///
    /// Composes [`Self::descriptor_dynamic`] into the shared format
    /// template — the `{descriptor}` slot binds to whichever per-role
    /// [`Self::SUBST_BAD_INDEX_DESCRIPTOR`] /
    /// [`Self::SPLICE_BAD_INDEX_DESCRIPTOR`] constant the DYNAMIC arm
    /// projects through, and the `{idx}` slot binds the `usize`
    /// payload the enum's dynamic variant carries. Pre-lift
    /// [`Self::message`]'s body carried TWO byte-for-byte duplicated
    /// `format!(...)` arms whose only variance was the noun slot
    /// (`"param"` vs `"splice"`) — post-lift the shared template binds
    /// at ONE `format!(...)` site inside this method, the noun slot
    /// binds at the per-role descriptor const, and
    /// [`Self::descriptor_dynamic`] carries the arm→descriptor
    /// mapping.
    ///
    /// Peer projection to [`Self::message_static`] on the sibling
    /// STATIC 2-of-4 subset carving — the two projections together
    /// partition the four-arm closed set into its STATIC ⊕ DYNAMIC
    /// message-projection halves. [`Self::message`]'s body reduces to
    /// `message_static().map(str::to_string).or_else(||
    /// message_dynamic()).expect(...)` — ONE compositional flow over
    /// TWO typed subset projections rather than FOUR duplicated match
    /// arms (two `.into()` sites + two `format!(...)` sites in the
    /// pre-lift body).
    ///
    /// Sibling posture to a hypothetical
    /// `OptionalParamMalformedReason::label_dynamic` composing
    /// `Self::ExtraElements`'s `{length}` payload through
    /// [`OptionalParamMalformedReason::OPTIONAL_PARAM_SPEC_ARITY`] on
    /// the peer algebra's 1-of-4 dynamic carving.
    ///
    /// Future consumers that compose against this projection: a
    /// `tatara-check` predicate that filters a corpus's
    /// `TemplateInvariant` rejections into static-arm vs dynamic-arm
    /// message buckets; a Sekiban audit-trail metric that samples
    /// dynamic-arm messages without paying the allocation cost on the
    /// STATIC subset (the `None` branch short-circuits).
    #[must_use]
    pub fn message_dynamic(self) -> Option<String> {
        let descriptor = self.descriptor_dynamic()?;
        let idx = match self {
            Self::SubstBadIndex(idx) | Self::SpliceBadIndex(idx) => idx,
            Self::EndListEmptyStack | Self::FinalNoValue => {
                // Unreachable: descriptor_dynamic() returned Some only
                // for SubstBadIndex / SpliceBadIndex on the `?` above.
                // Kept exhaustive rather than `_ =>` so a future refactor
                // that adds a fifth dynamic arm without extending
                // descriptor_dynamic fails compilation at THIS callsite
                // rather than at runtime.
                unreachable!(
                    "descriptor_dynamic returned Some only for dynamic-arm variants; \
                     the STATIC-arm match here is unreachable via the ? short-circuit"
                )
            }
        };
        Some(format!(
            "compiled template referenced bad {descriptor} index {idx}"
        ))
    }

    /// The `{message}` slot of the legacy `LispError::Compile { form:
    /// macro_name, message: <invariant> }` shape. Each variant projects
    /// to the canonical message string the pre-lift inline triples
    /// emitted — byte-for-byte equivalent so authoring-tool substring
    /// greps (`tatara-check`, REPL) see no drift across the lift.
    ///
    /// Body composes through BOTH typed subset projections — the
    /// STATIC 2-of-4 [`Self::message_static`] and the DYNAMIC 2-of-4
    /// [`Self::message_dynamic`]. The partition contract (exactly ONE
    /// projection returns `Some` for every legal variant) collapses
    /// the pre-lift's FOUR duplicated match arms (two `.into()` sites
    /// on the STATIC subset AND two byte-for-byte `format!(...)` sites
    /// on the DYNAMIC subset) into ONE `.or_else(...)` composition:
    /// `message_static().map(str::to_string).or_else(||
    /// message_dynamic()).expect(...)`. The `.expect(...)` is
    /// structurally unreachable — the partition test
    /// `template_invariant_kind_static_dynamic_projections_partition_closed_set`
    /// pins that at least ONE of the two projections returns `Some` for
    /// every variant. Sibling posture to
    /// `OptionalParamMalformedReason::label` composing through
    /// `label_static` on the peer 3-of-4 static carving.
    #[must_use]
    pub fn message(self) -> String {
        self.message_static()
            .map(str::to_string)
            .or_else(|| self.message_dynamic())
            .expect(
                "message_static/message_dynamic partition covers the four-arm closed set — \
                 exactly one projection returns Some for every legal variant, so the None \
                 branch here is unreachable",
            )
    }
}

/// Closed-set identifier for the head keyword of a `defmacro`-shape
/// rejection — the three canonical macro-definition heads
/// `defmacro` / `defpoint-template` / `defcheck`. Carried as a typed
/// slot on `LispError::DefmacroArity`, `LispError::DefmacroNonSymbolName`,
/// and `LispError::DefmacroNonListParams` so authoring tools (REPL, LSP,
/// `tatara-check`) bind to variant identity rather than substring-matching
/// the rendered `head` string.
///
/// Mirror at the macro-definition-head boundary of the prior-run
/// `CompilerSpecIoStage` (disk-persistence surface) and
/// `TemplateInvariantKind` (bytecode-runtime surface) closed-set lifts:
/// those variants key on a typed enum for the (operation, stage) pair
/// and the invariant kind respectively; this enum keys the three
/// `Defmacro*` variants on a typed head identity. Adding a new
/// macro-definition head requires extending this enum, which rustc-
/// enforces matching at every projection site (`keyword()`) — the
/// closed set becomes a TYPE rather than a `matches!` literal at the
/// `macro_def_from` gate plus three `match head` projections inside
/// each variant's helper.
///
/// `from_keyword(&str) -> Option<Self>` projects an arbitrary source
/// symbol into the typed enum; `keyword(self) -> &'static str` projects
/// back to the canonical literal for `LispError::Display` rendering.
/// The bidirection is the identity on the closed set —
/// `from_keyword(k).unwrap().keyword() == k` for every canonical `k`.
///
/// Theory anchor: THEORY.md §V.1 — knowable platform; the closed set of
/// macro-definition heads becomes a TYPE rather than a runtime
/// string-comparison-and-format dance. THEORY.md §VI.1 — generation
/// over composition; the typed enum lands the structural-completeness
/// floor for the macro-definition-head surface, parallel to how
/// `CompilerSpecIoStage` lands it for the disk-persistence surface and
/// `TemplateInvariantKind` for the bytecode-runtime surface.
#[derive(Debug, Clone, Copy, PartialEq, Eq, tatara_closed_set::DeriveClosedSet)]
#[closed_set(via = "keyword", display, generate_unknown = "macro definition head")]
pub enum MacroDefHead {
    /// `(defmacro NAME (PARAMS) BODY)` — the canonical Lisp-style macro
    /// definition.
    Defmacro,
    /// `(defpoint-template NAME (PARAMS) BODY)` — the K8s-as-processes
    /// authoring surface's macro form (see `tatara-process`).
    DefpointTemplate,
    /// `(defcheck NAME (PARAMS) BODY)` — the workspace-coherence
    /// authoring surface's macro form (see
    /// `tatara-reconciler/checks.lisp`).
    Defcheck,
}

impl MacroDefHead {
    /// The closed set of three macro-definition heads — single source
    /// of truth that drives the [`Self::keyword`] / [`fmt::Display`]
    /// projection AND the [`Self::from_keyword`] / [`FromStr`] decode
    /// sweeps keyed on [`Self::keyword`]. Adding a hypothetical fourth
    /// head (e.g. a `defpoint-fragment` partial-template surface, a
    /// `defrewrite` typed-rewriter authoring keyword) lands at one
    /// [`Self::ALL`] entry + one [`Self::keyword`] arm — exhaustively
    /// checked by the compiler (the `[Self; 3]` array literal forces
    /// the arity) AND by the per-variant truth-table tests below.
    ///
    /// Sibling closed-set lift to every other typed-shape enum in the
    /// crate ([`crate::ast::AtomKind::ALL`],
    /// [`crate::ast::QuoteForm::ALL`], [`SexpShape::ALL`],
    /// [`UnquoteForm::ALL`]) and across the workspace
    /// (`ConditionKind::ALL`, `ProcessPhase::ALL`,
    /// `ProcessSignal::ALL`, `ChannelKind::ALL`, `IntentKind::ALL`,
    /// `LifetimeKind::ALL`, `RequestorKind::ALL`, `ReceiptKind::ALL`,
    /// …) every one of which paired its typed projection with `ALL`
    /// before this lift.
    ///
    /// Future consumers that compose against `ALL`: LSP / REPL
    /// completion for the macro-definition head at point (every
    /// `(defma…` partial input expands through `Self::ALL.iter().
    /// map(MacroDefHead::keyword)`), `tatara-check` coverage assertions
    /// over which macro-definition heads reach a `DefmacroArity` /
    /// `DefmacroNonSymbolName` / `DefmacroNonListParams` arm at all
    /// (the typed sweep replaces the per-call-site vocabulary of three
    /// `&'static str` literals), any future audit-trail metric jointly
    /// labeled by [`Self::keyword`] (e.g.
    /// `tatara_lisp_defmacro_arity_total{head="defmacro"}` — the
    /// metric label set IS [`Self::ALL`] mapped through
    /// [`Self::keyword`]).
    pub const ALL: [Self; 3] = [Self::Defmacro, Self::DefpointTemplate, Self::Defcheck];

    /// Canonical `&'static str` head keyword for [`Self::Defmacro`] —
    /// the `(defmacro NAME (PARAMS) BODY)` Lisp-style macro-definition
    /// form. Sibling posture to [`Self::DEFPOINT_TEMPLATE_KEYWORD`]
    /// (`"defpoint-template"`) and [`Self::DEFCHECK_KEYWORD`]
    /// (`"defcheck"`) on the same head-keyword algebra layer.
    ///
    /// Pre-lift the same `"defmacro"` bytes lived inline at the
    /// [`Self::keyword`] match arm plus at the Display truth-table
    /// test (`macro_def_head_display_renders_canonical_keyword_for_each_variant`)
    /// — the ≥2 PRIME-DIRECTIVE trigger. Post-lift the (`Defmacro`
    /// variant, canonical `&'static str`) pairing binds at ONE `pub
    /// const` on the typed [`MacroDefHead`] algebra: the [`Self::keyword`]
    /// arm and every consumer that pins the exact bytes route through
    /// this constant, so a rename to `defmacro-typed` (say, if a
    /// future extension lands a peer `defmacro-hygienic` variant and
    /// wants to disambiguate the legacy form) is ONE edit HERE with
    /// the derived Display / FromStr surfaces mechanically picking it
    /// up. Sibling posture to the closed set of per-role canonical
    /// `pub const` bytes on the substrate's other closed-set outer
    /// algebras: [`crate::ast::Atom::STR_DELIMITER`] (`'"'`),
    /// [`crate::ast::Atom::KEYWORD_MARKER`] (`":"`),
    /// [`crate::ast::Sexp::LIST_OPEN`] (`'('`),
    /// [`crate::macro_expand::MacroParams::REST_MARKER`] (`"&rest"`),
    /// [`crate::macro_expand::MacroParams::OPTIONAL_MARKER`] (`"&optional"`).
    pub const DEFMACRO_KEYWORD: &'static str = "defmacro";

    /// Canonical `&'static str` head keyword for [`Self::DefpointTemplate`]
    /// — the `(defpoint-template NAME (PARAMS) BODY)` K8s-as-processes
    /// authoring-surface macro form (see the `tatara-process` crate).
    /// Sibling posture to [`Self::DEFMACRO_KEYWORD`] (`"defmacro"`)
    /// and [`Self::DEFCHECK_KEYWORD`] (`"defcheck"`) on the same
    /// head-keyword algebra layer.
    ///
    /// Pre-lift the same `"defpoint-template"` bytes lived inline at
    /// the [`Self::keyword`] match arm plus at the Display truth-table
    /// test. Post-lift the (`DefpointTemplate` variant, canonical
    /// `&'static str`) pairing binds at ONE `pub const` on the typed
    /// [`MacroDefHead`] algebra.
    pub const DEFPOINT_TEMPLATE_KEYWORD: &'static str = "defpoint-template";

    /// Canonical `&'static str` head keyword for [`Self::Defcheck`] —
    /// the `(defcheck NAME (PARAMS) BODY)` workspace-coherence
    /// authoring-surface macro form (see `tatara-reconciler/checks.lisp`).
    /// Sibling posture to [`Self::DEFMACRO_KEYWORD`] (`"defmacro"`)
    /// and [`Self::DEFPOINT_TEMPLATE_KEYWORD`] (`"defpoint-template"`)
    /// on the same head-keyword algebra layer.
    ///
    /// Pre-lift the same `"defcheck"` bytes lived inline at the
    /// [`Self::keyword`] match arm plus at the Display truth-table
    /// test AND at seven `iter_named_calls_to(&forms, "defcheck")` /
    /// `["defmonitor", "defalertpolicy", "defcheck"]` test-site
    /// literals across [`crate::ast`] and [`crate::compile`]. Post-lift
    /// the (`Defcheck` variant, canonical `&'static str`) pairing
    /// binds at ONE `pub const` on the typed [`MacroDefHead`] algebra.
    pub const DEFCHECK_KEYWORD: &'static str = "defcheck";

    /// The closed set of three canonical `&'static str` head keywords
    /// — the [`Self::DEFMACRO_KEYWORD`] (`"defmacro"`) canonical
    /// Lisp-style macro-definition keyword followed by the
    /// [`Self::DEFPOINT_TEMPLATE_KEYWORD`] (`"defpoint-template"`)
    /// K8s-as-processes authoring-surface keyword followed by the
    /// [`Self::DEFCHECK_KEYWORD`] (`"defcheck"`) workspace-coherence
    /// authoring-surface keyword. Canonical declaration order matches
    /// [`Self::ALL`] so `Self::KEYWORDS[i] == Self::ALL[i].keyword()`
    /// element-wise — pinned by
    /// `macro_def_head_keywords_align_with_all_by_index`.
    ///
    /// Sibling posture to
    /// [`crate::macro_expand::MacroParams::LAMBDA_LIST_KEYWORDS`]
    /// (`[Self; 2]`) — every closed-set algebra now pins its
    /// keyword-projection ALL array at the declaration site via a
    /// forced-arity `[&'static str; N]` array whose length fails
    /// compilation if a new variant lands without being added to the
    /// set. Adding a hypothetical fourth head (a `defpoint-fragment`
    /// partial-template surface, a `defrewrite` typed-rewriter
    /// authoring keyword) extends [`Self::ALL`] ONCE +
    /// [`Self::keyword`] ONCE + [`Self::KEYWORDS`] ONCE + adds ONE
    /// per-role keyword `pub const` — rustc's forced-arity check on
    /// the `[Self; N]` array + `[&'static str; N]` array pair
    /// enforces every downstream consumer picks up the extension
    /// mechanically.
    ///
    /// Future consumers that compose against [`Self::KEYWORDS`]: an
    /// LSP / REPL completion provider surfacing every `(defma…`
    /// partial input against the closed set (`Self::KEYWORDS.iter()`
    /// is the ONE typed sweep over every legal macro-definition
    /// head), a `tatara-check` coverage assertion (every workspace
    /// `.lisp` file's `(def…)` form-head must classify to some entry
    /// of `Self::KEYWORDS` OR be a registered `TataraDomain` keyword),
    /// a Sekiban audit-trail metric jointly labeled by
    /// [`Self::keyword`] whose metric-label set IS `Self::KEYWORDS`.
    pub const KEYWORDS: [&'static str; 3] = [
        Self::DEFMACRO_KEYWORD,
        Self::DEFPOINT_TEMPLATE_KEYWORD,
        Self::DEFCHECK_KEYWORD,
    ];

    /// Project a `head: &str` borrow (a `Sexp` symbol slice) into the
    /// typed `MacroDefHead`. Returns `None` if `head` is not one of the
    /// three canonical macro-definition head keywords; the caller
    /// (`macro_def_from`) then returns `Ok(None)` to mean "this form is
    /// not a defmacro form."
    ///
    /// Implemented as a linear sweep over [`Self::ALL`] keyed on
    /// [`Self::keyword`] so the three canonical keyword literals
    /// (`"defmacro"` / `"defpoint-template"` / `"defcheck"`) live at
    /// ONE site (the `keyword` arms) rather than at TWO sites
    /// (`keyword` + a per-variant `from_keyword` match arm). Adding a
    /// fourth variant extends only [`Self::ALL`] + [`Self::keyword`],
    /// NOT a third per-variant literal site. The `Option<Self>` face
    /// is the open-by-design projection [`crate::ast::Sexp::as_call_to_any`]
    /// composes against; [`FromStr`] is the typed-error face callers
    /// reaching for a parse-rejection diagnostic compose against.
    /// Cross-face contract pinned by
    /// `macro_def_head_from_keyword_matches_from_str_for_every_input`.
    #[must_use]
    pub fn from_keyword(head: &str) -> Option<Self> {
        head.parse().ok()
    }

    /// Project the typed `MacroDefHead` back to the canonical
    /// `&'static str` literal — feeds the `LispError::Defmacro*` Display
    /// rendering via the `#[error(...)]` annotation. The `&'static str`
    /// lifetime is load-bearing: it's what lets the variants project
    /// through this method into their `compile error in {head}:` prefix
    /// without an allocation, parallel to how
    /// `CompilerSpecIoStage::operation()` / `label()` feed
    /// `LispError::CompilerSpecIo`'s Display.
    #[must_use]
    pub fn keyword(self) -> &'static str {
        match self {
            Self::Defmacro => Self::DEFMACRO_KEYWORD,
            Self::DefpointTemplate => Self::DEFPOINT_TEMPLATE_KEYWORD,
            Self::Defcheck => Self::DEFCHECK_KEYWORD,
        }
    }
}

// `impl std::fmt::Display for MacroDefHead` + `impl std::str::FromStr
// for MacroDefHead` + `impl tatara_closed_set::ClosedSet for MacroDefHead` +
// `pub struct UnknownMacroDefHead(pub String)` are generated by
// `#[derive(tatara_closed_set::DeriveClosedSet)]` on the enum declaration
// above. `label` delegates to the inherent `MacroDefHead::keyword` via
// `#[closed_set(via = "keyword")]` so the domain-canonical
// reserved-word projection (`"defmacro"` / `"defpoint-template"` /
// `"defcheck"`) stays load-bearing at the inherent surface while the
// trait surface unifies every closed-set implementor's projection name
// onto `label`. The `display` flag emits the substrate-wide
// `f.write_str(Self::keyword(*self))` block.
// `#[closed_set(generate_unknown = "macro definition head")]` emits the
// typed parse-rejection carrier with the substrate-wide `Debug + Clone
// + PartialEq + Eq + thiserror::Error` derives and the `#[error("unknown
// macro definition head: {0}")]` annotation byte-for-byte; the explicit
// label overrides the auto-derived
// `pascal_to_spaced_lowercase("MacroDefHead")` (`"macro def head"`)
// which abbreviates `Def` rather than expanding it to `definition`,
// pinning the pre-lift operator-facing wording. The FromStr decode is
// a linear sweep over `MacroDefHead::ALL` keyed on `keyword`; round-trip
// + cross-axis rejection (`"defpoint"` / `"symbol"`) pinned by
// `macro_def_head_keyword_round_trips_through_from_str` +
// `macro_def_head_from_str_rejects_cross_axis_vocabularies`.

/// Closed-set identifier for the way a `Sexp::List` entry in a macro's
/// `&optional` section failed to match the canonical `(NAME DEFAULT)`
/// shape. Carried as a typed slot on `LispError::OptionalParamMalformed`
/// so authoring tools (REPL, LSP, `tatara-check`) bind to variant identity
/// rather than substring-matching the rendered suffix.
///
/// Mirror at the `parse_params` optional-section boundary of the prior-run
/// `MacroDefHead` (macro-definition-head closed set), `UnquoteForm`
/// (template-marker closed set), `CompilerSpecIoStage` (disk-persistence
/// surface), and `TemplateInvariantKind` (bytecode-runtime surface)
/// closed-set lifts: those enums key their respective rejection variants
/// on a typed identity; this enum keys the four reachable list-spec
/// rejection modes the optional-section gate can emit on a typed identity.
/// Adding a new mode (e.g., `SuppliedPNotYetSupported` once an evaluator
/// lands and the three-element `(name default supplied-p)` shape is
/// admitted) requires extending this enum, which rustc-enforces matching
/// at every projection site (`label()`).
///
/// `label(self) -> String` projects the typed reason to a short
/// human-readable clause (`"empty list"` / `"missing default"` / `"3
/// elements (need 2)"` / `"name not a symbol"`) that the
/// `LispError::OptionalParamMalformed` Display rendering threads through
/// `optional_param_malformed_suffix` into the parenthetical suffix —
/// parallel to how `TemplateInvariantKind::message()` feeds
/// `LispError::TemplateInvariant`'s Display.
///
/// Theory anchor: THEORY.md §V.1 — knowable platform; the closed set of
/// optional-spec malformed shapes becomes a TYPE rather than a runtime
/// string-comparison-and-format dance. A typo like `reason: "empty list
/// "` (trailing space) is structurally unrepresentable; the four shapes
/// are an exhaustive `match`. THEORY.md §VI.1 — generation over
/// composition; the typed enum lands the structural-completeness floor
/// for the optional-section-malformed surface, parallel to how
/// `TemplateInvariantKind` lands it for the bytecode-runtime surface and
/// `MacroDefHead` for the macro-definition-head surface.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum OptionalParamMalformedReason {
    /// `&optional ()` — the spec is a list of length zero, with no name
    /// and no default form.
    EmptyList,
    /// `&optional (x)` — the spec is a list of length one, naming an
    /// optional but supplying no default form. This is REJECTED rather
    /// than reinterpreted as `&optional x` because a bare-symbol spec
    /// IS the canonical "no default" shape; a parenthesized
    /// single-element spec is ambiguous and would silently DROP the
    /// extra parens at the surface.
    MissingDefault,
    /// `&optional (x default extra …)` — the spec is a list of length
    /// three or more. CL's `(name default supplied-p)` shape is NOT
    /// supported in v0 (no evaluator → no `supplied-p` variable
    /// binding), so any third element is structurally surplus. `length`
    /// is the actual element count (≥3).
    ExtraElements { length: usize },
    /// `&optional (5 default)` — the spec is a list of length two but
    /// the first element isn't a symbol. The name slot must be a symbol
    /// (the same gate the bare-symbol path enforces); a non-symbol head
    /// is rejected here so the `OptionalParam.name: String` slot cannot
    /// be populated from a `5` / `:foo` / `(nested)` value.
    NonSymbolName,
}

impl OptionalParamMalformedReason {
    /// Canonical `&'static str` diagnostic-label bytes for the
    /// [`Self::EmptyList`] rejection — `"empty list"`. Per-role peer of
    /// [`Self::EmptyList`] on the closed-set optional-spec-rejection
    /// algebra; consumers reach for
    /// `OptionalParamMalformedReason::EMPTY_LIST_LABEL` when the caller
    /// has a variant in hand at compile time and wants the canonical
    /// diagnostic bytes without an intermediate `.to_string()`
    /// allocation through [`Self::label`].
    ///
    /// Sibling posture to [`crate::error::MacroDefHead::DEFMACRO_KEYWORD`]
    /// et al (per-role reserved-word algebra on the macro-definition-head
    /// closed set) and [`crate::error::StructuralKind::NIL_LABEL`] et al
    /// (per-role structural-residual algebra on the SexpShape 2-of-12
    /// carving): every closed-set outer algebra the substrate carries
    /// now pins its per-variant canonical bytes at ONE `pub const` per
    /// role.
    ///
    /// The three per-role static labels here (this constant,
    /// [`Self::MISSING_DEFAULT_LABEL`], [`Self::NON_SYMBOL_NAME_LABEL`])
    /// close the STATIC subset of the four-arm closed set — the fourth
    /// arm [`Self::ExtraElements`] carries a `usize` payload and formats
    /// its label dynamically, so it stays inline at [`Self::label`] and
    /// does NOT admit a per-role `&'static str` constant on this axis.
    /// The 3-of-4 carving is pinned by
    /// [`Self::STATIC_LABELS`]'s `[&'static str; 3]` forced-arity array.
    ///
    /// Cross-axis overlap: this label's `"empty list"` bytes are
    /// byte-for-byte identical to the fallback body emitted by
    /// [`missing_head_symbol_suffix`]'s `None` arm (the "no head symbol,
    /// list is empty" rejection at [`LispError::MissingHeadSymbol`]).
    /// The two sites SHARE the surface bytes but carry DISTINCT
    /// semantic scopes (this arm scopes to the `&optional` section
    /// gate; the sibling site scopes to a bare call-head list-empty
    /// gate), so the alias is intentionally NOT lifted to a
    /// substrate-wide constant — a future disambiguation drift on
    /// EITHER side must land at the semantic-scope site rather than at
    /// a shared canonical byte.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 5 — composition
    /// preserves proofs; the (variant, canonical-bytes) pairing binds
    /// at ONE `pub const` on the typed algebra rather than at TWO
    /// sites (a match-arm literal AND a Display-test literal).
    /// THEORY.md §III — the typescape; the canonical diagnostic bytes
    /// bind at ONE `pub const` on the closed-set algebra rather than
    /// at inline `.to_string()` literals in the [`Self::label`] match
    /// arms.
    pub const EMPTY_LIST_LABEL: &'static str = "empty list";

    /// Canonical `&'static str` diagnostic-label bytes for the
    /// [`Self::MissingDefault`] rejection — `"missing default"`.
    /// Sibling of [`Self::EMPTY_LIST_LABEL`] on the closed-set per-role
    /// static-label axis; see [`Self::EMPTY_LIST_LABEL`] for the
    /// algebra-level round-trip contract every sibling shares.
    pub const MISSING_DEFAULT_LABEL: &'static str = "missing default";

    /// Canonical `&'static str` diagnostic-label bytes for the
    /// [`Self::NonSymbolName`] rejection — `"name not a symbol"`.
    /// Sibling of [`Self::EMPTY_LIST_LABEL`] on the closed-set per-role
    /// static-label axis; see [`Self::EMPTY_LIST_LABEL`] for the
    /// algebra-level round-trip contract every sibling shares.
    pub const NON_SYMBOL_NAME_LABEL: &'static str = "name not a symbol";

    /// Closed-set forced-arity ALL array over the canonical STATIC
    /// diagnostic-label `&'static str` bytes — the three arms that
    /// project to a `&'static str` label under [`Self::label`], in
    /// canonical declaration order matching the enum's static-label
    /// subset ([`Self::EmptyList`], [`Self::MissingDefault`],
    /// [`Self::NonSymbolName`] — the fourth variant
    /// [`Self::ExtraElements`] formats a `usize` payload dynamically
    /// and is excluded from this array).
    ///
    /// Sibling posture to [`crate::error::StructuralKind::LABELS`]
    /// (`[&'static str; 2]` — the 2-of-12 structural-residual carving),
    /// [`crate::error::MacroDefHead::KEYWORDS`] (`[&'static str; 3]` —
    /// the 3-arm macro-definition-head algebra), and
    /// [`crate::ast::AtomKind::LABELS`] (`[&'static str; 6]` — the
    /// 6-of-12 atomic-payload carving) — every closed-set outer
    /// algebra that carries an `&'static str`-per-variant label now
    /// pins its per-role canonical bytes at ONE `pub const` per role
    /// PLUS an ALL array for family-wide consumers.
    ///
    /// Pre-lift the three static rejection-label bytes had NO per-role
    /// primitive on this closed-set algebra — a consumer with a
    /// [`OptionalParamMalformedReason`] variant in hand at compile time
    /// reaching for the canonical bytes had to spell
    /// `OptionalParamMalformedReason::EmptyList.label()` (runtime
    /// dispatch through the match arm PLUS a `.to_string()` heap
    /// allocation) OR inline the `"empty list"` literal at the call
    /// site AND at every Display-round-trip test's assertion body.
    /// Post-lift the THREE canonical bytes bind at ONE `pub const` per
    /// role on the typed algebra AND at [`Self::STATIC_LABELS`] as a
    /// family-wide forced-arity array — a future LSP / REPL completion
    /// bar keyed on this rejection surface, a `tatara-check` coverage
    /// sweep over the `&optional`-spec-malformed arm-set of a
    /// `LispError` corpus, or a Sekiban audit-trail metric jointly
    /// labeled by the rejection reason
    /// (`tatara_lisp_optional_param_malformed_total{reason="empty
    /// list"}`) reads through the typed constants without re-deriving
    /// the 3-of-4 static-subset carving inline.
    ///
    /// Adding a hypothetical fifth STATIC rejection reason (e.g. a
    /// `KeywordName` rejection for `&optional (:foo default)` if
    /// keywords ever became legal in the `&optional` name slot) extends
    /// this array AND adds ONE per-role `pub const` in lockstep —
    /// rustc's forced-arity check on `[&'static str; N]` fails
    /// compilation if the array grows without the const.
    ///
    /// The `#[allow(dead_code)]` posture matches
    /// [`crate::error::StructuralKind::HASH_DISCRIMINATORS`] and other
    /// prior-run family-wide ALL arrays: the substrate's current
    /// [`Self::label`] body composes through the per-variant match arm
    /// rather than sweeping the family-wide array, so no non-test
    /// caller currently reaches this array directly. The lift lands
    /// the substrate primitive so future consumers keyed on the whole
    /// static-subset (a Sekiban metric, a `tatara-check` predicate,
    /// a `TypedRewriter<OptionalParamMalformedReasonOp>` sweep) bind
    /// to ONE `[&'static str; 3]` primitive rather than re-deriving
    /// the array inline per callsite.
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the three
    /// canonical rejection-label bytes bind at ONE typed
    /// `[&'static str; 3]` array on the closed-set algebra rather
    /// than at zero-primitive-plus-three-inline-`.to_string()`-literals
    /// scattered across [`Self::label`]. THEORY.md §V.1 — knowable
    /// platform; the static-subset's cardinality becomes a TYPE-level
    /// constant on the substrate algebra rather than a per-consumer
    /// runtime dispatch through the label match. THEORY.md §VI.1 —
    /// generation over composition; the family-wide contract
    /// (alignment with the enum's static-label subset, membership
    /// through [`Self::label`]) emerges from the composition of FOUR
    /// substrate primitives (this `pub const` array + the three
    /// per-role `pub const *_LABEL` aliases) rather than as per-
    /// variant inline assertions duplicated at each call site.
    #[allow(dead_code)]
    pub const STATIC_LABELS: [&'static str; 3] = [
        Self::EMPTY_LIST_LABEL,
        Self::MISSING_DEFAULT_LABEL,
        Self::NON_SYMBOL_NAME_LABEL,
    ];

    /// Canonical target arity of the `&optional (NAME DEFAULT)` list-spec
    /// — exactly TWO elements (a symbol head naming the optional and a
    /// default form). The accept-arity for `parse_optional_list_spec`'s
    /// dispatch; every other arity is a rejection reason on this closed
    /// set ([`Self::EmptyList`] at arity 0, [`Self::MissingDefault`] at
    /// arity 1, [`Self::ExtraElements`] at arity ≥3).
    ///
    /// Pre-lift the target arity appeared as the bare literal `2` at
    /// FOUR sites: the `match items.len()` accept arm in
    /// `parse_optional_list_spec` (macro_expand.rs), the `"need 2"`
    /// suffix bytes embedded in [`Self::label`]'s `ExtraElements` arm,
    /// the doc-comment enumeration on this enum's Display projection,
    /// and every truth-table test that asserts against the rendered
    /// diagnostic bytes. A drift on any ONE site (e.g. an evaluator lands
    /// and the accept-arity becomes 3 to admit CL's `(name default
    /// supplied-p)` shape) had to ripple across all four in lockstep or
    /// silently fracture the parser gate from its operator-facing
    /// vocabulary. Post-lift the arity binds at ONE `pub const usize` on
    /// the typed algebra: the parser reaches through
    /// [`Self::classify_arity`] (which threads this constant into the
    /// match arm via a local rebind), [`Self::label`] renders `"need
    /// {}"` interpolated on this constant, and the doc + tests reach for
    /// the const symbol rather than the literal `2`.
    ///
    /// Sibling posture to the prior-run per-role `&'static str` / `u8` /
    /// `char` per-variant algebras ([`Self::EMPTY_LIST_LABEL`],
    /// [`crate::error::StructuralKind::HASH_DISCRIMINATORS`],
    /// [`crate::ast::QuoteForm::UNQUOTE_PREFIX`], et al) — every prior
    /// lift pinned a per-role marker at ONE `pub const` on the typed
    /// algebra rather than at N inline literals across parsers,
    /// projections, and tests. This lift extends the axis-set with the
    /// first per-family-canonical `usize` on the closed-set optional-
    /// spec-rejection algebra.
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the canonical
    /// accept-arity of the `&optional (NAME DEFAULT)` spec binds at ONE
    /// typed `pub const usize` on the closed-set algebra rather than at
    /// four literal-`2` sites scattered across parsers, projections, and
    /// tests. THEORY.md §II.1 invariant 5 — composition preserves proofs;
    /// a hypothetical bump to arity-3 (once an evaluator admits `(name
    /// default supplied-p)`) lands at ONE constant AND rustc-enforces
    /// that every downstream projection ([`Self::label`],
    /// [`Self::classify_arity`], every truth-table test) recomputes
    /// against the new arity. THEORY.md §V.1 — knowable platform; the
    /// parser's accept-arity becomes a TYPE-level constant on the
    /// substrate algebra rather than a per-callsite magic number.
    pub const OPTIONAL_PARAM_SPEC_ARITY: usize = 2;

    /// Classify a list-spec's element count against the canonical
    /// accept-arity [`Self::OPTIONAL_PARAM_SPEC_ARITY`] — returns `None`
    /// iff the arity is exactly the accept target (the parser continues
    /// to the head-symbol gate); returns `Some(reason)` otherwise with
    /// the arity-derivable rejection reason on the closed set.
    ///
    /// The three arity-derivable rejection arms are:
    ///
    ///   * arity 0 → [`Self::EmptyList`]
    ///   * arity 1 → [`Self::MissingDefault`]
    ///   * arity ≥3 → [`Self::ExtraElements { length }`]
    ///
    /// The fourth variant [`Self::NonSymbolName`] is NOT arity-derivable
    /// — accept-arity with a non-symbol head still rejects — and stays
    /// at the caller's head-symbol gate. The caller composes this
    /// classifier with the head-symbol check to close the full four-way
    /// dispatch. Pre-lift `parse_optional_list_spec` embedded the arity
    /// match inline (`match items.len() { 0 => ..., 1 => ..., 2 => ...,
    /// length => ... }`) with the accept-arity as a bare literal `2` in
    /// the accept arm — a duplicate of the target arity that
    /// [`Self::label`]'s `"need 2"` suffix ALSO embedded literally. Post-
    /// lift the arity-to-reason projection binds at ONE typed function on
    /// the algebra threading [`Self::OPTIONAL_PARAM_SPEC_ARITY`] through
    /// a local `const ARITY` rebind (rustc's match-pattern rules require
    /// a name binding rather than a `Self::` path pattern).
    ///
    /// Sibling posture to [`crate::ast::QuoteForm::as_unquote_form`]
    /// (typed 2-of-4 subset projection between quote-family enums) and
    /// [`crate::ast::AtomKind::from_atom`] (typed constructor from a
    /// parent's payload) — every prior-run typed classifier factored an
    /// inline dispatch into a `#[must_use]` typed function on the closed
    /// set. This method extends the pattern to the arity-to-reason
    /// projection.
    ///
    /// Future consumers that compose against this classifier: a
    /// `tatara-check` static analyzer that predicts optional-spec
    /// rejections without threading through the whole parser; an LSP
    /// quick-fix that suggests wrapping a bare symbol as `(symbol
    /// default)` iff `classify_arity(1) == Some(MissingDefault)`; a
    /// `TypedRewriter<OptionalParamMalformedReasonOp>` sweep that keys
    /// on this reason projection.
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the arity→reason
    /// projection binds at ONE typed function on the algebra rather than
    /// at inline `match` bodies duplicated across parsers. THEORY.md
    /// §II.1 invariant 1 (typed entry): every parser that accepts an
    /// `&optional`-spec list threads its arity through this classifier
    /// before touching the head-symbol gate, closing the arity
    /// half of the rejection surface at a single typed site.
    #[must_use]
    pub fn classify_arity(length: usize) -> Option<Self> {
        const ARITY: usize = OptionalParamMalformedReason::OPTIONAL_PARAM_SPEC_ARITY;
        match length {
            0 => Some(Self::EmptyList),
            1 => Some(Self::MissingDefault),
            ARITY => None,
            length => Some(Self::ExtraElements { length }),
        }
    }

    /// Zero-allocation projection over the STATIC subset of the closed
    /// set — `Some(&'static str)` for the three arms whose diagnostic
    /// bytes bind at a per-role [`Self::EMPTY_LIST_LABEL`] /
    /// [`Self::MISSING_DEFAULT_LABEL`] / [`Self::NON_SYMBOL_NAME_LABEL`]
    /// constant, and `None` for the fourth arm [`Self::ExtraElements`]
    /// whose diagnostic bytes format the `length` payload dynamically
    /// through `format!("{length} elements (need {})",
    /// [`Self::OPTIONAL_PARAM_SPEC_ARITY`])` and cannot bind to a
    /// `&'static str` constant on this axis.
    ///
    /// This is the STATIC-subset typed projection over the 3-of-4
    /// carving [`Self::STATIC_LABELS`] enumerates — the same 3-of-4
    /// shape pinned as a `[&'static str; 3]` forced-arity array on
    /// that constant. Callers that KNOW they've matched a static arm
    /// at compile time reach for the per-role `pub const *_LABEL`
    /// directly; callers that hold a variant of unknown identity
    /// reach for this projection to filter the STATIC subset without
    /// paying an allocation for the failing branch. The composition
    /// gives every downstream site — Sekiban audit-trail metrics
    /// (`tatara_lisp_optional_param_malformed_total{reason="empty
    /// list"}` where the label is a `&'static str` label slot with
    /// no heap indirection), an LSP quick-fix keyed on the STATIC
    /// subset, a `tatara-check` predicate that filters a corpus's
    /// `OptionalParamMalformed` rejections into static-arm vs
    /// dynamic-arm buckets — one typed subset selector rather than
    /// three inline `matches!(reason, Self::EmptyList |
    /// Self::MissingDefault | Self::NonSymbolName)` gates threaded
    /// through per-consumer allocation.
    ///
    /// Sibling posture to [`Self::classify_arity`] (typed `usize` →
    /// `Option<Self>` projection over the arity-derivable 3-of-4
    /// carving) — both methods carve the same closed set along the
    /// same 3-of-4 axis (the fourth variant [`Self::NonSymbolName`]
    /// on the classify side, [`Self::ExtraElements`] on this side)
    /// and pin the carving at ONE typed function on the algebra.
    /// The two carvings compose: a caller with an arity `n` in hand
    /// runs `classify_arity(n)` to get `Option<Self>`, then runs
    /// `label_static(reason)` on the `Some` result to get
    /// `Option<&'static str>` — the double-`Option` collapses the
    /// arity → reason → static-label pipeline into TWO typed
    /// projections composable at zero allocation cost for the STATIC
    /// subset.
    ///
    /// [`Self::label`] composes this projection with the dynamic
    /// [`Self::ExtraElements`] format arm — an `Option::unwrap_or_else`
    /// over `label_static()` that lands on the `format!` branch iff
    /// the variant is [`Self::ExtraElements`]. Pre-lift `label`'s
    /// body carried FOUR match arms — three inline `.to_string()`
    /// literals routing through the per-role `pub const`s AND one
    /// `format!` arm formatting the `length` payload. Post-lift
    /// `label`'s body reduces to `label_static().map(str::to_string)
    /// .unwrap_or_else(|| format!(...))`, and the three per-role
    /// static arms bind at ONE typed subset projection rather than
    /// at three duplicated `.to_string()` sites.
    ///
    /// Const-fn on `Self` because the four arms match on unit
    /// / payload-carrying variants alike without allocation — the
    /// `Self::ExtraElements { .. }` arm ignores the payload via
    /// `{ .. }` because the projection routes to `None` regardless
    /// of the `length` value.
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the STATIC-
    /// subset projection binds at ONE typed function on the
    /// algebra rather than at three inline `matches!` gates
    /// scattered across consumers. THEORY.md §II.1 invariant 5 —
    /// composition preserves proofs; a hypothetical fifth static
    /// rejection reason (e.g. `KeywordName` for `&optional (:foo
    /// default)`) extends this projection AND [`Self::STATIC_LABELS`]
    /// in lockstep — rustc's exhaustive-match check on this method
    /// fails compilation without the new arm. THEORY.md §VI.1 —
    /// generation over composition; [`Self::label`]'s dynamic body
    /// emerges from the composition of TWO substrate primitives (this
    /// static-subset projection + the [`Self::ExtraElements`] format
    /// arm) rather than as four duplicated match arms.
    #[must_use]
    pub const fn label_static(self) -> Option<&'static str> {
        match self {
            Self::EmptyList => Some(Self::EMPTY_LIST_LABEL),
            Self::MissingDefault => Some(Self::MISSING_DEFAULT_LABEL),
            Self::NonSymbolName => Some(Self::NON_SYMBOL_NAME_LABEL),
            Self::ExtraElements { .. } => None,
        }
    }

    /// Canonical `&'static str` noun-descriptor for the
    /// [`Self::ExtraElements`] rejection's dynamic format template —
    /// `"elements"`. Per-role peer of `Self::ExtraElements` on the
    /// DYNAMIC 1-of-4 subset carving of the four-arm closed set.
    ///
    /// Pre-lift the `"elements"` noun lived inline inside
    /// [`Self::label`]'s `format!("{length} elements (need {})", …)`
    /// arm — a single site, but one that any downstream sweep over
    /// dynamic-arm nouns had to substring-match rather than bind to a
    /// typed constant. Post-lift the (`ExtraElements` variant, canonical
    /// noun bytes) pairing binds at ONE `pub const` on the typed
    /// [`OptionalParamMalformedReason`] algebra: [`Self::label_dynamic`]
    /// composes this constant into the shared `"{length} {descriptor}
    /// (need {})"` format template, the peer [`Self::DYNAMIC_DESCRIPTORS`]
    /// array closes the DYNAMIC carving as a forced-arity
    /// `[&'static str; 1]` at ONE site, and [`Self::descriptor_dynamic`]
    /// carries the variant→noun projection.
    ///
    /// Sibling posture to
    /// [`TemplateInvariantKind::SUBST_BAD_INDEX_DESCRIPTOR`] /
    /// [`TemplateInvariantKind::SPLICE_BAD_INDEX_DESCRIPTOR`] on the peer
    /// bytecode-runtime algebra's DYNAMIC 2-of-4 subset carving — both
    /// pin per-role noun-descriptor bytes at ONE `pub const` on their
    /// closed-set algebra rather than at inline literals inside a
    /// `format!(...)` arm. The peer's DYNAMIC subset is TWO arms wide
    /// (`SubstBadIndex`, `SpliceBadIndex`); this algebra's DYNAMIC subset
    /// is ONE arm wide (`ExtraElements`) — the same carving idiom applied
    /// at asymmetric widths.
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the canonical
    /// noun-descriptor of the ExtraElements arm's dynamic format
    /// template binds at ONE typed `pub const &'static str` on the
    /// closed-set algebra rather than at an inline literal inside
    /// [`Self::label`]'s `format!` body. THEORY.md §II.1 invariant 5 —
    /// composition preserves proofs; a rename of the noun (e.g. from
    /// `"elements"` to `"items"` if an evaluator surface ever admits a
    /// more general list-shape) lands at ONE `pub const` edit — every
    /// downstream projection ([`Self::label_dynamic`],
    /// [`Self::DYNAMIC_DESCRIPTORS`], the [`Self::label`] composition,
    /// every truth-table test) recomputes against the new bytes.
    /// THEORY.md §VI.1 — generation over composition; the shared format
    /// template that emitted the `"elements"` literal inline at ONE site
    /// pre-lift now composes ONE typed const AND ONE typed projection
    /// AND ONE typed arity, so future dynamic-arm siblings extend at
    /// exactly these three axes rather than at inline duplication.
    pub const EXTRA_ELEMENTS_DESCRIPTOR: &'static str = "elements";

    /// Closed-set forced-arity ALL array over the canonical DYNAMIC
    /// noun-descriptor `&'static str` bytes — the ONE arm that projects
    /// to a `&'static str` descriptor under [`Self::descriptor_dynamic`],
    /// in canonical declaration order matching the enum's dynamic-label
    /// subset ([`Self::ExtraElements`] — the other three variants
    /// [`Self::EmptyList`], [`Self::MissingDefault`],
    /// [`Self::NonSymbolName`] carry their FULL bytes on the STATIC axis
    /// via [`Self::STATIC_LABELS`] and are excluded from this array).
    ///
    /// Peer 1-of-4 carving to [`Self::STATIC_LABELS`] — together the
    /// two arrays partition the four-arm closed set into its STATIC ⊕
    /// DYNAMIC halves. The STATIC array carries the three arms whose
    /// FULL diagnostic is `&'static str`; this DYNAMIC array carries the
    /// one arm whose NOUN slot is `&'static str` and whose full label is
    /// a `format!("{length} {descriptor} (need {})")` composition over
    /// [`Self::OPTIONAL_PARAM_SPEC_ARITY`]. Adding a hypothetical fifth
    /// static rejection reason (e.g. `KeywordName` for `&optional (:foo
    /// default)`) lands only on the STATIC array; adding a hypothetical
    /// fifth dynamic rejection reason (e.g. `NestedList { depth: usize
    /// }` naming a spec whose `NAME` slot is itself a list rather than a
    /// symbol) lands only on this array — rustc's forced-arity check on
    /// the `[&'static str; N]` shape fails compilation if the array
    /// grows without the corresponding per-role descriptor +
    /// [`Self::descriptor_dynamic`] arm being extended in lockstep.
    ///
    /// Sibling posture to
    /// [`TemplateInvariantKind::DYNAMIC_DESCRIPTORS`] (`[&'static str;
    /// 2]` — the peer bytecode-runtime algebra's DYNAMIC 2-of-4 carving)
    /// — every closed-set outer algebra the substrate carries now pins
    /// BOTH its STATIC-subset canonical-bytes array AND its DYNAMIC-
    /// subset per-role-slot array at ONE `pub const` per axis rather
    /// than at N inline literals scattered across projections and tests.
    /// The two peer algebras carry the same STATIC ⊕ DYNAMIC partition
    /// idiom at asymmetric widths (`TemplateInvariantKind` is 2 ⊕ 2;
    /// `OptionalParamMalformedReason` is 3 ⊕ 1).
    ///
    /// The `#[allow(dead_code)]` posture matches
    /// [`TemplateInvariantKind::DYNAMIC_DESCRIPTORS`] and
    /// [`Self::STATIC_LABELS`]: the substrate's current [`Self::label`]
    /// body composes through [`Self::descriptor_dynamic`] rather than
    /// sweeping the family-wide array, so no non-test caller currently
    /// reaches this array directly. The lift lands the substrate
    /// primitive so future consumers keyed on the whole dynamic subset
    /// (a Sekiban metric, a `tatara-check` predicate, a
    /// `TypedRewriter<OptionalParamMalformedReasonOp>` sweep) bind to
    /// ONE `[&'static str; 1]` primitive rather than re-deriving the
    /// array inline per callsite.
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the ONE canonical
    /// dynamic-arm noun-descriptor byte binds at ONE typed
    /// `[&'static str; 1]` array on the closed-set algebra rather than
    /// at zero-primitive-plus-one-inline-literal inside [`Self::label`]'s
    /// `format!` body. THEORY.md §V.1 — knowable platform; the DYNAMIC-
    /// subset's cardinality becomes a TYPE-level constant on the
    /// substrate algebra rather than a per-consumer runtime dispatch
    /// through the label match. THEORY.md §VI.1 — generation over
    /// composition; the family-wide contract (alignment with the enum's
    /// dynamic-label subset, membership through
    /// [`Self::descriptor_dynamic`]) emerges from the composition of TWO
    /// substrate primitives (this `pub const` array + the one per-role
    /// `pub const EXTRA_ELEMENTS_DESCRIPTOR` alias) rather than as
    /// per-variant inline assertions duplicated at each call site.
    #[allow(dead_code)]
    pub const DYNAMIC_DESCRIPTORS: [&'static str; 1] = [Self::EXTRA_ELEMENTS_DESCRIPTOR];

    /// Zero-allocation projection over the DYNAMIC subset of the closed
    /// set — `Some(&'static str)` for the one arm whose diagnostic bytes
    /// carry a `usize` payload and format through the shared
    /// `"{length} {descriptor} (need {})"` template
    /// ([`Self::ExtraElements`] → [`Self::EXTRA_ELEMENTS_DESCRIPTOR`]
    /// (`"elements"`)), and `None` for the three arms whose full
    /// diagnostic bytes bind at a `&'static str` on the STATIC axis
    /// ([`Self::EmptyList`], [`Self::MissingDefault`],
    /// [`Self::NonSymbolName`]) and carry no per-role descriptor slot.
    ///
    /// Peer projection to [`Self::label_static`] on the sibling STATIC
    /// 3-of-4 subset carving — the two projections together partition
    /// the four-arm closed set into its STATIC ⊕ DYNAMIC halves at zero
    /// allocation cost. Callers holding a variant of unknown identity
    /// thread it through BOTH projections; exactly ONE of
    /// `label_static(self)` and `descriptor_dynamic(self)` returns
    /// `Some` for every legal variant (`label_static` on the three-arm
    /// STATIC subset, `descriptor_dynamic` on the one-arm DYNAMIC
    /// subset). The partition is pinned by the truth-table test
    /// `optional_param_malformed_reason_static_dynamic_projections_partition_closed_set`.
    ///
    /// The `const fn` posture matches [`Self::label_static`],
    /// [`TemplateInvariantKind::descriptor_dynamic`], and every peer
    /// closed-set projection method on the substrate — the projection
    /// evaluates at rustc const-eval time when the variant is a const,
    /// so a future const-context consumer (an `#[allow(dead_code)] const
    /// _: Option<&'static str> = ...` static assertion, a `tatara-check`
    /// predicate binding at module-init time) picks up the DYNAMIC-
    /// subset selector without runtime dispatch.
    ///
    /// Sibling posture to
    /// [`TemplateInvariantKind::descriptor_dynamic`] on the peer
    /// bytecode-runtime algebra's DYNAMIC 2-of-4 subset carving — both
    /// project the DYNAMIC subset of a mixed-payload closed set (STATIC-
    /// only arms project to `None`) into a typed `Option<&'static str>`
    /// — the same idiom applied at two peer boundaries of the
    /// substrate's bytecode-runtime and macro-authoring surfaces at
    /// asymmetric widths (peer is 2-arm DYNAMIC; this is 1-arm DYNAMIC).
    ///
    /// Future consumers that compose against this projection: an LSP
    /// quick-fix keyed on the DYNAMIC-subset descriptor slot (surfaces
    /// `"drop the {descriptor} after the default form"` with
    /// `{descriptor}` bound to whatever this projection returns); a
    /// `tatara-check` predicate that filters a corpus's
    /// `OptionalParamMalformed` rejections into static-arm vs dynamic-
    /// arm buckets in ONE typed subset selector rather than
    /// `matches!(reason, Self::ExtraElements { .. })` gates threaded
    /// through per-consumer allocation.
    #[must_use]
    pub const fn descriptor_dynamic(self) -> Option<&'static str> {
        match self {
            Self::ExtraElements { .. } => Some(Self::EXTRA_ELEMENTS_DESCRIPTOR),
            Self::EmptyList | Self::MissingDefault | Self::NonSymbolName => None,
        }
    }

    /// Typed `Option<String>` projection over the DYNAMIC 1-of-4 subset
    /// carving of [`OptionalParamMalformedReason`]'s four-arm closed set
    /// — returns `Some(label)` for the one arm whose diagnostic bytes
    /// format their `usize` payload through the SHARED `"{length}
    /// {descriptor} (need {})"` template, and `None` for the three
    /// STATIC arms whose full bytes bind on the [`Self::label_static`]
    /// axis.
    ///
    /// Composes [`Self::descriptor_dynamic`] into the shared format
    /// template — the `{descriptor}` slot binds to the per-role
    /// [`Self::EXTRA_ELEMENTS_DESCRIPTOR`] constant the DYNAMIC arm
    /// projects through, the `{length}` slot binds the `usize` payload
    /// the enum's dynamic variant carries, and the `(need {})` suffix
    /// binds [`Self::OPTIONAL_PARAM_SPEC_ARITY`]. Pre-lift
    /// [`Self::label`]'s body carried the inline `format!("{length}
    /// elements (need {})", …)` arm hardcoding the `"elements"` noun —
    /// post-lift the shared template binds at ONE `format!(...)` site
    /// inside this method, the noun slot binds at the per-role
    /// descriptor const, and [`Self::descriptor_dynamic`] carries the
    /// arm→descriptor mapping.
    ///
    /// Peer projection to [`Self::label_static`] on the sibling STATIC
    /// 3-of-4 subset carving — the two projections together partition
    /// the four-arm closed set into its STATIC ⊕ DYNAMIC label-
    /// projection halves. [`Self::label`]'s body reduces to
    /// `label_static().map(str::to_string).or_else(||
    /// label_dynamic()).expect(...)` — ONE compositional flow over TWO
    /// typed subset projections rather than FOUR duplicated match arms
    /// (three `.to_string()` sites on the STATIC subset + one
    /// `format!(...)` site on the DYNAMIC subset in the pre-lift body).
    ///
    /// Sibling posture to [`TemplateInvariantKind::message_dynamic`] on
    /// the peer bytecode-runtime algebra's DYNAMIC 2-of-4 subset carving
    /// — both compose a per-role descriptor projection with a shared
    /// `format!(...)` template + a `usize` payload into a typed
    /// `Option<String>`. The peer's DYNAMIC subset is 2-arm wide (two
    /// noun-slot values, one shared template); this algebra's DYNAMIC
    /// subset is 1-arm wide (one noun-slot value, one shared template)
    /// — the same STATIC ⊕ DYNAMIC composition idiom at asymmetric
    /// widths.
    ///
    /// Future consumers that compose against this projection: a
    /// `tatara-check` predicate that filters a corpus's
    /// `OptionalParamMalformed` rejections into static-arm vs dynamic-
    /// arm label buckets; a Sekiban audit-trail metric that samples
    /// dynamic-arm labels without paying the allocation cost on the
    /// STATIC subset (the `None` branch short-circuits); an LSP quick-
    /// fix that suggests trimming the surplus elements based on the
    /// `{length}` payload the caller extracts from the enum before
    /// invoking this projection.
    #[must_use]
    pub fn label_dynamic(self) -> Option<String> {
        let descriptor = self.descriptor_dynamic()?;
        let length = match self {
            Self::ExtraElements { length } => length,
            Self::EmptyList | Self::MissingDefault | Self::NonSymbolName => {
                // Unreachable: descriptor_dynamic() returned Some only
                // for ExtraElements on the `?` above. Kept exhaustive
                // rather than `_ =>` so a future refactor that adds a
                // fifth dynamic arm without extending descriptor_dynamic
                // fails compilation at THIS callsite rather than at
                // runtime.
                unreachable!(
                    "descriptor_dynamic returned Some only for dynamic-arm variants; \
                     the STATIC-arm match here is unreachable via the ? short-circuit"
                )
            }
        };
        Some(format!(
            "{length} {descriptor} (need {})",
            Self::OPTIONAL_PARAM_SPEC_ARITY
        ))
    }

    /// Short human-readable clause for the parenthetical suffix of
    /// `LispError::OptionalParamMalformed`'s Display. The variants
    /// project to:
    ///
    ///   * `EmptyList`          → [`Self::EMPTY_LIST_LABEL`] (`"empty list"`)
    ///   * `MissingDefault`     → [`Self::MISSING_DEFAULT_LABEL`] (`"missing default"`)
    ///   * `ExtraElements{N}`   → `"N elements (need 2)"` (dynamic; the `2`
    ///     is [`Self::OPTIONAL_PARAM_SPEC_ARITY`])
    ///   * `NonSymbolName`      → [`Self::NON_SYMBOL_NAME_LABEL`] (`"name not a symbol"`)
    ///
    /// `label` returns `String` (rather than `&'static str`) because the
    /// `ExtraElements` arm formats its `length` payload — the other three
    /// arms route through per-role [`Self::EMPTY_LIST_LABEL`] /
    /// [`Self::MISSING_DEFAULT_LABEL`] / [`Self::NON_SYMBOL_NAME_LABEL`]
    /// constants which `.to_string()` projects through. Mirror of
    /// `TemplateInvariantKind::message()`: both return `String`, both
    /// project the closed-set typed reason into the `LispError::Display`
    /// rendering via the variant's `#[error(...)]` annotation.
    ///
    /// Composes [`Self::label_static`] (the STATIC-subset zero-allocation
    /// projection over the 3-of-4 carving) with [`Self::label_dynamic`]
    /// (the DYNAMIC-subset composition over the 1-of-4 carving). Pre-
    /// lift the three static arms carried inline `.to_string()` literals
    /// routing through the per-role `pub const`s AND the dynamic arm
    /// carried an inline `format!(...)` — post-lift the STATIC subset
    /// binds at ONE typed projection ([`Self::label_static`]) and the
    /// DYNAMIC subset binds at ONE typed projection
    /// ([`Self::label_dynamic`]), and this body reduces to
    /// `label_static().map(str::to_string).or_else(|| label_dynamic())`
    /// composing the two — exactly the shape
    /// [`TemplateInvariantKind::message`] carries on the peer bytecode-
    /// runtime algebra.
    ///
    /// The STATIC ⊕ DYNAMIC partition guarantees exactly ONE of the two
    /// projections returns `Some` for every legal variant; the `expect`
    /// arm is structurally unreachable by construction.
    #[must_use]
    pub fn label(self) -> String {
        self.label_static()
            .map(str::to_string)
            .or_else(|| self.label_dynamic())
            .expect(
                "label_static ⊕ label_dynamic partition the four-arm closed set; \
                 exactly one projection returns Some for every legal variant",
            )
    }
}

/// Closed-set identifier for the syntactic marker of a macro-template
/// unquote (`,`) or unquote-splice (`,@`). Carried as a typed slot on
/// `LispError::UnboundTemplateVar` and `LispError::NonSymbolUnquoteTarget`
/// so authoring tools (REPL, LSP, `tatara-check`) bind to variant identity
/// via `UnquoteForm::Splice` rather than substring-matching the rendered
/// `prefix` literal.
///
/// Mirror at the template-marker boundary of the prior-run `MacroDefHead`
/// (macro-definition-head closed set), `CompilerSpecIoStage`
/// (disk-persistence surface), and `TemplateInvariantKind` (bytecode-runtime
/// surface) closed-set lifts: those enums key their respective rejection
/// variants on a typed identity; this enum keys the two unquote-template
/// rejection variants (`UnboundTemplateVar`, `NonSymbolUnquoteTarget`) on a
/// typed marker identity. Adding a new unquote variant (e.g., a hypothetical
/// `,~` form) requires extending this enum, which rustc-enforces matching at
/// every projection site (`marker()`) — the closed set becomes a TYPE rather
/// than two `&'static str`-keyed slots that could drift independently.
///
/// `marker(self) -> &'static str` projects the typed `UnquoteForm` back to
/// the canonical literal for `LispError::Display` rendering. The `&'static
/// str` lifetime is load-bearing: it lets both variants project through this
/// method into their `compile error in {prefix}…:` prefix without an
/// allocation, parallel to how `MacroDefHead::keyword()` and
/// `CompilerSpecIoStage::operation()` / `label()` feed their respective
/// `LispError::*` Display impls.
///
/// Theory anchor: THEORY.md §V.1 — knowable platform; the closed set of
/// unquote markers becomes a TYPE rather than a runtime
/// string-comparison-and-format dance. A typo like `prefix: ",,"` is
/// structurally unrepresentable rather than re-asserted at the helper
/// boundary. THEORY.md §VI.1 — generation over composition; the typed enum
/// lands the structural-completeness floor for the template-marker surface,
/// parallel to how `MacroDefHead` lands it for the macro-definition-head
/// surface and `CompilerSpecIoStage` for the disk-persistence surface.
/// THEORY.md §II.1 invariant 1 (typed entry): a non-symbol unquote target /
/// an unbound template var is exactly the failure mode the typed-entry gate
/// exists to reject, and the marker identity is part of the proof.
#[derive(Debug, Clone, Copy, PartialEq, Eq, tatara_closed_set::DeriveClosedSet)]
#[closed_set(via = "marker", display, generate_unknown = "unquote form")]
pub enum UnquoteForm {
    /// `,x` — single-value substitution. The `,` marker; the inner symbol
    /// is substituted with its bound value at template expansion.
    Unquote,
    /// `,@x` — list-splice substitution. The `,@` marker; the inner symbol
    /// must be bound to a list, whose elements are flattened into the
    /// containing list at template expansion.
    Splice,
}

impl UnquoteForm {
    /// The closed set of two template-marker syntactic forms — single
    /// source of truth that drives the [`Self::marker`] / [`fmt::Display`]
    /// projection AND the [`FromStr`] decode sweep keyed on
    /// [`Self::marker`]. Adding a hypothetical third variant (e.g. a
    /// `,~` reverse-unquote, a `,?` conditional-unquote) lands at one
    /// [`Self::ALL`] entry + one [`Self::marker`] arm — exhaustively
    /// checked by the compiler (the `[Self; 2]` array literal forces
    /// the arity) AND by the per-variant truth-table tests below.
    ///
    /// Sibling closed-set lift to every other typed-shape enum the
    /// substrate carries: this crate's own [`SexpShape::ALL`] (the
    /// twelve reachable outer shapes — superset on the structural axis
    /// of the `Sexp` algebra), [`crate::ast::AtomKind::ALL`] (the six
    /// atomic-payload kinds — peer axis on the same algebra),
    /// [`crate::ast::QuoteForm`] (the four homoiconic prefix-wrappers
    /// — superset of THIS enum's two template markers via the 2-of-4
    /// projection [`crate::ast::QuoteForm::as_unquote_form`]), and the
    /// cross-crate `tatara-process` family (`ConditionKind::ALL`,
    /// `ProcessPhase::ALL`, `ProcessSignal::ALL`, `ChannelKind::ALL`,
    /// `IntentKind::ALL`, `LifetimeKind::ALL`, `RequestorKind::ALL`,
    /// `ReceiptKind::ALL`, …) every one of which paired its typed
    /// projection with `ALL` before this lift.
    ///
    /// Future consumers that compose against `ALL`: LSP / REPL
    /// completion for the operator-facing rendered template-marker
    /// (every `compile error in {prefix}…:` substring in `LispError`'s
    /// rendered diagnostics for a template-substitution rejection keys
    /// on this set's projection through [`Self::marker`]);
    /// `tatara-check` coverage assertions over which template markers
    /// reach a `NonSymbolUnquoteTarget` / `UnboundTemplateVar` arm at
    /// all — the typed sweep replaces a per-callsite vocabulary of two
    /// `&'static str` literals; any future audit-trail metric jointly
    /// labeled by [`Self::marker`] (e.g.
    /// `tatara_lisp_unbound_template_var_total{prefix=","}`) — the
    /// metric label set IS [`Self::ALL`] mapped through
    /// [`Self::marker`]; any future structural rewriter (typed
    /// analogue of MLIR's `op.walk<UnquoteFormOp>()`) that wants to
    /// sweep over every template marker in a typed sequence.
    pub const ALL: [Self; 2] = [Self::Unquote, Self::Splice];

    /// Canonical `&'static str` template-marker bytes for the
    /// [`Self::Unquote`] substitution — aliases
    /// [`crate::ast::QuoteForm::UNQUOTE_PREFIX`] on the UnquoteForm ⊂
    /// QuoteForm 2-of-4 subset carving so the marker-level per-role
    /// bytes bind at ONE `pub const` on the parent superset's Unquote
    /// arm rather than at TWO sites (the per-role `pub const` AND a
    /// parallel inline literal). Per-role peer of `Self::Unquote` on
    /// the closed-set template-substitution algebra; consumers reach
    /// for `UnquoteForm::UNQUOTE_MARKER` when the caller has a variant
    /// in hand at compile time and wants the canonical diagnostic
    /// bytes without runtime dispatch through [`Self::marker`].
    ///
    /// Sibling posture to [`crate::ast::AtomKind::SYMBOL_LABEL`] et al
    /// (commit fc126b8) — both pin the invariant that a typed-subset
    /// enum's per-role bytes are structurally derived from the parent
    /// superset's per-role `pub const` via a `pub const = Parent::CONST`
    /// alias rather than through parallel literal-discipline sites.
    pub const UNQUOTE_MARKER: &'static str = crate::ast::QuoteForm::UNQUOTE_PREFIX;

    /// Canonical `&'static str` template-marker bytes for the
    /// [`Self::Splice`] list-substitution — aliases
    /// [`crate::ast::QuoteForm::UNQUOTE_SPLICE_PREFIX`] on the
    /// UnquoteForm ⊂ QuoteForm 2-of-4 subset carving. Per-role peer of
    /// `Self::Splice`; the `,@` two-byte prefix is the ONLY multi-char
    /// bytes payload on the UnquoteForm algebra — every other marker
    /// is a single-byte comma rendered as `&'static str`.
    pub const SPLICE_MARKER: &'static str = crate::ast::QuoteForm::UNQUOTE_SPLICE_PREFIX;

    /// Closed-set forced-arity ALL array over the canonical template-
    /// marker `&'static str` bytes, in declaration order matching
    /// [`Self::ALL`] element-wise (pinned by
    /// `unquote_form_markers_align_with_all_by_index`). Sibling posture
    /// to [`crate::ast::QuoteForm::PREFIXES`] (`[&'static str; 4]` —
    /// the superset carving this UnquoteForm subset embeds into),
    /// [`crate::ast::AtomKind::LABELS`] (`[&'static str; 6]` — sibling
    /// subset-through-parent alias on the AtomKind ⊂ SexpShape
    /// carving), [`SexpShape::LABELS`] (`[&'static str; 12]`),
    /// [`ExpectedKwargShape::LABELS`] (`[&'static str; 7]`),
    /// [`KwargPathKind::LABELS`] (`[&'static str; 3]`),
    /// [`MacroDefHead::KEYWORDS`] (`[&'static str; 3]`),
    /// [`crate::ast::Atom::BOOL_LITERALS`] (`[&'static str; 2]`), and
    /// [`crate::macro_expand::MacroParams::LAMBDA_LIST_KEYWORDS`]
    /// (`[&'static str; 2]`) — every closed-set outer projection on
    /// the substrate that carries an `&'static str`-per-variant marker
    /// now pins its per-role canonical bytes at ONE `pub const` per
    /// role PLUS an ALL array for family-wide consumers.
    ///
    /// Pre-lift the two template-marker bytes had NO per-role primitive
    /// on this closed-set subset algebra — a consumer with an
    /// `UnquoteForm` variant in hand at compile time reaching for the
    /// canonical marker bytes had to spell
    /// `UnquoteForm::Splice.marker()` (runtime dispatch through the
    /// composition [`Self::to_quote_form`] +
    /// [`crate::ast::QuoteForm::prefix`]) OR reach across the algebra
    /// boundary into [`crate::ast::QuoteForm::UNQUOTE_SPLICE_PREFIX`]
    /// and re-derive the UnquoteForm ⊂ QuoteForm variant pairing at
    /// the call site. Post-lift the TWO canonical bytes bind at ONE
    /// `pub const` per role on the typed [`UnquoteForm`] algebra AND
    /// at [`Self::MARKERS`] as a family-wide forced-arity array — a
    /// future LSP / REPL completion bar keyed on
    /// `UnquoteForm::MARKERS`, a `tatara-check` coverage sweep over
    /// the template-marker arms of a `NonSymbolUnquoteTarget` /
    /// `UnboundTemplateVar` corpus, or a Sekiban audit-trail metric
    /// jointly labeled by the template marker
    /// (`tatara_lisp_unbound_template_var_total{prefix=","}`) reads
    /// through the typed constants on this subset algebra without
    /// re-deriving the 2-of-4 carving inline.
    ///
    /// Each entry is byte-for-byte identical to the corresponding
    /// [`crate::ast::QuoteForm`] Unquote / UnquoteSplice arm — an
    /// intentional cross-axis overlap pinned by
    /// `unquote_form_per_role_markers_alias_quote_form_per_role_prefixes_byte_for_byte`
    /// so a future marker rename on EITHER side (a
    /// [`crate::ast::QuoteForm`] `","` → `",."` drift, or an
    /// [`UnquoteForm`] rename that skips the alias) fails-loudly at
    /// the alias test rather than as a silent operator-facing
    /// vocabulary fracture. Adding a hypothetical third template-
    /// marker (e.g. a `,~` reverse-unquote, a `,?` conditional-unquote)
    /// extends [`Self::ALL`] AND [`Self::MARKERS`] AND adds ONE per-
    /// role `pub const` alias in lockstep — rustc's forced-arity check
    /// on the two `[_; N]` arrays fails compilation if EITHER ALL
    /// array grows without the other.
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the two
    /// canonical template-marker bytes bind at ONE typed
    /// `[&'static str; 2]` array on the closed-set UnquoteForm algebra
    /// rather than at zero-primitive-on-this-subset-plus-two-inline-
    /// lookups scattered across the substrate. THEORY.md §V.1 —
    /// knowable platform; the family's cardinality becomes a TYPE-
    /// level constant on the substrate algebra rather than a per-
    /// consumer runtime dispatch through the composition. THEORY.md
    /// §VI.1 — generation over composition; the family-wide contract
    /// sweeps (alignment with `ALL`, pairwise disjointness, membership
    /// through [`Self::marker`]) emerge from the composition of TWO
    /// substrate primitives (this `pub const` array + the two per-role
    /// `pub const *_MARKER` aliases) rather than as per-variant inline
    /// assertions duplicated at each call site.
    pub const MARKERS: [&'static str; 2] = [Self::UNQUOTE_MARKER, Self::SPLICE_MARKER];

    /// Canonical reader-lead `char` byte for BOTH [`Self::Unquote`] AND
    /// [`Self::Splice`] — aliases [`crate::ast::QuoteForm::UNQUOTE_LEAD`]
    /// (which is `','`) on the UnquoteForm ⊂ QuoteForm 2-of-4 subset
    /// carving so the reader-lead-char per-role bytes bind at ONE
    /// `pub const` on the parent superset's Unquote arm rather than at
    /// TWO sites (the per-role `pub const` AND a parallel inline `','`
    /// literal). Per-role peer of [`Self::Unquote`] on the closed-set
    /// template-substitution algebra; consumers reach for
    /// `UnquoteForm::UNQUOTE_LEAD` when the caller has a variant in
    /// hand at compile time and wants the canonical reader-entry lead
    /// char without runtime dispatch through
    /// `self.to_quote_form().lead_char()`.
    ///
    /// The (2-of-2 collapse) shape-asymmetry is load-bearing: BOTH
    /// UnquoteForm arms share the SAME lead char at
    /// [`crate::ast::QuoteForm::lead_char`]'s `Self::Unquote |
    /// Self::UnquoteSplice => Self::UNQUOTE_LEAD` merged arm — the
    /// reader's outer tokenizer dispatch selects between quote-family
    /// entry and every non-quote-family arm on lead char alone, with
    /// the `,`-vs-`,@` disambiguation falling out of the reader's
    /// second-char peek (`@` promotes to Splice) rather than at
    /// [`crate::ast::QuoteForm::from_lead_char`]'s decode. This
    /// UnquoteForm ⊂ QuoteForm subset's LEAD alias is
    /// SHAPE-ASYMMETRIC-COLLAPSE to `[Self::UNQUOTE_LEAD]` (a
    /// single-entry ALL — see [`Self::LEADS`]) because both subset
    /// arms project to the same superset lead byte, mirroring the
    /// parent's `[QUOTE_LEAD, QUASIQUOTE_LEAD, UNQUOTE_LEAD]` shape-
    /// asymmetric collapse (3 distinct leads for 4 arms).
    ///
    /// Sibling posture to [`Self::UNQUOTE_MARKER`] (commit 3640f76 —
    /// aliases the reader-punctuation prefix vocabulary `","`),
    /// [`Self::UNQUOTE_LABEL`] (commit da68af5 — aliases the
    /// substrate diagnostic-label vocabulary `"unquote"`),
    /// [`Self::UNQUOTE_IAC_FORGE_TAG`] (commit 6acab84 — aliases the
    /// iac-forge canonical-form vocabulary `"unquote"`), and
    /// [`Self::UNQUOTE_HASH_DISCRIMINATOR`] (commit eca4730 —
    /// aliases the outer-`Sexp` cache-key `u8` byte `5u8`) — this
    /// FIFTH per-role `pub const` axis closes the (reader-lead char,
    /// reader-prefix bytes, diagnostic label, iac-forge canonical-form
    /// tag, outer-`Sexp` cache-key byte) QUINTUPLE on the UnquoteForm
    /// subset algebra in lockstep with the same quintuple on the
    /// parent [`crate::ast::QuoteForm`] superset.
    pub const UNQUOTE_LEAD: char = crate::ast::QuoteForm::UNQUOTE_LEAD;

    /// Closed-set forced-arity ALL array over the canonical
    /// reader-lead `char` bytes on the UnquoteForm ⊂ QuoteForm 2-of-4
    /// subset carving — SHAPE-ASYMMETRIC-COLLAPSE `[char; 1]` on this
    /// subset carving (both arms share the same `','` lead byte), peer
    /// to [`crate::ast::QuoteForm::LEADS`] (`[char; 3]` on the 4-arm
    /// superset carving, itself shape-asymmetric-collapse from 4 arms
    /// to 3 distinct leads because [`crate::ast::QuoteForm::Unquote`]
    /// and [`crate::ast::QuoteForm::UnquoteSplice`] share the same
    /// lead byte).
    ///
    /// Peer axis to [`Self::MARKERS`] on the SAME reader-vocabulary
    /// production surface: [`Self::MARKERS`] holds the arm-per-arm
    /// prefix bytes (`","`, `",@"` — cardinality matches [`Self::ALL`]
    /// at `[_; 2]`), and [`Self::LEADS`] holds the DISTINCT lead-byte
    /// sub-vocabulary the reader's outer tokenizer dispatch selects on
    /// (`","` alone — cardinality collapses from 2 arms to 1 distinct
    /// lead byte). The shape-asymmetric arities `[_; 2]` for MARKERS
    /// vs `[_; 1]` for LEADS ARE the shared-lead-char structural
    /// collapse invariant carried at the type-system level — a future
    /// third UnquoteForm arm (e.g. a hypothetical `,~` reverse-unquote
    /// binding a NEW lead char `~`) would extend BOTH [`Self::MARKERS`]
    /// to `[_; 3]` AND [`Self::LEADS`] to `[_; 2]` in lockstep, adding
    /// ONE per-role LEAD `pub const` alias.
    ///
    /// Sibling posture to [`crate::ast::QuoteForm::LEADS`] (the
    /// superset carving's own DISTINCT-lead-byte ALL array on the
    /// SAME reader-lead-vocabulary axis), [`Self::MARKERS`],
    /// [`Self::LABELS`], [`Self::IAC_FORGE_TAGS`], and
    /// [`Self::HASH_DISCRIMINATORS`] — every one a forced-arity ALL
    /// array on the SAME UnquoteForm closed-set algebra spanning ONE
    /// of the production byte-vocabularies the substrate carries per
    /// role.
    ///
    /// Pre-lift the sole distinct lead byte had NO per-role primitive
    /// on this closed-set subset algebra — a consumer wanting the
    /// UnquoteForm-only reader-lead-byte set had to spell the two-
    /// step composition `UnquoteForm::ALL.iter().map(|uf|
    /// uf.to_quote_form().lead_char()).collect()` (with a manual dedup
    /// downstream to project the 2-arm output onto its 1 distinct
    /// byte) OR reach across into
    /// [`crate::ast::QuoteForm::UNQUOTE_LEAD`] and re-derive the
    /// UnquoteForm ⊂ QuoteForm variant-share pairing at the call site.
    /// Post-lift the sole canonical byte binds at ONE `pub const` on
    /// the typed [`UnquoteForm`] algebra AND at [`Self::LEADS`] as a
    /// family-wide `[char; 1]` forced-arity array — a future
    /// substrate-facing reader-classifier keyed on the substitution-
    /// subset's lead-vocabulary specifically (a future LSP completion
    /// bar filtering to template-substitution-only entries, a
    /// syntax-highlighter's per-char classifier for the reader-entry
    /// template-marker subset, a `tatara-check` predicate
    /// `(check-substitution-subset-lead-partition …)` that verifies
    /// the subset's sole lead byte sits inside the parent
    /// [`crate::ast::QuoteForm::LEADS`] set) reads through the typed
    /// constants without re-deriving the 2-of-4 → 1-of-3 collapse
    /// inline.
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the sole
    /// canonical distinct-lead byte on the substitution-subset
    /// carving binds at ONE typed `[char; 1]` array on the closed-set
    /// UnquoteForm algebra rather than as a zero-primitive-on-this-
    /// subset-plus-inline-lookup at each callsite. Closes the FIFTH
    /// per-role `pub const` axis on the UnquoteForm subset carving in
    /// lockstep with the same quintuple on [`crate::ast::QuoteForm`].
    /// THEORY.md §V.1 — knowable platform; the SHAPE-ASYMMETRIC-
    /// COLLAPSE distinct-lead-byte sub-vocabulary becomes load-bearing
    /// typed data on the substrate's substitution-subset closed set —
    /// the type-system carries the "both subset arms share ONE lead"
    /// invariant at the `[char; 1]` arity rather than as a comment on
    /// a lookup site. THEORY.md §VI.1 — generation over composition;
    /// the family-wide contract sweeps (alignment with the parent
    /// [`crate::ast::QuoteForm::LEADS`]'s subset image, cardinality
    /// containment `Self::LEADS.len() <= Self::ALL.len()` — the
    /// collapse witness) emerge from ONE substrate primitive plus the
    /// per-role LEAD alias rather than from per-consumer runtime
    /// dispatch through the two-step composition.
    pub const LEADS: [char; 1] = [Self::UNQUOTE_LEAD];

    /// Canonical `&'static str` iac-forge canonical-form tag bytes for
    /// the [`Self::Unquote`] substitution — aliases
    /// [`crate::ast::QuoteForm::UNQUOTE_IAC_FORGE_TAG`] on the
    /// UnquoteForm ⊂ QuoteForm 2-of-4 subset carving so the
    /// iac-forge-tag-level per-role bytes bind at ONE `pub const` on
    /// the parent superset's Unquote arm rather than at TWO sites (the
    /// per-role `pub const` AND a parallel inline literal). Per-role
    /// peer of [`Self::Unquote`] on the closed-set template-
    /// substitution algebra; consumers reach for
    /// `UnquoteForm::UNQUOTE_IAC_FORGE_TAG` when the caller has a
    /// variant in hand at compile time and wants the canonical iac-
    /// forge interop-tag bytes without runtime dispatch through
    /// [`Self::iac_forge_tag`].
    ///
    /// Sibling posture to [`Self::UNQUOTE_MARKER`] (commit 3640f76) —
    /// both pin the invariant that a typed-subset enum's per-role
    /// bytes are structurally derived from the parent superset's
    /// per-role `pub const` via a `pub const = Parent::CONST` alias
    /// rather than through parallel literal-discipline sites. Where
    /// [`Self::UNQUOTE_MARKER`] aliases the reader-punctuation
    /// vocabulary (`","`) shared with the Lisp source-code surface,
    /// this constant aliases the iac-forge canonical-form vocabulary
    /// (`"unquote"`) shared with the cross-crate attestation surface
    /// — the two peer axes span the two production byte-vocabularies
    /// the parent [`crate::ast::QuoteForm`] closed set carries, and
    /// both now bind through the same aliased typed source of truth on
    /// this UnquoteForm subset.
    pub const UNQUOTE_IAC_FORGE_TAG: &'static str = crate::ast::QuoteForm::UNQUOTE_IAC_FORGE_TAG;

    /// Canonical `&'static str` iac-forge canonical-form tag bytes for
    /// the [`Self::Splice`] list-substitution — aliases
    /// [`crate::ast::QuoteForm::UNQUOTE_SPLICE_IAC_FORGE_TAG`] on the
    /// UnquoteForm ⊂ QuoteForm 2-of-4 subset carving. Per-role peer of
    /// [`Self::Splice`]; the `"unquote-splicing"` bytes are the ONLY
    /// hyphenated multi-syllable canonical-form tag on the UnquoteForm
    /// algebra — the other iac-forge tag is a single word.
    ///
    /// INTENTIONALLY diverges from [`crate::error::SexpShape::label`]'s
    /// splice arm (which renders `"unquote-splice"` for the diagnostic
    /// surface) — the iac-forge canonical-form REQUIRES the
    /// `unquote-splicing` spelling, while the substrate's operator-
    /// facing diagnostic surface renders the shorter idiom. The typed
    /// per-role `pub const` documents the divergence structurally: a
    /// future "consolidation" PR that homogenizes the two axes would
    /// have to touch this constant explicitly, surfacing the boundary-
    /// distinct invariant at code-review time rather than silently.
    pub const SPLICE_IAC_FORGE_TAG: &'static str =
        crate::ast::QuoteForm::UNQUOTE_SPLICE_IAC_FORGE_TAG;

    /// Closed-set forced-arity ALL array over the canonical iac-forge
    /// canonical-form tag `&'static str` bytes, in declaration order
    /// matching [`Self::ALL`] element-wise (pinned by
    /// `unquote_form_iac_forge_tags_align_with_all_by_index`). Sibling
    /// posture to [`Self::MARKERS`] (`[&'static str; 2]` on the reader-
    /// punctuation axis of the SAME [`UnquoteForm`] closed set — commit
    /// 3640f76) and to [`crate::ast::QuoteForm::IAC_FORGE_TAGS`]
    /// (`[&'static str; 4]` — the superset carving this UnquoteForm
    /// subset embeds into on the SAME iac-forge canonical-form axis).
    /// The (canonical iac-forge tag) axis + the (canonical reader
    /// marker) axis together span the two production byte-vocabularies
    /// the [`UnquoteForm`] closed set carries — [`Self::MARKERS`] holds
    /// the Lisp source-code prefixes (`","`, `",@"`) the reader
    /// tokenizes on, [`Self::IAC_FORGE_TAGS`] holds the cross-crate
    /// canonical-form tag strings (`"unquote"`, `"unquote-splicing"`)
    /// the iac-forge interop layer round-trips through.
    ///
    /// Pre-lift the two iac-forge tag bytes had NO per-role primitive
    /// on this closed-set subset algebra — a consumer with an
    /// [`UnquoteForm`] variant in hand at compile time reaching for
    /// the canonical tag bytes had to spell
    /// `UnquoteForm::Splice.iac_forge_tag()` (runtime dispatch through
    /// the composition [`Self::to_quote_form`] +
    /// [`crate::ast::QuoteForm::iac_forge_tag`]) OR reach across the
    /// algebra boundary into
    /// [`crate::ast::QuoteForm::UNQUOTE_SPLICE_IAC_FORGE_TAG`] and
    /// re-derive the UnquoteForm ⊂ QuoteForm variant pairing at the
    /// call site. Post-lift the TWO canonical bytes bind at ONE
    /// `pub const` per role on the typed [`UnquoteForm`] algebra AND
    /// at [`Self::IAC_FORGE_TAGS`] as a family-wide forced-arity array
    /// — a future LSP / REPL completion bar keyed on
    /// `UnquoteForm::IAC_FORGE_TAGS`, a `tatara-check` coverage sweep
    /// over the template-marker arms of an attestation-payload corpus,
    /// or a Sekiban audit-trail metric jointly labeled by the iac-
    /// forge tag (`tatara_lisp_iac_forge_tag_total{tag="unquote"}`)
    /// reads through the typed constants on this subset algebra
    /// without re-deriving the 2-of-4 carving inline.
    ///
    /// Each entry is byte-for-byte identical to the corresponding
    /// [`crate::ast::QuoteForm`] Unquote / UnquoteSplice arm — an
    /// intentional cross-axis overlap pinned by
    /// `unquote_form_per_role_iac_forge_tags_alias_quote_form_per_role_iac_forge_tags_byte_for_byte`
    /// so a future canonical-form tag rename on EITHER side (a
    /// [`crate::ast::QuoteForm`] `"unquote"` → `"unquote-value"` drift,
    /// or an [`UnquoteForm`] rename that skips the alias) fails-loudly
    /// at the alias test rather than as a silent cross-crate
    /// canonical-form vocabulary fracture that mis-hashes BLAKE3
    /// attestation keys. Adding a hypothetical third template-marker
    /// (e.g. a `,~` reverse-unquote with its own canonical `"reverse-
    /// unquote"` tag, a `,?` conditional-unquote with its own tag)
    /// extends [`Self::ALL`] AND [`Self::IAC_FORGE_TAGS`] AND adds ONE
    /// per-role `pub const` alias in lockstep — rustc's forced-arity
    /// check on the two `[_; N]` arrays fails compilation if EITHER
    /// ALL array grows without the other.
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the two
    /// canonical iac-forge tag bytes bind at ONE typed
    /// `[&'static str; 2]` array on the closed-set UnquoteForm algebra
    /// rather than at zero-primitive-on-this-subset-plus-two-inline-
    /// lookups scattered across the substrate. THEORY.md §V.1 —
    /// knowable platform; the family's cardinality becomes a TYPE-
    /// level constant on the substrate algebra rather than a per-
    /// consumer runtime dispatch through the composition. THEORY.md
    /// §V.3 — three-pillar attestation; the canonical iac-forge tag
    /// bytes are the surface the substrate's cross-crate `intent_hash`
    /// pillar composes over for every substitution-subset arm of a
    /// homoiconic template AST — binding the two bytes on the typed
    /// algebra makes attestation-key drift a compile error rather than
    /// a silent BLAKE3 mis-hash. THEORY.md §VI.1 — generation over
    /// composition; the family-wide contract sweeps (alignment with
    /// `ALL`, pairwise disjointness, membership through
    /// [`Self::iac_forge_tag`]) emerge from the composition of TWO
    /// substrate primitives (this `pub const` array + the two per-role
    /// `pub const *_IAC_FORGE_TAG` aliases) rather than as per-variant
    /// inline assertions duplicated at each call site.
    pub const IAC_FORGE_TAGS: [&'static str; 2] =
        [Self::UNQUOTE_IAC_FORGE_TAG, Self::SPLICE_IAC_FORGE_TAG];

    /// Canonical `&'static str` diagnostic label bytes for the
    /// [`Self::Unquote`] substitution — aliases
    /// [`crate::ast::QuoteForm::UNQUOTE_LABEL`] on the UnquoteForm ⊂
    /// QuoteForm 2-of-4 subset carving so the label-level per-role
    /// bytes bind at ONE `pub const` on the parent superset's Unquote
    /// arm (which itself aliases [`SexpShape::UNQUOTE_LABEL`] on the
    /// QuoteForm ⊂ SexpShape 4-of-12 subset carving) rather than at
    /// multiple sites (the per-role `pub const` PLUS a parallel inline
    /// literal). Per-role peer of [`Self::Unquote`] on the closed-set
    /// template-substitution algebra; consumers reach for
    /// `UnquoteForm::UNQUOTE_LABEL` when the caller has a variant in
    /// hand at compile time and wants the canonical diagnostic bytes
    /// without runtime dispatch through [`Self::label`].
    ///
    /// Sibling posture to [`Self::UNQUOTE_MARKER`] (commit 3640f76 —
    /// aliases the reader-punctuation vocabulary `","`) and to
    /// [`Self::UNQUOTE_IAC_FORGE_TAG`] (commit 6acab84 — aliases the
    /// iac-forge canonical-form vocabulary `"unquote"`) — this THIRD
    /// per-role `pub const` axis closes the (reader punctuation,
    /// diagnostic label, iac-forge canonical-form) triple on the
    /// UnquoteForm subset algebra in lockstep with the same triple
    /// on the parent [`crate::ast::QuoteForm`] superset. At the
    /// Unquote arm the diagnostic label AND the iac-forge tag AND the
    /// substrate-facing `SexpShape::UNQUOTE_LABEL` all agree
    /// byte-for-byte on `"unquote"`; the divergence axis lives at
    /// [`Self::SPLICE_LABEL`] (`"unquote-splice"`) vs
    /// [`Self::SPLICE_IAC_FORGE_TAG`] (`"unquote-splicing"`).
    pub const UNQUOTE_LABEL: &'static str = crate::ast::QuoteForm::UNQUOTE_LABEL;

    /// Canonical `&'static str` diagnostic label bytes for the
    /// [`Self::Splice`] list-substitution — aliases
    /// [`crate::ast::QuoteForm::UNQUOTE_SPLICE_LABEL`] on the
    /// UnquoteForm ⊂ QuoteForm 2-of-4 subset carving. Per-role peer of
    /// [`Self::Splice`]. The `"unquote-splice"` short label matches
    /// [`SexpShape::UNQUOTE_SPLICE_LABEL`] byte-for-byte through the
    /// alias chain and diverges INTENTIONALLY from
    /// [`Self::SPLICE_IAC_FORGE_TAG`] (`"unquote-splicing"`) — the two
    /// projections key the SAME closed set on TWO distinct boundaries
    /// (substrate diagnostic surface vs cross-crate Common-Lisp
    /// canonical form). See [`Self::UNQUOTE_LABEL`] for the alias-
    /// chain shape both siblings share.
    pub const SPLICE_LABEL: &'static str = crate::ast::QuoteForm::UNQUOTE_SPLICE_LABEL;

    /// Closed-set forced-arity ALL array over the canonical diagnostic
    /// label `&'static str` bytes, in declaration order matching
    /// [`Self::ALL`] element-wise (pinned by
    /// `unquote_form_labels_align_with_all_by_index`). Sibling posture
    /// to [`Self::MARKERS`] (`[&'static str; 2]` — reader-punctuation
    /// axis) and [`Self::IAC_FORGE_TAGS`] (`[&'static str; 2]` — iac-
    /// forge canonical-form axis) on the SAME UnquoteForm closed set,
    /// and to [`crate::ast::QuoteForm::LABELS`] (`[&'static str; 4]` —
    /// the superset carving this UnquoteForm subset embeds into on the
    /// SAME diagnostic-label axis). The (diagnostic label) axis + the
    /// (reader punctuation) axis + the (iac-forge canonical-form)
    /// axis together span the THREE production byte-vocabularies the
    /// [`UnquoteForm`] closed set carries — [`Self::MARKERS`] holds
    /// the Lisp source-code prefixes (`","`, `",@"`), [`Self::LABELS`]
    /// holds the substrate diagnostic labels (`"unquote"`,
    /// `"unquote-splice"`), [`Self::IAC_FORGE_TAGS`] holds the cross-
    /// crate canonical-form tag strings (`"unquote"`, `"unquote-
    /// splicing"`).
    ///
    /// Pre-lift the two diagnostic-label bytes had NO per-role
    /// primitive on this closed-set subset algebra — a consumer with
    /// an [`UnquoteForm`] variant in hand at compile time reaching for
    /// the canonical diagnostic bytes had to spell the two-step
    /// composition `uf.to_quote_form().label()` OR reach across the
    /// algebra boundary into
    /// [`crate::ast::QuoteForm::UNQUOTE_SPLICE_LABEL`] and re-derive
    /// the UnquoteForm ⊂ QuoteForm variant pairing at the call site.
    /// Post-lift the TWO canonical bytes bind at ONE `pub const` per
    /// role on the typed [`UnquoteForm`] algebra AND at
    /// [`Self::LABELS`] as a family-wide forced-arity array — a
    /// future LSP / REPL completion bar keyed on
    /// `UnquoteForm::LABELS`, a `tatara-check` coverage sweep over
    /// the template-marker arms of a diagnostic corpus, or a Sekiban
    /// audit-trail metric jointly labeled by the diagnostic label
    /// (`tatara_lisp_unbound_template_var_total{label="unquote"}`)
    /// reads through the typed constants on this subset algebra
    /// without re-deriving the 2-of-4 carving inline.
    ///
    /// Each entry is byte-for-byte identical to the corresponding
    /// [`crate::ast::QuoteForm`] Unquote / UnquoteSplice arm — an
    /// intentional cross-axis overlap pinned by
    /// `unquote_form_per_role_labels_alias_quote_form_per_role_labels_byte_for_byte`
    /// so a future label rename on EITHER side (a
    /// [`crate::ast::QuoteForm`] `"unquote"` → `"substitute"` drift,
    /// or an [`UnquoteForm`] rename that skips the alias) fails-
    /// loudly at the alias test rather than as a silent operator-
    /// facing vocabulary fracture. Adding a hypothetical third
    /// template-marker (e.g. a `,~` reverse-unquote) extends
    /// [`Self::ALL`] AND [`Self::LABELS`] AND adds ONE per-role
    /// `pub const` alias in lockstep — rustc's forced-arity check on
    /// the two `[_; N]` arrays fails compilation if EITHER array
    /// grows without the other.
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the two
    /// canonical diagnostic label bytes bind at ONE typed
    /// `[&'static str; 2]` array on the closed-set UnquoteForm algebra
    /// rather than at zero-primitive-on-this-subset-plus-two-inline-
    /// lookups scattered across the substrate. Closes the THIRD
    /// per-role `pub const` axis on the UnquoteForm subset carving in
    /// lockstep with the same triple on [`crate::ast::QuoteForm`].
    /// THEORY.md §V.1 — knowable platform; the family's cardinality
    /// becomes a TYPE-level constant on the substrate algebra rather
    /// than a per-consumer runtime dispatch through the composition.
    /// THEORY.md §VI.1 — generation over composition; the family-wide
    /// contract sweeps (alignment with `ALL`, pairwise disjointness,
    /// membership through [`Self::label`]) emerge from the composition
    /// of TWO substrate primitives (this `pub const` array + the two
    /// per-role `pub const *_LABEL` aliases) rather than as per-
    /// variant inline assertions duplicated at each call site.
    /// THEORY.md §II.1 invariant 5 — composition preserves proofs;
    /// the alias-chain composition law `UnquoteForm::LABELS[i] ==
    /// UnquoteForm::ALL[i].to_quote_form().label()` binds the family-
    /// wide array to the composition through [`Self::to_quote_form`] +
    /// [`crate::ast::QuoteForm::label`] at rustc time.
    pub const LABELS: [&'static str; 2] = [Self::UNQUOTE_LABEL, Self::SPLICE_LABEL];

    /// Canonical `u8` outer-`Sexp` cache-key byte for the
    /// [`Self::Unquote`] substitution — `5`. Aliases
    /// [`crate::ast::QuoteForm::UNQUOTE_HASH_DISCRIMINATOR`] on the
    /// UnquoteForm ⊂ QuoteForm 2-of-4 subset carving so the byte-
    /// discriminator-level per-role bytes bind at ONE
    /// `pub(crate) const` on the parent superset's Unquote arm rather
    /// than at TWO sites (the per-role `pub(crate) const` AND a
    /// parallel inline literal). Per-role peer of [`Self::Unquote`] on
    /// the closed-set template-substitution algebra; consumers reach
    /// for `UnquoteForm::UNQUOTE_HASH_DISCRIMINATOR` when the caller
    /// has a variant in hand at compile time and wants the canonical
    /// cache-key byte without runtime dispatch through
    /// [`Self::hash_discriminator`] (which itself composes through
    /// [`Self::to_quote_form`] +
    /// [`crate::ast::QuoteForm::hash_discriminator`]).
    ///
    /// Sibling posture to [`Self::UNQUOTE_MARKER`] (commit 3640f76 —
    /// aliases the reader-punctuation vocabulary `","`),
    /// [`Self::UNQUOTE_IAC_FORGE_TAG`] (commit 6acab84 — aliases the
    /// iac-forge canonical-form vocabulary `"unquote"`), and
    /// [`Self::UNQUOTE_LABEL`] (commit da68af5 — aliases the substrate
    /// diagnostic-label vocabulary `"unquote"`) — this FOURTH per-role
    /// `pub const` axis closes the (reader punctuation, iac-forge
    /// canonical-form, diagnostic label, outer-`Sexp` cache-key byte)
    /// quadruple on the UnquoteForm subset algebra in lockstep with
    /// the same quadruple on the parent [`crate::ast::QuoteForm`]
    /// superset. The three prior axes span the three `&'static str`
    /// production vocabularies the substrate carries at every quote-
    /// family arm; this fourth axis spans the ONE `u8` outer-`Sexp`
    /// cache-key vocabulary the substrate's
    /// [`Hash for Sexp`](crate::ast::Sexp) body composes over — so
    /// every substrate-surface byte the parent [`crate::ast::QuoteForm`]
    /// superset carries per role now has a matching per-role
    /// `pub const` on this substitution subset.
    ///
    /// `pub(crate)` because the byte-discriminator surface is an
    /// implementation detail of the substrate's
    /// [`Hash for Sexp`](crate::ast::Sexp) cache-key contract; exposing
    /// it publicly would leak the cache-key shape through the API
    /// without enabling any external consumer the three public
    /// `pub const` axes ([`Self::UNQUOTE_MARKER`],
    /// [`Self::UNQUOTE_IAC_FORGE_TAG`], [`Self::UNQUOTE_LABEL`]) don't
    /// already serve. Same posture as
    /// [`crate::ast::QuoteForm::UNQUOTE_HASH_DISCRIMINATOR`],
    /// [`crate::ast::AtomKind::SYMBOL_HASH_DISCRIMINATOR`],
    /// [`StructuralKind::NIL_HASH_DISCRIMINATOR`], and every other
    /// per-role `*_HASH_DISCRIMINATOR` `pub const` on the substrate's
    /// typed-shape family — every one is crate-private.
    pub(crate) const UNQUOTE_HASH_DISCRIMINATOR: u8 =
        crate::ast::QuoteForm::UNQUOTE_HASH_DISCRIMINATOR;

    /// Canonical `u8` outer-`Sexp` cache-key byte for the
    /// [`Self::Splice`] list-substitution — `6`. Aliases
    /// [`crate::ast::QuoteForm::UNQUOTE_SPLICE_HASH_DISCRIMINATOR`] on
    /// the UnquoteForm ⊂ QuoteForm 2-of-4 subset carving. Per-role
    /// peer of [`Self::Splice`]. The gap-free `{5, 6}` partition on
    /// the substitution-subset carving is load-bearing: the substrate's
    /// [`Hash for Sexp`](crate::ast::Sexp) body reserves `{0, 2}` for
    /// [`StructuralKind`], `{1}` for the outer [`crate::ast::Sexp::Atom`]
    /// carve, `{3, 4}` for the non-substitution quote-family arms
    /// ([`crate::ast::QuoteForm::Quote`],
    /// [`crate::ast::QuoteForm::Quasiquote`]), and `{5, 6}` for this
    /// substitution subset — a cache-key collision would leak macro-
    /// expansion cache hits across carvings. See
    /// [`Self::UNQUOTE_HASH_DISCRIMINATOR`] for the alias-chain shape
    /// both siblings share.
    pub(crate) const SPLICE_HASH_DISCRIMINATOR: u8 =
        crate::ast::QuoteForm::UNQUOTE_SPLICE_HASH_DISCRIMINATOR;

    /// Closed-set forced-arity ALL array over the canonical outer-
    /// `Sexp` cache-key `u8` bytes, in declaration order matching
    /// [`Self::ALL`] element-wise (pinned by
    /// `unquote_form_hash_discriminators_align_with_all_by_index`).
    /// Sibling posture to [`Self::MARKERS`] (`[&'static str; 2]` —
    /// reader-punctuation axis), [`Self::IAC_FORGE_TAGS`]
    /// (`[&'static str; 2]` — iac-forge canonical-form axis), and
    /// [`Self::LABELS`] (`[&'static str; 2]` — diagnostic-label axis)
    /// on the SAME UnquoteForm closed set, and to
    /// [`crate::ast::QuoteForm::HASH_DISCRIMINATORS`] (`[u8; 4]` —
    /// the superset carving this UnquoteForm subset embeds into on
    /// the SAME outer-`Sexp` cache-key axis). Every closed-set
    /// carving of the substrate's outer-`Sexp` cache-key partition
    /// now pins its per-role canonical cache-key bytes at ONE
    /// `pub(crate) const` per role PLUS an ALL array for family-wide
    /// consumers: [`Self::HASH_DISCRIMINATORS`] (`[u8; 2]` —
    /// substitution-subset), [`StructuralKind::HASH_DISCRIMINATORS`]
    /// (`[u8; 2]` — structural-residual),
    /// [`crate::ast::AtomKind::HASH_DISCRIMINATORS`] (`[u8; 6]` —
    /// atomic-payload nested inner carving),
    /// [`crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR`] (scalar
    /// `1u8` — atomic-payload outer marker),
    /// [`crate::ast::QuoteForm::HASH_DISCRIMINATORS`] (`[u8; 4]` —
    /// quote-family), and
    /// [`SexpShape::HASH_DISCRIMINATORS`] (`[u8; 12]` — full outer
    /// twelve-arm shape).
    ///
    /// Pre-lift the two cache-key bytes had NO per-role primitive on
    /// this closed-set subset algebra — a consumer with an
    /// [`UnquoteForm`] variant in hand at compile time reaching for
    /// the canonical cache-key byte had to spell the two-step
    /// composition `uf.to_quote_form().hash_discriminator()` OR reach
    /// across the algebra boundary into
    /// [`crate::ast::QuoteForm::UNQUOTE_SPLICE_HASH_DISCRIMINATOR`]
    /// and re-derive the UnquoteForm ⊂ QuoteForm variant pairing at
    /// the call site. Post-lift the TWO canonical bytes bind at ONE
    /// `pub(crate) const` per role on the typed [`UnquoteForm`]
    /// algebra AND at [`Self::HASH_DISCRIMINATORS`] as a family-wide
    /// forced-arity array — a future
    /// [`crate::macro_expand::Expander`] cache-invalidation predicate
    /// that decides on the 2-of-4 substitution-subset only, a future
    /// `tatara-check` predicate `(check-substitution-subset-cache-
    /// key-partition-injective …)` that verifies the substitution-
    /// subset carving's cache-key partition sits inside `{5, 6}`, a
    /// future `TypedRewriter<UnquoteFormOp>` sweep zipping ALL /
    /// LABELS / MARKERS / IAC_FORGE_TAGS / HASH_DISCRIMINATORS in
    /// lockstep for a family-wide (variant, label, marker, tag, byte)
    /// quintuple render, or a Sekiban audit-trail metric jointly
    /// labeled by the substitution-subset cache-key partition read
    /// through the typed constants on this subset algebra without
    /// re-deriving the 2-of-4 carving inline.
    ///
    /// Each entry is byte-for-byte identical to the corresponding
    /// [`crate::ast::QuoteForm`] Unquote / UnquoteSplice arm — an
    /// intentional cross-axis overlap pinned by
    /// `unquote_form_per_role_hash_discriminators_alias_quote_form_per_role_hash_discriminators_byte_for_byte`
    /// so a future cache-key byte reshuffling on EITHER side (a
    /// [`crate::ast::QuoteForm`] `5u8` → `7u8` drift, or an
    /// [`UnquoteForm`] rename that skips the alias) fails-loudly at
    /// the alias test rather than as a silent macro-expansion cache
    /// mis-hash. Adding a hypothetical third template-marker (e.g. a
    /// `,~` reverse-unquote) extends [`Self::ALL`] AND
    /// [`Self::HASH_DISCRIMINATORS`] AND adds ONE per-role
    /// `pub(crate) const` alias in lockstep — rustc's forced-arity
    /// check on the two `[_; N]` arrays fails compilation if EITHER
    /// array grows without the other.
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the two
    /// canonical cache-key bytes bind at ONE typed `[u8; 2]` array
    /// on the closed-set UnquoteForm algebra rather than at zero-
    /// primitive-on-this-subset-plus-two-inline-lookups scattered
    /// across the substrate. Closes the FOURTH per-role `pub const`
    /// axis on the UnquoteForm subset carving in lockstep with the
    /// same quadruple on [`crate::ast::QuoteForm`]. THEORY.md §V.1 —
    /// knowable platform; the family's cardinality becomes a TYPE-
    /// level constant on the substrate algebra rather than a per-
    /// consumer runtime dispatch through the composition. THEORY.md
    /// §V.3 — three-pillar attestation; the cache-key partition is
    /// the substrate's outer [`Sexp`](crate::ast::Sexp) `intent_hash`
    /// composition axis for every substitution-subset arm — binding
    /// the two bytes on the typed algebra makes attestation-key
    /// drift a compile error rather than a silent BLAKE3 mis-hash.
    /// THEORY.md §VI.1 — generation over composition; the family-
    /// wide contract sweeps (alignment with `ALL`, pairwise
    /// disjointness, membership through
    /// [`Self::hash_discriminator`]) emerge from the composition of
    /// TWO substrate primitives (this `pub(crate) const` array + the
    /// two per-role `pub(crate) const *_HASH_DISCRIMINATOR` aliases)
    /// rather than as per-variant inline assertions duplicated at
    /// each call site. THEORY.md §II.1 invariant 5 — composition
    /// preserves proofs; the alias-chain composition law
    /// `UnquoteForm::HASH_DISCRIMINATORS[i] ==
    /// UnquoteForm::ALL[i].to_quote_form().hash_discriminator()`
    /// binds the family-wide array to the composition through
    /// [`Self::to_quote_form`] +
    /// [`crate::ast::QuoteForm::hash_discriminator`] at rustc time.
    ///
    /// The `#[allow(dead_code)]` posture matches every sibling
    /// `HASH_DISCRIMINATORS` array on the substrate's typed-shape
    /// family: the substrate's current
    /// [`Hash for Sexp`](crate::ast::Sexp) body composes through the
    /// four-arm superset's [`crate::ast::QuoteForm::hash_discriminator`]
    /// projection rather than splitting the dispatch into
    /// (2 non-substitution + 2 substitution) arms — so no non-test
    /// caller currently reaches THIS subset-algebra array. The lift
    /// lands the substrate primitive so future consumers keyed on
    /// the substitution-subset carving specifically bind to ONE
    /// `[u8; 2]` primitive rather than re-deriving the array inline
    /// per callsite.
    #[allow(dead_code)]
    pub(crate) const HASH_DISCRIMINATORS: [u8; 2] = [
        Self::UNQUOTE_HASH_DISCRIMINATOR,
        Self::SPLICE_HASH_DISCRIMINATOR,
    ];

    /// Closed-set forced-arity ALL array over the reader's promotion
    /// triples on the two-variant substitution-subset lattice —
    /// `(Self::Unquote, '@', Self::Splice)` for the ONE `,` → `,@`
    /// promotion the substrate's reader `promote_via_next_char` arm
    /// depends on at the parent superset level. Its forced-arity `1`
    /// is INTENTIONAL and load-bearing on the subset carving: only
    /// [`Self::Splice`] carries a two-char rendered marker on the
    /// substitution subset (its `,@` prefix decomposes into `,` +
    /// [`crate::ast::QuoteForm::SPLICE_DISCRIMINATOR`]), so the
    /// promotion table's Some-arm is the singleton `{(Unquote, '@') →
    /// Splice}` on the `Self × char → Option<Self>` product — the
    /// two-of-four substitution-subset peer of the closed set
    /// [`crate::ast::QuoteForm::PROMOTIONS`] `[(head, char, promoted);
    /// 1]` carries on the four-arm quote-family superset.
    ///
    /// Cross-algebra composition law (pinned by
    /// `unquote_form_promotions_align_with_quote_form_promotions_by_projection`):
    /// for the ONE entry `(head, disc, promoted)` in
    /// [`Self::PROMOTIONS`],
    /// `(head.to_quote_form(), disc, promoted.to_quote_form())` equals
    /// [`crate::ast::QuoteForm::PROMOTIONS`]`[0]` byte-for-byte. The
    /// subset's promotion triple embeds into the parent superset's
    /// promotion triple through the pre-existing 2-of-4 subset →
    /// superset projection [`Self::to_quote_form`] composed with the
    /// identity on the middle discriminator `char` (which is a
    /// [`crate::ast::QuoteForm::SPLICE_DISCRIMINATOR`] alias direct at
    /// the constant site). A regression that drifts the subset's
    /// triple silently promotes a phantom pairing (e.g. re-inlines
    /// `Self::Splice` at the head column) AND fails the composition
    /// pin at rustc / test time rather than at silent tokenizer drift
    /// where the reader's `,@xs` sequence tokenizes to a phantom
    /// substitution-subset marker.
    ///
    /// Sibling posture to the closed-set forced-arity ALL arrays
    /// across the substrate's [`UnquoteForm`] subset algebra:
    /// [`Self::ALL`] (`[Self; 2]` — the closed set of variants),
    /// [`Self::MARKERS`] (`[&'static str; 2]` — the reader-marker
    /// axis, aliased through
    /// [`crate::ast::QuoteForm::UNQUOTE_PREFIX`] /
    /// [`crate::ast::QuoteForm::UNQUOTE_SPLICE_PREFIX`]),
    /// [`Self::IAC_FORGE_TAGS`] (`[&'static str; 2]` — the iac-forge
    /// canonical-form tag axis, aliased through
    /// [`crate::ast::QuoteForm::UNQUOTE_IAC_FORGE_TAG`] /
    /// [`crate::ast::QuoteForm::UNQUOTE_SPLICE_IAC_FORGE_TAG`]),
    /// [`Self::LABELS`] (`[&'static str; 2]` — the diagnostic-label
    /// axis, aliased through
    /// [`crate::ast::QuoteForm::UNQUOTE_LABEL`] /
    /// [`crate::ast::QuoteForm::UNQUOTE_SPLICE_LABEL`]), and
    /// [`Self::HASH_DISCRIMINATORS`] (`[u8; 2]` — the outer-`Sexp`
    /// cache-key byte axis, aliased through
    /// [`crate::ast::QuoteForm::UNQUOTE_HASH_DISCRIMINATOR`] /
    /// [`crate::ast::QuoteForm::UNQUOTE_SPLICE_HASH_DISCRIMINATOR`]).
    /// This lift adds the FIFTH per-family axis on the substitution-
    /// subset algebra — the (head, disc, promoted) triple axis on
    /// the closed-set promotion product. Each of the five axes now
    /// pins its per-role canonical data at ONE `pub const` per role
    /// (or ONE `pub const` triple on the promotion-asymmetric single-
    /// arm collapse) PLUS an ALL array for family-wide consumers.
    ///
    /// The middle discriminator column aliases
    /// [`crate::ast::QuoteForm::SPLICE_DISCRIMINATOR`] direct at the
    /// constant site — the substitution subset does NOT introduce a
    /// separate `SPLICE_DISCRIMINATOR` const because the discriminator
    /// byte is shape-uniform across the parent superset (it is the
    /// SAME `'@'` byte that promotes at every quote-family arm on the
    /// parent) and lives at ONE canonical site in `ast.rs`. Alias
    /// direction runs from the [`UnquoteForm`] subset INTO the parent
    /// [`crate::ast::QuoteForm`] superset — the SAME direction the
    /// four prior per-family axes take on this subset (MARKERS,
    /// IAC_FORGE_TAGS, LABELS, HASH_DISCRIMINATORS).
    ///
    /// `pub(crate)` because the promotion algebra is an implementation
    /// detail of the substrate's reader — exposing it publicly would
    /// leak the promotion-table shape through the API without
    /// enabling any external consumer the parent superset's public
    /// [`crate::ast::QuoteForm::promote_via_next_char`] projection
    /// doesn't already serve on the four-arm surface. Same visibility
    /// rationale as [`Self::HASH_DISCRIMINATORS`] on the sibling
    /// cache-key axis.
    ///
    /// The `#[allow(dead_code)]` posture matches
    /// [`Self::HASH_DISCRIMINATORS`] AND
    /// [`crate::ast::QuoteForm::PROMOTIONS`]: the substrate's current
    /// reader dispatches through the parent superset's
    /// [`crate::ast::QuoteForm::promote_via_next_char`] arm rather
    /// than a UnquoteForm-subset promotion body (which does not
    /// exist on this subset — the two-of-four carving does not carry
    /// a `promote_via_next_char` method because the reader boundary
    /// is the four-arm parent), so no non-test caller currently
    /// reaches this substitution-subset promotion array directly.
    /// The lift lands the substrate primitive so future consumers
    /// keyed on the substitution-subset carving specifically (a
    /// future `TypedRewriter<UnquoteFormOp>` sweep zipping ALL /
    /// MARKERS / IAC_FORGE_TAGS / LABELS / HASH_DISCRIMINATORS /
    /// PROMOTIONS in lockstep for a family-wide render, a future
    /// `tatara-check` predicate
    /// `(check-substitution-subset-promotion-algebra-injective …)`
    /// that verifies the substitution subset's promotion triples
    /// embed injectively into the parent superset's, a Sekiban
    /// audit-trail metric jointly labeled by the substitution-subset
    /// promotion partition) bind to ONE `[(Self, char, Self); N]`
    /// primitive rather than re-deriving the promotion triples
    /// inline per callsite. Matches the preemptive-primitive posture
    /// the prior-run [`Self::HASH_DISCRIMINATORS`] +
    /// [`crate::ast::QuoteForm::PROMOTIONS`] +
    /// [`crate::ast::QuoteForm::HASH_DISCRIMINATORS`] lifts carried
    /// before their downstream consumers materialized.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 1 — typed entry; the
    /// reader's two-char quote-family classification IS the typed-
    /// entry gate on the `,@` boundary, and lifting the substitution-
    /// subset's promotion triple to ONE typed `[(Self, char, Self);
    /// 1]` primitive on the closed-set subset algebra closes the
    /// gate's two-char entry surface onto the subset algebra rather
    /// than at zero-primitive-on-this-subset dispatch through the
    /// parent superset. THEORY.md §II.1 invariant 5 — composition
    /// preserves proofs; the (subset promotion triple, superset
    /// promotion triple) pairing binds at rustc time by identity
    /// composition through [`Self::to_quote_form`] on the head +
    /// promoted columns AND by direct alias on the middle
    /// discriminator column. THEORY.md §III — the typescape; the
    /// singleton promotion triple binds at ONE typed `pub const` on
    /// the closed-set [`UnquoteForm`] algebra rather than at zero-
    /// primitive-on-this-subset. Closes the FIFTH per-role
    /// `pub const` axis on the UnquoteForm subset carving in lockstep
    /// with the same-axis lift on [`crate::ast::QuoteForm`].
    /// THEORY.md §V.1 — knowable platform; the family's cardinality
    /// becomes a TYPE-level constant on the substrate algebra rather
    /// than a per-consumer runtime dispatch through the parent
    /// superset's method surface. THEORY.md §VI.1 — generation over
    /// composition; the family-wide contract sweeps (alignment with
    /// [`Self::ALL`], cardinality, cross-algebra composition against
    /// [`crate::ast::QuoteForm::PROMOTIONS`]) emerge from the
    /// composition of ONE substrate primitive (this `pub(crate) const`
    /// array) rather than as per-arm inline assertions duplicated at
    /// each call site.
    ///
    /// Frontier inspiration: MLIR's typed rewriter registry
    /// (`mlir::PatternApplicator`) carries per-op-family static
    /// rewrite tables at the closed-set boundary; a sub-op-family
    /// (a distinguished carving of the parent op-family) inherits
    /// the rewrite table through direct alias from the parent's
    /// canonical site, so the subset's rewrite table binds at ONE
    /// typed constant on the subset algebra with the alignment
    /// composition through the subset → superset projection at
    /// const-fn evaluation time. [`Self::PROMOTIONS`] is the Rust-
    /// typed peer of MLIR's per-subset rewrite-table projection at
    /// the two-variant substitution-subset level — its single entry
    /// composes from [`crate::ast::QuoteForm::PROMOTIONS`]`[0]`
    /// through subset → superset projection on the endpoints and
    /// direct alias on the middle discriminator.
    #[allow(dead_code)]
    pub(crate) const PROMOTIONS: [(Self, char, Self); 1] = [(
        Self::Unquote,
        crate::ast::QuoteForm::SPLICE_DISCRIMINATOR,
        Self::Splice,
    )];

    /// Project the typed `UnquoteForm` to the canonical `&'static str`
    /// literal — feeds the `LispError::UnboundTemplateVar` /
    /// `LispError::NonSymbolUnquoteTarget` Display rendering via the
    /// `#[error(...)]` annotation. The `&'static str` lifetime is
    /// load-bearing: it lets the variants project through this method into
    /// their `compile error in {prefix}…:` prefix without an allocation,
    /// parallel to how `MacroDefHead::keyword()` and
    /// `CompilerSpecIoStage::operation()` / `label()` feed their respective
    /// `LispError::*` Display impls.
    ///
    /// Composition law: `self.marker() == self.to_quote_form().prefix()`
    /// for every `self: UnquoteForm`. Pre-lift the body inlined the two
    /// literals (`","` / `",@"`) as a parallel match-table; the same two
    /// literals also lived at the matching Unquote/UnquoteSplice arms of
    /// [`crate::ast::QuoteForm::prefix`]. Post-lift the body composes
    /// `Self::to_quote_form()` (the typed 2-of-4 subset → superset
    /// projection) with `crate::ast::QuoteForm::prefix()` (the canonical
    /// 4-of-4 prefix-string projection), so the two `&'static str`
    /// literals live at ONE canonical site (`QuoteForm::prefix`'s
    /// Unquote/UnquoteSplice arms in `ast.rs`) and every consumer of
    /// `UnquoteForm::marker` (the `ClosedSet`-trait Display/FromStr
    /// surface via `#[closed_set(via = "marker")]`, the unbound-template
    /// `did you mean ,@args?` hint suffix in this module's
    /// `unbound_hint_suffix` helper, the `#[error("... {prefix}")]`
    /// annotation on `LispError::UnboundTemplateVar` /
    /// `LispError::NonSymbolUnquoteTarget`, the future LSP / REPL /
    /// `tatara-check` completion-bar projections that key on the typed
    /// marker) inherits the canonical vocabulary through the composition
    /// rather than through a parallel inline table that drifts at the
    /// next vocabulary rename.
    ///
    /// Sibling-shape lift to the prior-run `AtomKind::label` ⊂
    /// `SexpShape::label` composition (commit 1db697f): both pin the
    /// invariant that a typed-subset enum's projection on a closed-set
    /// vocabulary is structurally derived from its parent superset's
    /// projection, not a parallel literal table the type system happens
    /// to not catch when the vocabularies drift.
    ///
    /// The bidirectional contract is anchored by tests:
    /// `unquote_form_marker_projects_canonical_literal_for_each_variant`
    /// pins each variant's canonical literal so a typo in any arm
    /// fails-loudly,
    /// `unquote_form_display_renders_canonical_marker_for_each_variant`
    /// pins Display-equals-marker so any `#[error("... {prefix}")]`
    /// annotation that threads through this projection projects
    /// byte-for-byte,
    /// `unquote_form_marker_round_trips_through_from_str` pins the
    /// `marker` ↔ [`Self::FromStr`] round-trip for every variant in
    /// [`Self::ALL`] so the typed surface and the rendered diagnostic
    /// literal cannot drift, and the post-lift composition-routing
    /// pin
    /// `unquote_form_marker_routes_through_to_quote_form_prefix_via_composition`
    /// asserts pointer-equality between `self.marker()` and
    /// `self.to_quote_form().prefix()` for every variant — so a
    /// regression that re-inlines the literals as a parallel match-table
    /// fails the pointer pin even when the rendered bytes still agree
    /// (the inline-literal-table copy lives at a different `&'static str`
    /// address).
    #[must_use]
    pub fn marker(self) -> &'static str {
        self.to_quote_form().prefix()
    }

    /// Project the 2-of-4 template-substitution subset back to its
    /// parent [`crate::ast::QuoteForm`] superset — the structural
    /// inverse of [`crate::ast::QuoteForm::as_unquote_form`]. Returns
    /// the [`crate::ast::QuoteForm`] variant whose canonical prefix
    /// string matches this `UnquoteForm`'s marker:
    /// [`Self::Unquote`] → [`crate::ast::QuoteForm::Unquote`],
    /// [`Self::Splice`] → [`crate::ast::QuoteForm::UnquoteSplice`].
    ///
    /// Total (not `Option`) because every `UnquoteForm` IS a
    /// `QuoteForm` — the 2-of-4 subset is a subset by inclusion. The
    /// dual projection [`crate::ast::QuoteForm::as_unquote_form`]
    /// returns `Option<UnquoteForm>` because the two non-substitution
    /// variants ([`crate::ast::QuoteForm::Quote`] and
    /// [`crate::ast::QuoteForm::Quasiquote`]) lie outside the
    /// substitution subset.
    ///
    /// Round-trip identity: `self.to_quote_form().as_unquote_form() ==
    /// Some(self)` for every `self: UnquoteForm`, pinned by
    /// `unquote_form_to_quote_form_round_trips_through_as_unquote_form`.
    /// The dual identity `qf.as_unquote_form().map(|uf|
    /// uf.to_quote_form()) == qf.as_unquote_form().map(|_| qf)` holds
    /// by construction (the projection is a section of
    /// [`crate::ast::QuoteForm::as_unquote_form`] restricted to its
    /// image — the Unquote/UnquoteSplice variants).
    ///
    /// Lifts the (UnquoteForm variant, QuoteForm variant) pairing onto
    /// the typed algebra so consumers that need the parent superset
    /// from a substitution-subset value (the `marker` lift's
    /// composition root, the future hint-suffix pretty-printer's
    /// `prefix.to_quote_form().prefix()` routing, the future
    /// canonical-form interop tag that wants to route an `UnquoteForm`
    /// through `iac_forge_tag` via `to_quote_form().iac_forge_tag()`
    /// without re-deriving the pairing — now closed at
    /// [`Self::iac_forge_tag`]) bind at ONE typed projection
    /// rather than at parallel match arms each site re-derives.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the
    /// subset-to-superset projection becomes a TYPE projection on the
    /// substrate algebra. THEORY.md §VI.1 — generation over
    /// composition; the (UnquoteForm variant, QuoteForm variant)
    /// pairing emerges from this ONE primitive rather than from
    /// per-callsite per-variant literals. THEORY.md §II.1 invariant 1 —
    /// typed entry; the typed subset-to-superset projection IS a
    /// substrate-owned theorem rather than a hand-inlined match-table
    /// duplication discipline N sites had to keep in lockstep.
    #[must_use]
    pub fn to_quote_form(self) -> crate::ast::QuoteForm {
        match self {
            Self::Unquote => crate::ast::QuoteForm::Unquote,
            Self::Splice => crate::ast::QuoteForm::UnquoteSplice,
        }
    }

    /// Project the 2-of-4 template-substitution subset marker back into
    /// its matching [`crate::ast::Sexp`] wrapper variant applied to
    /// `inner` — the typed-CONSTRUCT face on the closed-set `UnquoteForm`
    /// algebra, sibling section-for-retraction of the existing typed-
    /// PROJECT face [`crate::ast::Sexp::as_unquote`] on the outer
    /// [`crate::ast::Sexp`] algebra. [`Self::Unquote`] yields
    /// [`crate::ast::Sexp::Unquote`], [`Self::Splice`] yields
    /// [`crate::ast::Sexp::UnquoteSplice`], each boxing `inner` into the
    /// corresponding tuple-variant constructor
    /// (`fn(Box<Sexp>) -> Sexp`).
    ///
    /// Closes the (construct, project) algebra dual on the closed-set
    /// `UnquoteForm` algebra — the substitution-subset peer of the
    /// closed-set superset algebra's already-closed dual pair
    /// ([`crate::ast::QuoteForm::wrap`] +
    /// [`crate::ast::Sexp::as_quote_form`]). Where the superset's
    /// `wrap` reaches all four homoiconic prefix-wrappers and its
    /// projection returns `Option<(QuoteForm, &Sexp)>` on the outer
    /// [`crate::ast::Sexp`] algebra, this subset's `wrap` reaches only
    /// the two template-substitution wrappers
    /// ([`crate::ast::Sexp::Unquote`] and
    /// [`crate::ast::Sexp::UnquoteSplice`]) and its projection sibling
    /// [`crate::ast::Sexp::as_unquote`] returns
    /// `Option<(UnquoteForm, &Sexp)>` — the (construct, project) pair on
    /// the subset algebra is symmetric with the (construct, project)
    /// pair on the superset algebra, each closed at one method per
    /// direction on the respective closed set.
    ///
    /// Composition law (forward): `self.wrap(inner) ==
    /// self.to_quote_form().wrap(inner)` for every `self: UnquoteForm`
    /// and every `inner: Sexp` — routes through the superset's
    /// [`crate::ast::QuoteForm::wrap`] at the single tuple-variant
    /// emission site so the (marker, `Sexp::*` tuple-variant
    /// constructor) pairing binds at ONE closed-set match on the
    /// superset algebra rather than at a parallel two-arm match table
    /// on this subset. Round-trip law (section-for-retraction with the
    /// soft-projection sibling): `self.wrap(inner).as_unquote() ==
    /// Some((self, &inner))` for every `self: UnquoteForm` and every
    /// `inner: Sexp` — the subset's typed constructor pairs
    /// section-for-retraction with the outer algebra's soft projection,
    /// and the marker + inner body cross-projection preserves identity
    /// on the substitution-subset closed set. Sibling-shape lift to the
    /// prior-run `UnquoteForm::marker` ⊂ `QuoteForm::prefix` composition
    /// (commit 250c001): both pin the invariant that a typed-subset
    /// enum's projection on a closed-set operation is structurally
    /// derived from its parent superset's projection through the
    /// canonical `to_quote_form` composition, not a parallel inline
    /// match-table the type system happens to not catch when the
    /// vocabularies drift.
    ///
    /// Pre-lift consumers that had an `UnquoteForm` marker in hand and
    /// wanted to build a fresh [`crate::ast::Sexp`] wrapper had to
    /// spell the two-step composition
    /// `uf.to_quote_form().wrap(inner)` — a future template rewriter
    /// consuming [`crate::ast::Sexp::as_unquote`]'s
    /// `Option<(UnquoteForm, &Sexp)>` projection and threading a
    /// rewritten inner body back into the matching wrapper on the
    /// substitution-subset closed set (a future
    /// `TypedRewriter<UnquoteFormOp>` sweep, a future macro-template
    /// canonicalizer that normalizes `,x` / `,@x` shapes, a future REPL
    /// pretty-printer that emits a fresh substitution wrapper from a
    /// borrowed marker + inner pair) would have re-derived the
    /// `.to_quote_form().wrap(_)` composition at every callsite. Post-
    /// lift the composition binds at ONE typed-algebra method on the
    /// closed-set `UnquoteForm` algebra, matching the section-for-
    /// retraction posture the superset's [`crate::ast::QuoteForm::wrap`]
    /// already carries on the outer [`crate::ast::Sexp`] algebra. The
    /// (marker, `Sexp::*` tuple-variant constructor) pairing continues
    /// to live at ONE site on the superset's `wrap` closed-set match
    /// (the single tuple-variant emission point the substrate owns),
    /// which is what this subset method routes through — no parallel
    /// match table, no per-arm drift risk on the two-variant closed set.
    ///
    /// The [`crate::ast::Sexp`] (owned) return type complements
    /// [`crate::ast::Sexp::as_unquote`]'s `&Sexp` (borrowed) —
    /// symmetric with the ([`crate::ast::QuoteForm::wrap`],
    /// [`crate::ast::Sexp::as_quote_form`]) asymmetry on the superset
    /// algebra: `wrap` consumes the inner body to build the new
    /// wrapper, the projection borrows the inner body from the existing
    /// wrapper. The typed `Box::new(inner)` allocation lives at ONE
    /// site on the superset's [`crate::ast::QuoteForm::wrap`] (the
    /// closed-set tuple-variant emission point), so a future
    /// allocation-policy change (e.g. arena-allocated wrappers for
    /// span-aware [`crate::ast::Sexp`]) lands as ONE edit at the
    /// superset's `wrap` and propagates through this subset method
    /// byte-for-byte.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 1 — typed entry; the
    /// (UnquoteForm variant, `Sexp::*` tuple-variant constructor)
    /// pairing binds at ONE typed-algebra method on the subset algebra,
    /// routed through the ONE closed-set match on the superset algebra
    /// the substrate already owns. THEORY.md §II.1 invariant 2 — free
    /// middle; every consumer that has an `UnquoteForm` marker and
    /// wants to build a wrapper `Sexp` routes through the SAME typed
    /// method, so a regression that drifts one consumer's pairing from
    /// the others cannot reach the substrate's runtime. THEORY.md §V.1
    /// — knowable platform; the typed-construct face becomes a TYPE
    /// projection on the subset algebra sitting next to the typed-
    /// project face [`crate::ast::Sexp::as_unquote`] on the outer
    /// [`crate::ast::Sexp`] algebra rather than a bare
    /// `to_quote_form().wrap(_)` two-step composition consumers had to
    /// re-derive per site. THEORY.md §VI.1 — generation over
    /// composition; the (subset marker, wrapper `Sexp`) pairing emerges
    /// from ONE typed-algebra composition on the subset algebra rather
    /// than from parallel per-consumer per-variant literals.
    ///
    /// Frontier inspiration: Racket's `syntax/parse` `~or* (~unquote
    /// stx) (~unquote-splice stx)` pattern paired one-for-one with a
    /// typed constructor face on the same subset shape — the (project,
    /// construct) algebra dual is closed at one method per direction
    /// on Racket's substitution-subset surface, and `UnquoteForm::wrap`
    /// / [`crate::ast::Sexp::as_unquote`] is the Rust-typed peer on
    /// the closed-set `UnquoteForm` algebra with
    /// [`crate::ast::QuoteForm::wrap`] standing in for Racket's typed
    /// dispatch through the superset. MLIR's typed factory
    /// `mlir::OpBuilder::create<UnquoteFamilyOp>(loc, inner)` paired
    /// with the projection sibling `mlir::dyn_cast<UnquoteFamilyOp>(op)`
    /// — the typed factory + typed downcast pair the IR algebra closes
    /// over on every wrapper op subset; `UnquoteForm::wrap` /
    /// [`crate::ast::Sexp::as_unquote`] is the unstructured-Rust peer
    /// on the outer [`crate::ast::Sexp`] algebra with the closed-set
    /// `UnquoteForm` standing in for MLIR's subset-of-`OperationName`
    /// taxonomy over the substitution-subset op family.
    #[must_use]
    pub fn wrap(self, inner: crate::ast::Sexp) -> crate::ast::Sexp {
        self.to_quote_form().wrap(inner)
    }

    /// Canonical [`SexpShape`] embed target for the [`Self::Unquote`]
    /// template-substitution arm on the UnquoteForm ⊂ QuoteForm ⊂
    /// SexpShape composed carving — aliases
    /// [`crate::ast::QuoteForm::UNQUOTE_SHAPE`] on the parent's 4-of-12
    /// quote-family carving byte-for-byte (which in turn aliases
    /// [`SexpShape::Unquote`]). Per-role peer of `Self::Unquote` on the
    /// closed-set UnquoteForm ⊂ SexpShape 2-of-12 composed embed axis;
    /// consumers with an `UnquoteForm` variant in hand at compile time
    /// bind the canonical embed target through ONE typed `pub const` on
    /// the subset algebra rather than through runtime dispatch via
    /// `Self::sexp_shape` OR by reaching across the two-hop
    /// `Self::to_quote_form().sexp_shape()` composition OR by re-deriving
    /// the UnquoteForm ⊂ QuoteForm ⊂ SexpShape variant pairing inline.
    /// Sibling posture to [`Self::UNQUOTE_MARKER`] on the reader-prefix
    /// axis, [`Self::UNQUOTE_LEAD`] on the reader-lead axis,
    /// [`Self::UNQUOTE_IAC_FORGE_TAG`] on the iac-forge canonical-form tag
    /// axis, [`Self::UNQUOTE_LABEL`] on the diagnostic-label axis, and
    /// [`Self::UNQUOTE_HASH_DISCRIMINATOR`] on the outer-Sexp cache-key
    /// byte axis — every one of the pre-existing per-role sub-vocabulary
    /// aliases on this subset algebra now has a peer per-role
    /// `SexpShape` embed-target alias on the SAME closed-set
    /// UnquoteForm ⊂ QuoteForm 2-of-4 subset carving.
    pub const UNQUOTE_SHAPE: SexpShape = crate::ast::QuoteForm::UNQUOTE_SHAPE;

    /// Canonical [`SexpShape`] embed target for the [`Self::Splice`]
    /// template-substitution arm on the UnquoteForm ⊂ QuoteForm ⊂
    /// SexpShape composed carving — aliases
    /// [`crate::ast::QuoteForm::UNQUOTE_SPLICE_SHAPE`] on the parent's
    /// 4-of-12 quote-family carving byte-for-byte (which in turn aliases
    /// [`SexpShape::UnquoteSplice`]). Per-role peer of `Self::Splice` on
    /// the closed-set UnquoteForm ⊂ SexpShape 2-of-12 composed embed
    /// axis. See [`Self::UNQUOTE_SHAPE`] for the alias-chain shape every
    /// sibling shares.
    pub const SPLICE_SHAPE: SexpShape = crate::ast::QuoteForm::UNQUOTE_SPLICE_SHAPE;

    /// Closed-set forced-arity ALL array over the canonical
    /// [`SexpShape`] embed targets on the UnquoteForm ⊂ SexpShape
    /// 2-of-12 composed carving, in declaration order matching
    /// [`Self::ALL`] element-wise (pinned by
    /// `unquote_form_shapes_align_with_all_by_index`). Sibling posture
    /// to [`Self::MARKERS`] (`[&'static str; 2]` — reader-prefix bytes),
    /// [`Self::LEADS`] (`[char; 1]` — SHAPE-ASYMMETRIC-COLLAPSE distinct-
    /// lead byte), [`Self::IAC_FORGE_TAGS`] (`[&'static str; 2]` — iac-
    /// forge canonical-form tags), [`Self::LABELS`] (`[&'static str; 2]`
    /// — diagnostic labels), [`Self::HASH_DISCRIMINATORS`] (`[u8; 2]` —
    /// outer-Sexp cache-key bytes), and [`Self::PROMOTIONS`]
    /// (`[(Self, char, Self); 1]` — SHAPE-ASYMMETRIC-COLLAPSE promotion
    /// triples) on the SAME closed-set UnquoteForm algebra; where those
    /// six arrays lift per-role sub-vocabularies on the substitution
    /// subset algebra, this array lifts the per-role [`SexpShape`]
    /// embed-target sub-vocabulary at the same `[_; 2]` forced arity.
    ///
    /// Aliased through [`crate::ast::QuoteForm::UNQUOTE_SHAPE`] +
    /// [`crate::ast::QuoteForm::UNQUOTE_SPLICE_SHAPE`] via the per-role
    /// [`Self::UNQUOTE_SHAPE`] + [`Self::SPLICE_SHAPE`] constants — the
    /// UnquoteForm ⊂ QuoteForm 2-of-4 subset carving of the parent's
    /// 4-of-12 quote-family SHAPES. Sibling posture to
    /// [`crate::ast::QuoteForm::SHAPES`] (`[SexpShape; 4]`) —
    /// the parent superset's peer array on the QuoteForm ⊂ SexpShape
    /// 4-of-12 carving; together with the three closed-set carvings'
    /// arrays ([`crate::ast::AtomKind::SHAPES`] 6-of-12,
    /// [`crate::ast::QuoteForm::SHAPES`] 4-of-12,
    /// [`StructuralKind::SHAPES`] 2-of-12) the four `SHAPES` arrays now
    /// close the FULL twelve-arm outer-shape algebra uniformly PLUS the
    /// UnquoteForm 2-of-4 subset carving of the quote-family sub-
    /// algebra.
    ///
    /// Pre-lift the two [`SexpShape`] embed targets had NO per-role
    /// primitive on this subset algebra — a consumer with an
    /// `UnquoteForm` variant in hand at compile time reaching for the
    /// canonical embed target had to spell
    /// `UnquoteForm::Unquote.sexp_shape()` (runtime dispatch through
    /// [`Self::sexp_shape`]'s two-hop `.to_quote_form().sexp_shape()`
    /// composition) OR reach across into
    /// [`crate::ast::QuoteForm::UNQUOTE_SHAPE`] and re-derive the
    /// UnquoteForm ⊂ QuoteForm 2-of-4 subset pairing at the call site.
    /// Post-lift the TWO canonical embed targets bind at ONE `pub const`
    /// per role on the typed [`UnquoteForm`] subset algebra AND at
    /// [`Self::SHAPES`] as a family-wide forced-arity array — a future
    /// LSP / REPL completion bar keyed on `UnquoteForm::SHAPES` for the
    /// "which SexpShape does this UnquoteForm embed into?" outer-shape
    /// column, a `tatara-check` coverage sweep zipping
    /// `UnquoteForm::ALL` / `LABELS` / `MARKERS` / `LEADS` /
    /// `IAC_FORGE_TAGS` / `HASH_DISCRIMINATORS` / `PROMOTIONS` /
    /// `SHAPES` in lockstep for a family-wide (variant, label, marker,
    /// lead, iac-forge tag, cache-key byte, promotion triple, embed-
    /// target) octuple render, or a Sekiban audit-trail metric jointly
    /// labeled by the embed target's SexpShape identity reads through
    /// the typed constants on this subset algebra without re-deriving
    /// the 2-of-12 composed carving inline.
    ///
    /// Round-trip identity with the inverse projection
    /// [`SexpShape::as_unquote_form`]: for every index `i`,
    /// `Self::SHAPES[i].as_unquote_form() == Some(Self::ALL[i])` (pinned
    /// by `unquote_form_shapes_align_with_all_by_index_through_as_unquote_form`)
    /// — the embed / project section closes as a family-wide array-
    /// indexed law on the composed 2-of-12 carving rather than as a
    /// per-variant assertion sweep. Adding a hypothetical third
    /// template-substitution marker (e.g. `,~` reverse-unquote for
    /// destructuring-bind hygiene, `,?` conditional-unquote) extends
    /// [`Self::ALL`] AND [`Self::SHAPES`] AND
    /// [`crate::ast::QuoteForm::ALL`] AND
    /// [`crate::ast::QuoteForm::SHAPES`] AND [`SexpShape::ALL`] AND adds
    /// ONE per-role `pub const *_SHAPE` in lockstep — rustc's forced-
    /// arity check on the two `[_; N]` arrays fails compilation if
    /// EITHER ALL array grows without the other, AND the peer
    /// [`SexpShape::as_unquote_form`] arm must grow in lockstep to
    /// preserve the round-trip identity.
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the two canonical
    /// [`SexpShape`] embed targets bind at ONE typed `[SexpShape; 2]`
    /// array on the closed-set UnquoteForm subset algebra rather than at
    /// zero-primitive-on-this-subset-plus-two-inline-lookups-through-
    /// two-hop-composition scattered across the substrate. THEORY.md
    /// §II.1 invariant 2 — free middle; the (embed, project) pair binds
    /// at THREE typed sites now — the projection method
    /// [`Self::sexp_shape`], this family-wide array, AND the peer inverse
    /// [`SexpShape::as_unquote_form`] — with rustc-enforced consistency
    /// across all three via the array-indexed round-trip law. THEORY.md
    /// §V.1 — knowable platform; the family's cardinality becomes a
    /// TYPE-level constant on the substrate algebra rather than a per-
    /// consumer runtime dispatch through the two-hop composition.
    /// THEORY.md §VI.1 — generation over composition; the family-wide
    /// contract sweeps (alignment with `ALL`, round-trip through
    /// `as_unquote_form`, membership through `sexp_shape`, pairwise
    /// injectivity across the two embed targets, alias byte-equality
    /// with QuoteForm's per-role SHAPE constants) emerge from the
    /// composition of TWO substrate primitives (this `pub const` array +
    /// the two per-role `pub const *_SHAPE` aliases) rather than as
    /// per-variant inline assertions duplicated at each call site.
    pub const SHAPES: [SexpShape; 2] = [Self::UNQUOTE_SHAPE, Self::SPLICE_SHAPE];

    /// Project the 2-of-4 template-substitution subset marker into its
    /// matching [`SexpShape`] variant on the outer [`crate::ast::Sexp`]
    /// algebra's twelve-variant shape lattice — [`Self::Unquote`] →
    /// [`SexpShape::Unquote`], [`Self::Splice`] → [`SexpShape::UnquoteSplice`].
    /// Section peer of [`SexpShape::as_unquote_form`] on the 2-of-12
    /// carving that names the template-substitution wrappers; closes the
    /// (embed, project) algebra dual on the `UnquoteForm ⊂ SexpShape`
    /// typed-shape lattice, sibling of the already-closed
    /// ([`crate::ast::AtomKind::sexp_shape`], [`SexpShape::as_atom_kind`])
    /// dual on the 6-of-12 atomic-payload carving AND
    /// ([`crate::ast::QuoteForm::sexp_shape`], [`SexpShape::as_quote_form`])
    /// dual on the 4-of-12 quote-family carving.
    ///
    /// Composition law: `self.sexp_shape() ==
    /// self.to_quote_form().sexp_shape()` for every `self: UnquoteForm`.
    /// The (subset marker, outer [`SexpShape`]) pairing binds at ONE
    /// closed-set match on the superset's
    /// [`crate::ast::QuoteForm::sexp_shape`] rather than at a parallel
    /// two-arm inline match table on this subset — matching the posture
    /// [`Self::marker`] takes through [`crate::ast::QuoteForm::prefix`]
    /// and [`Self::wrap`] takes through [`crate::ast::QuoteForm::wrap`].
    /// Round-trip law (section-for-retraction with the outer projection
    /// sibling): `self.sexp_shape().as_unquote_form() == Some(self)` for
    /// every `self: UnquoteForm`.
    ///
    /// Pre-lift the (UnquoteForm variant, SexpShape variant) pairing had
    /// NO typed projection on this subset algebra — a template rewriter
    /// with an `UnquoteForm` marker in hand wanting the outer
    /// [`SexpShape`] identity (e.g., a future `tatara-check` predicate
    /// that filters diagnostics to "this rejection was on a template-
    /// substitution wrapper", a future LSP hover that renders a typed
    /// marker's outer-shape witness alongside its punctuation, a future
    /// macro-hygiene analyzer that keys on the outer shape of a captured
    /// substitution point) had to spell the two-step composition
    /// `uf.to_quote_form().sexp_shape()` at every callsite. Post-lift
    /// the composition binds at ONE typed-algebra method on the closed-
    /// set `UnquoteForm` algebra, and the (embed, project) pair with
    /// [`SexpShape::as_unquote_form`] forms an `Iso(UnquoteForm,
    /// UnquoteShape ⊂ SexpShape)` on the substitution-subset carving.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the (subset
    /// marker, outer shape) pairing becomes a TYPE projection on the
    /// substrate algebra rather than a per-callsite `.to_quote_form()
    /// .sexp_shape()` two-step. THEORY.md §II.1 invariant 2 — free
    /// middle; every consumer that has an `UnquoteForm` marker and
    /// wants the outer [`SexpShape`] routes through the SAME typed
    /// method. THEORY.md §VI.1 — generation over composition; the
    /// pairing emerges from ONE typed-algebra composition on the subset
    /// algebra rather than from parallel per-consumer per-variant
    /// literals.
    ///
    /// Frontier inspiration: MLIR's `mlir::OperationName` typed
    /// projection from a subset-op-family value into the parent
    /// `OperationName` taxonomy — the (subset op, taxonomic identity)
    /// pairing lives at ONE typed projection on the subset algebra,
    /// composed through the parent op-family's typed identity face.
    /// `UnquoteForm::sexp_shape` is the Rust-typed peer on the closed-
    /// set `UnquoteForm` algebra with [`SexpShape`] standing in for
    /// MLIR's parent `OperationName` taxonomy.
    #[must_use]
    pub fn sexp_shape(self) -> SexpShape {
        self.to_quote_form().sexp_shape()
    }

    /// Project the 2-of-4 template-substitution subset marker into its
    /// canonical iac-forge interop tag — [`Self::Unquote`] →
    /// `"unquote"`, [`Self::Splice`] → `"unquote-splicing"`. The
    /// Common-Lisp-canonical tag string [`crate::ast::QuoteForm::iac_forge_tag`]
    /// projects on the superset carving, restricted through
    /// [`Self::to_quote_form`] to the substitution-subset carving.
    ///
    /// Composition law: `self.iac_forge_tag() ==
    /// self.to_quote_form().iac_forge_tag()` for every `self:
    /// UnquoteForm`. The body composes [`Self::to_quote_form`] (the
    /// typed 2-of-4 subset → superset projection) with
    /// [`crate::ast::QuoteForm::iac_forge_tag`] (the canonical 4-of-4
    /// interop-tag projection), so the two `&'static str` literals live
    /// at ONE canonical site (`QuoteForm::iac_forge_tag`'s
    /// Unquote/UnquoteSplice arms in `ast.rs`) — the (subset marker,
    /// canonical iac-forge tag string) pairing binds at ONE closed-set
    /// match on the superset algebra rather than at a parallel two-arm
    /// inline match table on this subset. Matches the posture
    /// [`Self::marker`] takes through [`crate::ast::QuoteForm::prefix`],
    /// [`Self::wrap`] takes through [`crate::ast::QuoteForm::wrap`],
    /// and [`Self::sexp_shape`] takes through
    /// [`crate::ast::QuoteForm::sexp_shape`] — the FOURTH
    /// composition-through-`to_quote_form` axis the closed-set subset
    /// algebra closes.
    ///
    /// The `&'static str` lifetime is load-bearing: every future iac-
    /// forge consumer with an `UnquoteForm` marker in hand projects
    /// through this method into the canonical 2-element-list head
    /// without an allocation, parallel to how [`Self::marker`] projects
    /// the reader-punctuation vocabulary. The tag stays intentionally
    /// disjoint from [`Self::marker`] (reader punctuation: `","` /
    /// `",@"`) AND from [`Self::sexp_shape`]'s
    /// [`crate::error::SexpShape::label`] rendering (diagnostic label:
    /// `"unquote"` / `"unquote-splice"`) at the substitution-subset's
    /// `Splice` arm — the CL canonical form REQUIRES the
    /// `unquote-splicing` spelling, while the substrate's diagnostic
    /// surface renders `unquote-splice`. The two projections key the
    /// SAME closed-set on TWO distinct boundaries; consolidating them
    /// would silently break either the iac-forge canonical-form round-
    /// trip OR the operator-facing diagnostic surface. That distinction
    /// is pinned bit-for-bit through the composition law: this method
    /// AGREES with [`crate::ast::QuoteForm::iac_forge_tag`] at every
    /// variant AND disagrees with [`crate::error::SexpShape::label`]
    /// at the `Splice` arm through the same closed-set typed algebra.
    ///
    /// Pre-lift the (UnquoteForm variant, iac-forge tag) pairing had
    /// NO typed projection on this subset algebra — a future consumer
    /// with an `UnquoteForm` marker wanting the canonical iac-forge
    /// tag (e.g. a future template rewriter emitting canonical-form
    /// diagnostics keyed on the substitution-subset marker, a future
    /// `tatara-check` predicate that renders `(check-iac-forge-tag
    /// ,x)` for a substitution-subset value, a future audit-trail
    /// metric jointly labeled by the interop tag on a template-
    /// substitution rejection) had to spell the two-step composition
    /// `uf.to_quote_form().iac_forge_tag()` at every callsite —
    /// exactly the composition the docstring for [`Self::wrap`]
    /// explicitly names as the NEXT deferred sweep this lift picks up.
    /// Post-lift the composition binds at ONE typed-algebra method on
    /// the closed-set `UnquoteForm` algebra sitting next to the three
    /// prior sibling projections ([`Self::marker`], [`Self::wrap`],
    /// [`Self::sexp_shape`]), closing the FOURTH
    /// composition-through-`to_quote_form` axis on the subset — every
    /// substrate-surface axis the superset algebra carries
    /// ([`crate::ast::QuoteForm::prefix`],
    /// [`crate::ast::QuoteForm::wrap`],
    /// [`crate::ast::QuoteForm::sexp_shape`],
    /// [`crate::ast::QuoteForm::iac_forge_tag`]) now has a matching
    /// composition on the substitution subset.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the (subset
    /// marker, canonical iac-forge tag) pairing becomes a TYPE
    /// projection on the substrate algebra rather than a per-callsite
    /// `.to_quote_form().iac_forge_tag()` two-step. THEORY.md §II.1
    /// invariant 2 — free middle; every consumer that has an
    /// `UnquoteForm` marker and wants the canonical iac-forge tag
    /// routes through the SAME typed method. THEORY.md §VI.1 —
    /// generation over composition; the pairing emerges from ONE
    /// typed-algebra composition on the subset algebra rather than
    /// from parallel per-consumer per-variant literals. A future
    /// third template-substitution marker (e.g. `,~` reverse-unquote)
    /// extends [`Self::ALL`] + [`Self::to_quote_form`]'s dispatch
    /// table in lockstep — rustc-enforced through the closed-set
    /// exhaustiveness — with THIS method inheriting the extension
    /// through the [`crate::ast::QuoteForm::iac_forge_tag`]
    /// composition site without a per-site edit.
    ///
    /// Frontier inspiration: Racket's `syntax-source-module` +
    /// `syntax->datum` interop chain paired with a substitution-subset
    /// pattern-class projection — the (subset pattern, canonical
    /// interop identity) pairing lives at ONE typed projection on the
    /// subset algebra, composed through the parent syntactic-form
    /// interop identity face. `UnquoteForm::iac_forge_tag` is the
    /// Rust-typed peer on the closed-set `UnquoteForm` algebra with
    /// [`crate::ast::QuoteForm::iac_forge_tag`] standing in for
    /// Racket's parent syntactic-form interop identity taxonomy.
    /// MLIR's `mlir::OperationName::getStringRef()` typed projection
    /// from a subset-op-family value into the canonical cross-crate
    /// op-identity string — the (subset op, canonical string) pairing
    /// lives at ONE typed projection on the subset algebra, composed
    /// through the parent op-family's typed identity face.
    /// `UnquoteForm::iac_forge_tag` is the Rust-typed peer on the
    /// closed-set `UnquoteForm` algebra with `iac_forge_tag` standing
    /// in for MLIR's `getStringRef` cross-boundary identity face.
    #[must_use]
    pub fn iac_forge_tag(self) -> &'static str {
        self.to_quote_form().iac_forge_tag()
    }

    /// Project the 2-of-4 template-substitution subset marker into its
    /// canonical substrate diagnostic label — [`Self::Unquote`] →
    /// `"unquote"`, [`Self::Splice`] → `"unquote-splice"`. Feeds the
    /// same `SexpShape::label`-backed diagnostic surface consumers
    /// reach for on the parent [`crate::ast::QuoteForm::label`]
    /// projection, restricted through [`Self::to_quote_form`] to the
    /// substitution-subset carving.
    ///
    /// Composition law: `self.label() ==
    /// self.to_quote_form().label()` for every `self: UnquoteForm`.
    /// The body composes [`Self::to_quote_form`] (the typed 2-of-4
    /// subset → superset projection) with
    /// [`crate::ast::QuoteForm::label`] (the canonical 4-of-4
    /// diagnostic-label projection through
    /// [`crate::ast::QuoteForm::sexp_shape`] +
    /// [`SexpShape::label`]), so the two `&'static str` literals live
    /// at ONE canonical site ([`SexpShape::UNQUOTE_LABEL`] /
    /// [`SexpShape::UNQUOTE_SPLICE_LABEL`] in `error.rs`) — the
    /// (subset marker, canonical diagnostic label) pairing binds at
    /// ONE closed-set match on the superset algebra rather than at a
    /// parallel two-arm inline match table on this subset. Matches
    /// the posture [`Self::marker`] takes through
    /// [`crate::ast::QuoteForm::prefix`], [`Self::wrap`] takes through
    /// [`crate::ast::QuoteForm::wrap`], [`Self::sexp_shape`] takes
    /// through [`crate::ast::QuoteForm::sexp_shape`], and
    /// [`Self::iac_forge_tag`] takes through
    /// [`crate::ast::QuoteForm::iac_forge_tag`] — the FIFTH
    /// composition-through-`to_quote_form` axis the closed-set subset
    /// algebra closes.
    ///
    /// The `&'static str` lifetime is load-bearing: every future
    /// diagnostic consumer with an `UnquoteForm` marker in hand
    /// projects through this method into the canonical
    /// SexpShape-label vocabulary without an allocation, parallel to
    /// how [`Self::marker`] projects the reader-punctuation vocabulary
    /// and [`Self::iac_forge_tag`] projects the cross-crate iac-forge
    /// vocabulary. The diagnostic label stays intentionally distinct
    /// from [`Self::marker`] (reader punctuation: `","` / `",@"`) AND
    /// diverges INTENTIONALLY from [`Self::iac_forge_tag`] at the
    /// `Splice` arm — `label` renders `"unquote-splice"` (substrate
    /// diagnostic surface) while `iac_forge_tag` renders `"unquote-
    /// splicing"` (Common-Lisp canonical form). The typed method
    /// documents the boundary-distinct invariant structurally: a
    /// future "consolidation" that homogenizes the two axes would
    /// have to touch this method explicitly.
    ///
    /// Note: `#[closed_set(via = "marker")]` on the enum's derive
    /// wires the trait-side [`tatara_closed_set::ClosedSet::label`] projection to
    /// [`Self::marker`] (the reader-punctuation byte), NOT to this
    /// inherent `label` (which is the SexpShape-diagnostic label).
    /// The inherent surface takes precedence for direct `uf.label()`
    /// calls; generic consumers reaching through the trait
    /// (`<UnquoteForm as ClosedSet>::label(uf)`) still see the marker.
    /// This mirrors [`crate::ast::QuoteForm::label`]'s posture on the
    /// parent superset ([`crate::ast::QuoteForm`]'s trait `label` is
    /// wired via `#[closed_set(via = "prefix")]` to `prefix`, while
    /// its inherent `label` returns `sexp_shape().label()`) — the
    /// UnquoteForm subset now closes the SAME (inherent-diagnostic,
    /// trait-punctuation) split on its subset algebra.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the
    /// (subset marker, canonical diagnostic label) pairing becomes a
    /// TYPE projection on the substrate algebra rather than a per-
    /// callsite `.to_quote_form().label()` two-step. THEORY.md §II.1
    /// invariant 2 — free middle; every consumer that has an
    /// `UnquoteForm` marker and wants the canonical diagnostic label
    /// routes through the SAME typed method. THEORY.md §VI.1 —
    /// generation over composition; the pairing emerges from ONE
    /// typed-algebra composition on the subset algebra rather than
    /// from parallel per-consumer per-variant literals. A future
    /// third template-substitution marker (e.g. `,~` reverse-unquote)
    /// extends [`Self::ALL`] + [`Self::to_quote_form`]'s dispatch
    /// table in lockstep — rustc-enforced through the closed-set
    /// exhaustiveness — with THIS method inheriting the extension
    /// through the [`crate::ast::QuoteForm::label`] composition site
    /// without a per-site edit.
    #[must_use]
    pub fn label(self) -> &'static str {
        self.to_quote_form().label()
    }

    /// Stable, per-variant byte discriminator that paired with the
    /// substitution-subset outer-shape hash body builds the substrate's
    /// [`Hash for Sexp`](crate::ast::Sexp) projection at the two
    /// template-substitution arms — `5u8` for [`Self::Unquote`], `6u8`
    /// for [`Self::Splice`]. The byte values are load-bearing because
    /// the macro-expansion cache ([`crate::macro_expand::Expander`]'s
    /// cache) keys on the hash of `(macro_name, args)`, and every
    /// [`crate::ast::Sexp::Unquote`] / [`crate::ast::Sexp::UnquoteSplice`]
    /// wrapper participates in that hash through the superset's
    /// [`crate::ast::QuoteForm::hash_discriminator`] arms — changing a
    /// discriminator here silently invalidates every cached expansion
    /// across the substrate AND risks collision with the reserved bytes
    /// the other outer-Sexp carvings' arms use (`1u8` for the
    /// [`crate::ast::Sexp::Atom`] outer-carve marker, `{0, 2}` for the
    /// [`StructuralKind::hash_discriminator`] structural-residual
    /// carving, `{3, 4}` for the non-substitution quote-family arms
    /// [`crate::ast::QuoteForm::Quote`] and
    /// [`crate::ast::QuoteForm::Quasiquote`]).
    ///
    /// Composition law: `self.hash_discriminator() ==
    /// self.to_quote_form().hash_discriminator()` for every `self:
    /// UnquoteForm`. The body composes [`Self::to_quote_form`] (the
    /// typed 2-of-4 subset → superset projection) with
    /// [`crate::ast::QuoteForm::hash_discriminator`] (the canonical
    /// 4-of-4 cache-key byte projection), so the two `5u8`/`6u8`
    /// literals live at ONE canonical site
    /// ([`crate::ast::QuoteForm::hash_discriminator`]'s Unquote /
    /// UnquoteSplice arms in `ast.rs`) rather than at a parallel
    /// two-arm inline table on this subset. Matches the posture
    /// [`Self::marker`] takes through [`crate::ast::QuoteForm::prefix`],
    /// [`Self::wrap`] takes through [`crate::ast::QuoteForm::wrap`],
    /// [`Self::sexp_shape`] takes through
    /// [`crate::ast::QuoteForm::sexp_shape`], and
    /// [`Self::iac_forge_tag`] takes through
    /// [`crate::ast::QuoteForm::iac_forge_tag`] — the FIFTH
    /// composition-through-`to_quote_form` axis the closed-set subset
    /// algebra closes.
    ///
    /// Pre-lift the (UnquoteForm variant, cache-key byte) pairing had
    /// NO typed projection on this subset algebra — a future consumer
    /// with an [`UnquoteForm`] marker in hand wanting the outer-Sexp
    /// cache-key byte (e.g. a future template rewriter that keys a
    /// substitution-subset audit-trail metric on the
    /// [`Hash for Sexp`](crate::ast::Sexp) cache-key partition, a
    /// future `tatara-check` predicate that verifies the substitution-
    /// subset carving's cache-key partition sits inside `{5, 6}` at a
    /// substrate coherence gate, a future `TypedRewriter<UnquoteFormOp>`
    /// that decides cache invalidation on the substitution-subset
    /// discriminator) had to spell the two-step composition
    /// `uf.to_quote_form().hash_discriminator()` at every callsite.
    /// Post-lift the composition binds at ONE typed-algebra method on
    /// the closed-set [`UnquoteForm`] algebra sitting next to the four
    /// prior sibling projections ([`Self::marker`], [`Self::wrap`],
    /// [`Self::sexp_shape`], [`Self::iac_forge_tag`]), closing the
    /// FIFTH composition-through-`to_quote_form` axis on the subset
    /// — every substrate-surface axis the superset algebra carries
    /// ([`crate::ast::QuoteForm::prefix`],
    /// [`crate::ast::QuoteForm::wrap`],
    /// [`crate::ast::QuoteForm::sexp_shape`],
    /// [`crate::ast::QuoteForm::iac_forge_tag`],
    /// [`crate::ast::QuoteForm::hash_discriminator`]) now has a
    /// matching composition on the substitution subset.
    ///
    /// `pub(crate)` because the byte-discriminator surface is an
    /// implementation detail of the substrate's
    /// [`Hash for Sexp`](crate::ast::Sexp) cache-key contract; exposing
    /// it publicly would leak the cache-key shape through the API
    /// without enabling any external consumer the public projections
    /// ([`Self::marker`], [`Self::wrap`], [`Self::sexp_shape`],
    /// [`Self::iac_forge_tag`]) don't already serve. Same posture as
    /// [`crate::ast::QuoteForm::hash_discriminator`],
    /// [`StructuralKind::hash_discriminator`],
    /// [`crate::ast::AtomKind::hash_discriminator`], and
    /// [`SexpShape::hash_discriminator`] — every `hash_discriminator`
    /// projection on the substrate's typed-shape family is
    /// crate-private.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the (subset
    /// marker, cache-key byte) pairing becomes a TYPE projection on the
    /// substrate algebra rather than a per-callsite
    /// `.to_quote_form().hash_discriminator()` two-step. THEORY.md
    /// §II.1 invariant 2 — free middle; every consumer that has an
    /// [`UnquoteForm`] marker and wants the outer-Sexp cache-key byte
    /// routes through the SAME typed method, so a regression that
    /// drifts ONE consumer's byte from the others cannot reach the
    /// substrate's runtime cache. THEORY.md §VI.1 — generation over
    /// composition; the pairing emerges from ONE typed-algebra
    /// composition on the subset algebra rather than from parallel
    /// per-consumer per-variant literals. A future third template-
    /// substitution marker (e.g. `,~` reverse-unquote) extends
    /// [`Self::ALL`] + [`Self::to_quote_form`]'s dispatch table in
    /// lockstep — rustc-enforced through the closed-set exhaustiveness
    /// — with THIS method inheriting the extension through the
    /// [`crate::ast::QuoteForm::hash_discriminator`] composition site
    /// without a per-site edit.
    ///
    /// Frontier inspiration: MLIR's `mlir::TypeID::get<T>()` typed
    /// projection from a subset-op-family value into the canonical
    /// per-type identity byte the IR framework hashes on — the (subset
    /// op, canonical hash identity) pairing lives at ONE typed
    /// projection on the subset algebra, composed through the parent
    /// op-family's typed identity face. `UnquoteForm::hash_discriminator`
    /// is the Rust-typed peer on the closed-set [`UnquoteForm`]
    /// algebra with [`crate::ast::QuoteForm::hash_discriminator`]
    /// standing in for MLIR's parent op-family `TypeID` face.
    ///
    /// The `#[allow(dead_code)]` posture is deliberate: the substrate's
    /// current [`Hash for Sexp`](crate::ast::Sexp) body composes
    /// through [`crate::ast::QuoteForm::hash_discriminator`] at the
    /// four quote-family arms uniformly rather than splitting the
    /// dispatch into (2 non-substitution + 2 substitution) arms — so
    /// no non-test caller currently reaches THIS subset-algebra
    /// method's discriminator projection. The lift lands the
    /// substrate primitive so future consumers keyed on the
    /// substitution-subset carving specifically (a future
    /// [`crate::macro_expand::Expander`] cache-invalidation predicate
    /// that decides on the 2-of-4 substitution-subset only, a future
    /// `tatara-check` predicate `(check-substitution-subset-cache-key
    /// …)` that verifies the substitution-subset carving's cache-key
    /// partition sits inside `{5, 6}`, a future
    /// `TypedRewriter<UnquoteFormOp>` sweep that keys on the subset
    /// discriminator directly) bind to ONE typed algebra method
    /// rather than re-deriving the `.to_quote_form()
    /// .hash_discriminator()` composition per callsite. Matches the
    /// preemptive-primitive posture the prior-run [`Self::wrap`],
    /// [`Self::sexp_shape`], and [`Self::iac_forge_tag`] lifts
    /// carried before their downstream consumers materialized.
    #[must_use]
    #[allow(dead_code)]
    pub(crate) fn hash_discriminator(self) -> u8 {
        self.to_quote_form().hash_discriminator()
    }
}

// `impl std::fmt::Display for UnquoteForm` + `impl std::str::FromStr
// for UnquoteForm` + `impl tatara_closed_set::ClosedSet for UnquoteForm` +
// `pub struct UnknownUnquoteForm(pub String)` are generated by
// `#[derive(tatara_closed_set::DeriveClosedSet)]` on the enum declaration
// above. `label` delegates to the inherent `UnquoteForm::marker` via
// `#[closed_set(via = "marker")]` so the domain-canonical
// punctuation-marker projection (`","` / `",@"`) stays load-bearing at
// the inherent surface while the trait surface unifies every
// closed-set implementor's projection name onto `label`. The marker
// axis stays intentionally disjoint from the structural-axis
// `SexpShape` vocabulary (`"unquote"` / `"unquote-splice"`); the
// disjointness contract holds at the trait surface exactly because
// each implementor's `label` projects its own inherent
// axis-vocabulary. The `display` flag emits the substrate-wide
// `f.write_str(Self::marker(*self))` block.
// `#[closed_set(generate_unknown = "unquote form")]` emits the typed
// parse-rejection carrier with the substrate-wide `Debug + Clone +
// PartialEq + Eq + thiserror::Error` derives and the `#[error("unknown
// unquote form: {0}")]` annotation byte-for-byte; the explicit label
// matches the auto-derived `pascal_to_spaced_lowercase("UnquoteForm")`
// projection byte-for-byte but pins the pre-lift wording against any
// future change to the projection helper's behavior on this name. The
// FromStr decode is a linear sweep over `UnquoteForm::ALL` keyed on
// `marker`; round-trip + cross-axis rejection (`"unquote"` /
// `"unquote-splice"`) pinned by
// `unquote_form_marker_round_trips_through_from_str` +
// `unquote_form_from_str_rejects_sexp_shape_labels_on_template_marker_axis`.

/// Closed-set identifier for a kwargs-path projection — the `form:` label
/// shape that a typed-entry kwarg failure renders into the `compile error
/// in {form}:` prefix of a `LispError::TypeMismatch` diagnostic. Encodes
/// the three reachable path shapes the kwargs gate emits — `:<key>` for a
/// named kwarg (`extract_string` / `extract_int` / etc. failure),
/// `:<key>[<idx>]` for the Nth item of a list-typed kwarg
/// (`extract_string_list` per-item failure), and `kwargs[<idx>]` for an
/// even-position slot that failed the "this-position-must-be-a-keyword"
/// gate before a key was known (`parse_kwargs` direct call) — as a typed
/// borrowed enum, so authoring tools (REPL, LSP, `tatara-check`) bind to
/// path-shape identity (`KwargPath::Item { .. }` etc.) rather than
/// substring-matching the rendered prefix.
///
/// Mirror at the kwargs-path-shape boundary of the prior-run
/// `MacroDefHead` (macro-definition-head closed set),
/// `CompilerSpecIoStage` (disk-persistence surface),
/// `TemplateInvariantKind` (bytecode-runtime surface), and `UnquoteForm`
/// (template-marker syntactic forms) closed-set lifts: those enums key
/// their respective rejection variants on a typed identity carried inside
/// the variant's data shape; this enum keys the THREE distinct `form:`
/// label shapes emitted by the kwarg-gate's typed-entry chain on a typed
/// path identity. The three `format!` literals that used to live inline
/// in `domain.rs::kwarg_form` / `kwarg_item_form` / `kwargs_pos_form`
/// (three byte-identical `format!` shapes, one per helper) collapse into
/// ONE `Display` impl on this enum — the canonical literals (`":<key>"`
/// / `":<key>[<idx>]"` / `"kwargs[<idx>]"`) live in ONE place, so a typo
/// in any one of the three shapes can never drift independent of the
/// others (THEORY.md §VI.1 three-times rule). Adding a fourth path shape
/// (e.g., `:<key>.<field>` for nested-struct kwarg failures or
/// `:<key>::<variant>` for sum-typed kwarg failures) requires extending
/// this enum, which rustc-enforces matching at the `Display` projection
/// site.
///
/// `KwargPath` owns its `key` payload as `String` so it can inhabit
/// `LispError::TypeMismatch.form` (and any future error variant) without
/// a borrow constraint. The owned shape is the typed-slot promotion the
/// prior-run `KwargPath` landing pre-staged: every projection site that
/// used to produce a `String` via `KwargPath::Named(key).to_string()` (the
/// three sibling helpers `kwarg_form` / `kwarg_item_form` /
/// `kwargs_pos_form` and the fourth `kwarg_deserialize_form` helper) now
/// produces a typed `KwargPath` value directly; `type_mismatch` and every
/// `TypeMismatch.form` consumer pattern-match on the variant identity
/// (`KwargPath::Item { key, idx }`, `KwargPath::Slot(idx)`, etc.) instead
/// of substring-parsing the rendered prefix.
///
/// `Copy` is dropped because `String` is not `Copy`; `Clone + Debug +
/// PartialEq + Eq` are retained (same posture as every other owned-data
/// `LispError` field). The closed-set structural-completeness floor is
/// unchanged — only the data ownership changed.
///
/// Theory anchor: THEORY.md §V.1 — knowable platform; the closed set of
/// kwargs-path shapes becomes a TYPE rather than three byte-identical
/// `format!` literals scattered across helper definitions. THEORY.md
/// §VI.1 — generation over composition; the typed enum lands the
/// structural-completeness floor for the kwargs-path surface, parallel
/// to how `CompilerSpecIoStage` lands it for the disk-persistence
/// surface, `MacroDefHead` for the macro-definition-head surface,
/// `TemplateInvariantKind` for the bytecode-runtime surface, and
/// `UnquoteForm` for the template-marker surface. THEORY.md §II.1
/// invariant 1 — typed entry; the kwargs-path's renderable identity is
/// part of the proof of WHICH kwarg-gate fired, and the typed enum makes
/// that identity first-class — now as load-bearing data on the
/// `TypeMismatch` variant rather than as a projection-to-String.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum KwargPath {
    /// `:<key>` — failure at a named kwarg (`extract_string`,
    /// `extract_int`, `extract_float`, `extract_bool`, etc.). The `key`
    /// is the offending kwarg's identifier, owned so the variant lives
    /// independent of the call frame.
    Named(String),
    /// `:<key>[<idx>]` — failure at the Nth item of a list-typed kwarg
    /// (`extract_string_list` per-item failure). The `key` is the
    /// containing kwarg's identifier (owned); `idx` is the 0-based item
    /// index inside that kwarg's list value.
    Item { key: String, idx: usize },
    /// `kwargs[<idx>]` — failure at the Nth slot of the kwargs slice
    /// before a key was known (`parse_kwargs`'s
    /// "this-position-must-be-a-keyword" gate firing on an even-position
    /// slot). `idx` is the 0-based position into the raw kwargs slice
    /// (not into a particular kwarg's value).
    Slot(usize),
}

impl KwargPath {
    /// Owned constructor for the `:<key>` shape — used by every call site
    /// that has a `&str` borrow of the kwarg identifier and wants to lift
    /// it into the typed enum without an inline `.to_string()` projection.
    #[must_use]
    pub fn named(key: &str) -> Self {
        Self::Named(key.to_string())
    }

    /// Owned constructor for the `:<key>[<idx>]` shape — sibling of
    /// `named`, threading the per-item index alongside the kwarg key.
    #[must_use]
    pub fn item(key: &str, idx: usize) -> Self {
        Self::Item {
            key: key.to_string(),
            idx,
        }
    }

    /// Discriminator projection — strips the payload and returns the
    /// closed-set [`KwargPathKind`]. The same shape every sibling
    /// payload-carrying closed-set enum in the workspace projects through
    /// (e.g. `tatara_process::lifetime_clock::AutoTerminate::kind` →
    /// [`crate::error::KwargPath`]'s tatara-process cousin
    /// `AutoTerminateKind`, `TerminateReason::kind` →
    /// `TerminateReasonKind`, `crate::matrix::SelectStrategy::kind` →
    /// `SelectStrategyKind`).
    ///
    /// Consumers that group [`LispError::TypeMismatch`] /
    /// [`LispError::KwargDeserialize`] failures by path-shape
    /// CATEGORY rather than full path identity (failure-cluster metrics
    /// labelled `path_kind=named` / `path_kind=item` / `path_kind=slot`,
    /// an LSP that surfaces "this is a per-item failure" before drilling
    /// into the bracket-suffix, a future `tatara-check` diagnostic
    /// histogram that buckets by kind) project through this method
    /// instead of destructuring the variant and discarding the payload at
    /// every site. Adding a fourth path shape (e.g., `:<key>.<field>`
    /// for nested-struct kwarg failures or `:<key>::<variant>` for
    /// sum-typed kwarg failures) requires extending [`KwargPathKind`],
    /// which rustc-enforces matching at this projection.
    #[must_use]
    pub const fn kind(&self) -> KwargPathKind {
        match self {
            Self::Named(_) => KwargPathKind::Named,
            Self::Item { .. } => KwargPathKind::Item,
            Self::Slot(_) => KwargPathKind::Slot,
        }
    }
}

impl std::fmt::Display for KwargPath {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Named(key) => write!(f, ":{key}"),
            Self::Item { key, idx } => write!(f, ":{key}[{idx}]"),
            Self::Slot(idx) => write!(f, "kwargs[{idx}]"),
        }
    }
}

/// The closed set of [`KwargPath`] kinds — the discriminator view,
/// payload-stripped, that sibling closed-set lifts in this crate carry
/// (see [`SexpShape`], [`ExpectedKwargShape`], [`MacroDefHead`],
/// [`UnquoteForm`], [`CompilerSpecIoStage`], [`TemplateInvariantKind`]).
///
/// Mirrors the workspace-wide [`payload-carrier, payload-stripped kind]
/// pairing — `AutoTerminate` / `AutoTerminateKind`, `TerminateReason` /
/// `TerminateReasonKind`, `SelectStrategy` / `SelectStrategyKind`,
/// `ChannelVariant` / `ChannelKind`, `ArtifactVariant` / `ArtifactKind`,
/// `EncapsulationTarget` / `EncapsulationKind`. [`KwargPath`] owns the
/// per-variant payload (`key: String`, `idx: usize`); [`KwargPathKind`]
/// is the `Copy`-able discriminator view callers reach when they want
/// the CATEGORY without the payload.
///
/// Drives the `label` / [`Display`] / [`FromStr`] triad over [`Self::ALL`]
/// so a new variant added with an `ALL` entry automatically extends the
/// parser, the canonical wire-format projection, and any future
/// metrics-label / failure-cluster bucket that needs to enumerate the
/// kwargs-path categories. The `[Self; 3]` array literal forces the arity
/// so a fourth variant — a hypothetical `Field` for nested-struct kwarg
/// failures (`:<key>.<field>`) or `Variant` for sum-typed kwarg failures
/// (`:<key>::<variant>`) — cannot land without bumping the constant.
///
/// Theory anchor: THEORY.md §V.1 — knowable platform; the
/// payload-stripped kind becomes a TYPE rather than three byte-identical
/// `matches!` discriminator literals scattered across consumers.
/// THEORY.md §VI.1 — generation over composition; the typed kind enum
/// lands the structural-completeness floor for the path-shape category
/// surface, parallel to how [`KwargPath`] lands it for the path-identity
/// surface, [`ExpectedKwargShape`] for the expected-shape surface, etc.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, tatara_closed_set::DeriveClosedSet)]
#[closed_set(via = "label", display, generate_unknown = "kwarg path kind")]
pub enum KwargPathKind {
    /// The kind-view of [`KwargPath::Named`] — `:<key>` failures at a
    /// named kwarg (typed-atom extractors, `Option<T>` paths).
    Named,
    /// The kind-view of [`KwargPath::Item`] — `:<key>[<idx>]` failures
    /// at the Nth item of a list-typed kwarg
    /// (`extract_string_list` per-item).
    Item,
    /// The kind-view of [`KwargPath::Slot`] — `kwargs[<idx>]` failures
    /// at a kwargs slice slot before a key was known
    /// (`parse_kwargs`'s slot-must-be-a-keyword gate).
    Slot,
}

impl KwargPathKind {
    /// The closed set — single source of truth for [`Self::label`] /
    /// [`Display`] / [`FromStr`]. The `[Self; 3]` arity is forced at the
    /// declaration so a fourth variant cannot land without bumping the
    /// constant.
    pub const ALL: [Self; 3] = [Self::Named, Self::Item, Self::Slot];

    /// Canonical `&'static str` category label for [`Self::Named`] —
    /// the `:<key>` failure category emitted by every typed-atom
    /// extractor (`extract_string`, `extract_int`, `extract_float`,
    /// `extract_bool`, and their `Option<T>` siblings). Sibling
    /// posture to [`Self::ITEM_LABEL`] (`"item"`) and
    /// [`Self::SLOT_LABEL`] (`"slot"`) on the same category-label
    /// algebra layer.
    ///
    /// Pre-lift the same `"named"` bytes lived inline at the
    /// [`Self::label`] match arm plus at the sibling truth-table tests
    /// (`kwarg_path_kind_all_is_unique_and_complete` sorted-labels
    /// pin, `kwarg_path_kind_label_does_not_overlap_kwarg_path_display_renderings`
    /// disjointness sweep) — the ≥2 PRIME-DIRECTIVE trigger. Post-lift
    /// the (`Named` variant, canonical `&'static str`) pairing binds
    /// at ONE `pub const` on the typed [`KwargPathKind`] algebra: the
    /// [`Self::label`] arm and every consumer that pins the exact
    /// bytes route through this constant. Sibling posture to the
    /// closed set of per-role canonical `&'static str` labels on the
    /// substrate's other closed-set outer algebras:
    /// [`MacroDefHead::DEFMACRO_KEYWORD`] (`"defmacro"`),
    /// [`crate::ast::Atom::TRUE_LITERAL`] (`"#t"`),
    /// [`crate::ast::QuoteForm::QUOTE_PREFIX`] (`"'"`),
    /// [`crate::macro_expand::MacroParams::REST_MARKER`] (`"&rest"`).
    pub const NAMED_LABEL: &'static str = "named";

    /// Canonical `&'static str` category label for [`Self::Item`] —
    /// the `:<key>[<idx>]` failure category emitted by
    /// `extract_string_list`'s per-item gate. Sibling posture to
    /// [`Self::NAMED_LABEL`] (`"named"`) and [`Self::SLOT_LABEL`]
    /// (`"slot"`) on the same category-label algebra layer.
    ///
    /// Pre-lift the same `"item"` bytes lived inline at the
    /// [`Self::label`] match arm plus at the sibling truth-table
    /// tests. Post-lift the (`Item` variant, canonical `&'static str`)
    /// pairing binds at ONE `pub const` on the typed [`KwargPathKind`]
    /// algebra.
    pub const ITEM_LABEL: &'static str = "item";

    /// Canonical `&'static str` category label for [`Self::Slot`] —
    /// the `kwargs[<idx>]` failure category emitted by
    /// `parse_kwargs`'s slot-must-be-a-keyword gate. Sibling posture
    /// to [`Self::NAMED_LABEL`] (`"named"`) and [`Self::ITEM_LABEL`]
    /// (`"item"`) on the same category-label algebra layer.
    ///
    /// Pre-lift the same `"slot"` bytes lived inline at the
    /// [`Self::label`] match arm plus at the sibling truth-table
    /// tests. Post-lift the (`Slot` variant, canonical `&'static str`)
    /// pairing binds at ONE `pub const` on the typed [`KwargPathKind`]
    /// algebra.
    pub const SLOT_LABEL: &'static str = "slot";

    /// The closed set of three canonical `&'static str` category
    /// labels — the [`Self::NAMED_LABEL`] (`"named"`) typed-atom-
    /// extractor failure category followed by the [`Self::ITEM_LABEL`]
    /// (`"item"`) list-item failure category followed by the
    /// [`Self::SLOT_LABEL`] (`"slot"`) kwargs-slice-slot failure
    /// category. Canonical declaration order matches [`Self::ALL`] so
    /// `Self::LABELS[i] == Self::ALL[i].label()` element-wise —
    /// pinned by `kwarg_path_kind_labels_align_with_all_by_index`.
    ///
    /// Sibling posture to [`MacroDefHead::KEYWORDS`]
    /// (`[&'static str; 3]`) — every closed-set algebra now pins its
    /// label-projection ALL array at the declaration site via a
    /// forced-arity `[&'static str; N]` array whose length fails
    /// compilation if a new variant lands without being added to the
    /// set. Adding a hypothetical fourth category (a `Root` failure
    /// category for a future kwargs-root-level rejection, a `Tail`
    /// failure category for a future nested-list-tail extractor)
    /// extends [`Self::ALL`] ONCE + [`Self::label`] ONCE +
    /// [`Self::LABELS`] ONCE + adds ONE per-role label `pub const`
    /// — rustc's forced-arity check on the `[Self; N]` array +
    /// `[&'static str; N]` array pair enforces every downstream
    /// consumer picks up the extension mechanically.
    ///
    /// Future consumers that compose against [`Self::LABELS`]: an
    /// LSP / REPL completion provider surfacing every legal category
    /// name in a `path_kind=` metrics query bar
    /// (`Self::LABELS.iter()` is the ONE typed sweep over every legal
    /// kwarg-path category), a `tatara-check` coverage assertion
    /// (every workspace `.lisp` file's typed-atom rejection must
    /// classify to some entry of `Self::LABELS`), a Sekiban
    /// audit-trail metric jointly labeled by [`Self::label`] whose
    /// metric-label set IS `Self::LABELS` (e.g.
    /// `tatara_lisp_kwarg_type_mismatch_total{path_kind="named"}`).
    pub const LABELS: [&'static str; 3] = [Self::NAMED_LABEL, Self::ITEM_LABEL, Self::SLOT_LABEL];

    /// Project the typed [`KwargPathKind`] to the canonical `&'static str`
    /// literal — lowercase byte-equal to the variant name (`"named"` /
    /// `"item"` / `"slot"`). The labels are kept distinct from the
    /// [`KwargPath::Display`] renderings (`":<key>"` / `":<key>[<idx>]"`
    /// / `"kwargs[<idx>]"`) because this projection names the CATEGORY,
    /// not the rendered identity — a metrics label `path_kind="named"`
    /// makes more sense at the kind boundary than a path-prefix template
    /// would.
    ///
    /// Body routes each arm through the per-role [`Self::NAMED_LABEL`] /
    /// [`Self::ITEM_LABEL`] / [`Self::SLOT_LABEL`] `pub const` so the
    /// three canonical `&'static str` labels live at ONE `pub const`
    /// per variant rather than at TWO sites (the per-role `pub const`
    /// AND an inline arm literal). Sibling posture to
    /// [`MacroDefHead::keyword`]'s arms routing through the per-role
    /// [`MacroDefHead::DEFMACRO_KEYWORD`] / [`MacroDefHead::DEFPOINT_TEMPLATE_KEYWORD`]
    /// / [`MacroDefHead::DEFCHECK_KEYWORD`] constants.
    ///
    /// Same shape every sibling kind-projection in the workspace uses
    /// (`AutoTerminateKind::as_str`, `TerminateReasonKind::as_str`,
    /// [`SexpShape::label`], [`ExpectedKwargShape::label`]).
    #[must_use]
    pub const fn label(self) -> &'static str {
        match self {
            Self::Named => Self::NAMED_LABEL,
            Self::Item => Self::ITEM_LABEL,
            Self::Slot => Self::SLOT_LABEL,
        }
    }
}

// `impl std::fmt::Display for KwargPathKind` + `impl std::str::FromStr
// for KwargPathKind` + `impl tatara_closed_set::ClosedSet for KwargPathKind` +
// `pub struct UnknownKwargPathKind(pub String)` are generated by
// `#[derive(tatara_closed_set::DeriveClosedSet)]` on the enum declaration
// above. `label` delegates to the inherent `KwargPathKind::label` via
// `#[closed_set(via = "label")]` — the inherent name coincides with
// the trait method name here, but the delegation stays explicit so the
// SAME wiring shape applies whether the inherent projection is named
// `label` / `prefix` / `marker` / `keyword` / `as_str`. The `display`
// flag emits the substrate-wide `f.write_str(Self::label(*self))` block.
// `#[closed_set(generate_unknown = "kwarg path kind")]` emits the typed
// parse-rejection carrier with the substrate-wide `Debug + Clone +
// PartialEq + Eq + thiserror::Error` derives and the `#[error("unknown
// kwarg path kind: {0}")]` annotation byte-for-byte; the explicit label
// matches the auto-derived `pascal_to_spaced_lowercase("KwargPathKind")`
// projection byte-for-byte but pins the pre-lift wording. Round-trip +
// cross-axis rejection (path-rendering literals `":foo"` / `":foo[0]"` /
// `"kwargs[0]"`) pinned by
// `kwarg_path_kind_label_round_trips_through_from_str` +
// `unknown_kwarg_path_kind_carries_offending_input_verbatim`.

/// Closed-set identifier for the `expected:` slot of a
/// `LispError::TypeMismatch` diagnostic — the seven reachable
/// expected-shape labels the typed-entry kwarg gate emits:
/// `Keyword` (the `parse_kwargs` slot-must-be-a-keyword gate),
/// `String` / `Int` / `Number` / `Bool` (the typed-atom extractors —
/// `extract_string`, `extract_int`, `extract_float`, `extract_bool`,
/// and their `Option` siblings, plus `extract_string_list`'s per-item
/// `string` gate), `List` (the `extract_vec_via_serde` outer-shape
/// gate), and `ListOfStrings` (the `extract_string_list` outer-shape
/// gate). Encoded as a typed enum so the closed set becomes
/// load-bearing data on `LispError::TypeMismatch.expected` rather than
/// a `&'static str` literal scattered across eleven call sites in
/// `domain.rs`.
///
/// Mirror at the expected-shape boundary of the prior-run `KwargPath`
/// (kwargs-path-shape closed set), `MacroDefHead` (macro-definition-
/// head closed set), `CompilerSpecIoStage` (disk-persistence surface),
/// `TemplateInvariantKind` (bytecode-runtime surface), and
/// `UnquoteForm` (template-marker syntactic forms) closed-set lifts:
/// those enums key their respective rejection variants on a typed
/// identity carried inside the variant's data shape; this enum keys
/// the SECOND slot (`expected`) of every `LispError::TypeMismatch`
/// site on a typed expected-shape identity, alongside the
/// already-typed `form: KwargPath`. After this lift the type-mismatch
/// variant's identity is fully closed-set typed in TWO of its three
/// slots — only `got: &'static str` remains as a `&'static str`
/// projection, and that slot's compile-time guarantee is sourced from
/// `crate::domain::sexp_type_name`'s exhaustive `Sexp` match.
///
/// Adding a future expected-shape (e.g. `Float` once `extract_float`
/// stops accepting integers, `Symbol` if a future extractor accepts
/// only `Sexp::Atom(Symbol)`, or a parameterized `ListOf(Box<Self>)`
/// for nested-typed-vec extractors) requires extending this enum,
/// which rustc-enforces matching at every projection site
/// (`label()`).
///
/// `label(self) -> &'static str` projects the typed `ExpectedKwargShape`
/// back to the canonical literal for `LispError::Display` rendering.
/// The `&'static str` lifetime is load-bearing: it lets the variant
/// project through this method into the `expected {expected}` slot of
/// the `#[error(...)]` annotation without an allocation, parallel to
/// how `MacroDefHead::keyword()`, `UnquoteForm::marker()`, and
/// `CompilerSpecIoStage::operation()` / `label()` feed their
/// respective `LispError::*` Display impls.
///
/// Theory anchor: THEORY.md §V.1 — knowable platform; the closed set
/// of expected-shape labels becomes a TYPE rather than eleven
/// `&'static str` literal call sites scattered across the kwarg
/// extractors. A typo in any literal can never drift into the
/// diagnostic at runtime; a regression that drifts the expected-shape
/// label (e.g. a typo `"strin"` for `"string"`) becomes a type error
/// at the call site, not a runtime substring drift. THEORY.md §VI.1 —
/// generation over composition; the typed enum lands the structural-
/// completeness floor for the expected-shape surface, parallel to how
/// `KwargPath` lands it for the kwargs-path surface, `MacroDefHead`
/// for the macro-definition-head surface, `UnquoteForm` for the
/// template-marker surface, `CompilerSpecIoStage` for the disk-
/// persistence surface, and `TemplateInvariantKind` for the bytecode-
/// runtime surface. THEORY.md §II.1 invariant 1 — typed entry; the
/// expected-shape identity is part of the proof of WHICH typed-entry
/// kwarg gate fired, and the typed enum makes that identity first-
/// class as load-bearing data on the variant rather than as a
/// projection-to-String at the helper boundary.
#[derive(Debug, Clone, Copy, PartialEq, Eq, tatara_closed_set::DeriveClosedSet)]
#[closed_set(via = "label", display, generate_unknown = "expected kwarg shape")]
pub enum ExpectedKwargShape {
    /// `"keyword"` — emitted by `parse_kwargs`'s
    /// "this-position-must-be-a-keyword" gate when an even-position
    /// slot in the kwargs slice isn't a `Sexp::Atom(Keyword(_))`.
    Keyword,
    /// `"string"` — emitted by `extract_string` /
    /// `extract_optional_string` (the kwarg's value isn't a
    /// `Sexp::Atom(Str(_))`) AND by `extract_string_list`'s per-item
    /// gate (an item inside a list-typed kwarg isn't a string).
    String,
    /// `"int"` — emitted by `extract_int` / `extract_optional_int`
    /// when the kwarg's value isn't a `Sexp::Atom(Int(_))`.
    Int,
    /// `"number"` — emitted by `extract_float` /
    /// `extract_optional_float` when the kwarg's value isn't a
    /// numeric atom. Wider than `Int`: `extract_float` accepts both
    /// `Sexp::Atom(Float(_))` and `Sexp::Atom(Int(_))` via
    /// `Sexp::as_float`, so the expected-shape label is the union
    /// "number" rather than the narrower "float".
    Number,
    /// `"bool"` — emitted by `extract_bool` / `extract_optional_bool`
    /// when the kwarg's value isn't a `Sexp::Atom(Bool(_))`.
    Bool,
    /// `"list"` — emitted by `extract_vec_via_serde`'s outer-shape
    /// gate when the kwarg's value isn't a `Sexp::List(_)`. Used by
    /// the universal-Deserialize fallthrough for any `Vec<T>` field.
    List,
    /// `"list of strings"` — emitted by `extract_string_list`'s
    /// outer-shape gate when the kwarg's value isn't a
    /// `Sexp::List(_)`. Wider than `List`: names the expected
    /// element-type so the diagnostic reads `expected list of
    /// strings, got string` instead of the bare `expected list, got
    /// string`. The per-item gate fires `String` (the narrower
    /// expected-shape for the element-type failure).
    ListOfStrings,
}

impl ExpectedKwargShape {
    /// The closed set of seven reachable expected-kwarg shapes — single
    /// source of truth that drives the [`Self::label`] / [`fmt::Display`]
    /// projection AND the [`FromStr`] decode sweep keyed on
    /// [`Self::label`]. Adding a hypothetical eighth variant (e.g.
    /// `Float` once `extract_float` stops accepting integers, `Symbol`
    /// if a future extractor accepts only `Sexp::Atom(Symbol)`, or a
    /// parameterized `ListOf(Box<Self>)` for nested-typed-vec
    /// extractors) lands at one [`Self::ALL`] entry + one [`Self::label`]
    /// arm — exhaustively checked by the compiler (the `[Self; 7]`
    /// array literal forces the arity) AND by the per-variant
    /// truth-table tests below.
    ///
    /// Sibling closed-set lift to every other typed-shape enum the
    /// substrate carries: this crate's own [`SexpShape::ALL`] (the
    /// twelve reachable outer shapes the reader can produce — peer
    /// axis on the same `Sexp` algebra, whose vocabulary overlaps
    /// with this set on five of seven entries — `"keyword"`,
    /// `"string"`, `"int"`, `"bool"`, `"list"` — and does NOT overlap
    /// on two — `"number"` ⊎ `"list of strings"`; the overlap is
    /// intentional and pinned by the cross-axis tests), and across
    /// the workspace ([`MacroDefHead::ALL`], [`UnquoteForm::ALL`],
    /// [`crate::ast::AtomKind::ALL`], [`crate::ast::QuoteForm::ALL`],
    /// `ConditionKind::ALL`, `ProcessPhase::ALL`,
    /// `ProcessSignal::ALL`, `ChannelKind::ALL`, `IntentKind::ALL`,
    /// `LifetimeKind::ALL`, `RequestorKind::ALL`, `ReceiptKind::ALL`,
    /// …) every one of which paired its typed projection with `ALL`
    /// before this lift.
    ///
    /// Future consumers that compose against `ALL`: LSP / REPL
    /// completion for the operator-facing rendered expected-shape
    /// label (every `expected X, ...` substring in `LispError`'s
    /// rendered diagnostics keys on this set's projection through
    /// [`Self::label`]); `tatara-check` coverage assertions over
    /// which expected-shape variants reach a `TypeMismatch.expected`
    /// arm at all — the typed sweep replaces the per-call-site
    /// vocabulary of seven `&'static str` literals; any future
    /// audit-trail metric jointly labeled by [`Self::label`] (e.g.
    /// `tatara_lisp_type_mismatch_total{expected="number"}`) — the
    /// metric label set IS [`Self::ALL`] mapped through
    /// [`Self::label`].
    pub const ALL: [Self; 7] = [
        Self::Keyword,
        Self::String,
        Self::Int,
        Self::Number,
        Self::Bool,
        Self::List,
        Self::ListOfStrings,
    ];

    /// Canonical `&'static str` bytes for the `Keyword` expected-shape —
    /// aliases [`SexpShape::KEYWORD_LABEL`] on the ExpectedKwargShape ⊂
    /// SexpShape 5-of-7 subset carving so the shared `"keyword"`
    /// vocabulary binds at ONE `pub const` on the parent-superset's
    /// `SexpShape::KEYWORD_LABEL` arm rather than at TWO independent
    /// literal-discipline sites (the per-role `pub const` here AND the
    /// per-role `pub const` on `SexpShape`). Per-role peer of
    /// `Self::Keyword` on the closed-set outer algebra; every consumer
    /// of the `"keyword"` bytes (Display, FromStr, the derive-
    /// generated `UnknownExpectedKwargShape` carrier, LSP completion,
    /// audit-trail metric labels) routes through THIS constant, so a
    /// spelling migration (a hypothetical port to `":keyword"`,
    /// `"kwarg-key"`, or a case-fold to `"Keyword"`) at
    /// [`SexpShape::KEYWORD_LABEL`] propagates HERE structurally at
    /// rustc time rather than through a parallel literal edit.
    ///
    /// Sibling posture to [`Self::STRING_LABEL`], [`Self::INT_LABEL`],
    /// [`Self::BOOL_LABEL`], [`Self::LIST_LABEL`] — the FIVE
    /// ExpectedKwargShape variants that share bytes with a matching
    /// [`SexpShape`] carving arm all bind through this same alias
    /// chain. The TWO non-overlapping siblings [`Self::NUMBER_LABEL`]
    /// (`"number"` — the wider numeric-union label distinct from
    /// [`SexpShape::FLOAT_LABEL`]'s `"float"`) and
    /// [`Self::LIST_OF_STRINGS_LABEL`] (`"list of strings"` — an
    /// element-typed refinement with no [`SexpShape`] peer) stay as
    /// direct literals since there is no superset arm to alias
    /// through. The 5-of-7 carving IS the intersection
    /// `ExpectedKwargShape::ALL ∩ SexpShape::ALL` on the
    /// `&'static str` label vocabulary.
    pub const KEYWORD_LABEL: &'static str = SexpShape::KEYWORD_LABEL;

    /// Canonical `&'static str` bytes for the `String` expected-shape —
    /// aliases [`SexpShape::STRING_LABEL`] on the ExpectedKwargShape ⊂
    /// SexpShape 5-of-7 subset carving. Per-role peer of `Self::String`
    /// on the closed-set outer algebra. Emitted by `extract_string` /
    /// `extract_optional_string` AND by `extract_string_list`'s per-
    /// item gate. See [`Self::KEYWORD_LABEL`] for the alias-chain shape
    /// every sibling in the 5-of-7 carving shares.
    pub const STRING_LABEL: &'static str = SexpShape::STRING_LABEL;

    /// Canonical `&'static str` bytes for the `Int` expected-shape —
    /// aliases [`SexpShape::INT_LABEL`] on the ExpectedKwargShape ⊂
    /// SexpShape 5-of-7 subset carving. Per-role peer of `Self::Int`
    /// on the closed-set outer algebra; the sibling
    /// [`Self::NUMBER_LABEL`] distinguishes the wider numeric-union
    /// case `extract_float` emits (which has NO [`SexpShape`] peer —
    /// [`SexpShape::FLOAT_LABEL`] is the narrower `"float"`). See
    /// [`Self::KEYWORD_LABEL`] for the alias-chain shape.
    pub const INT_LABEL: &'static str = SexpShape::INT_LABEL;

    /// Canonical `&'static str` bytes for the `Number` expected-shape —
    /// emitted by `extract_float` / `extract_optional_float` when the
    /// kwarg's value isn't a numeric atom. The "number" naming (not
    /// "float") is load-bearing: `extract_float` accepts BOTH
    /// `Sexp::Atom(Float(_))` and `Sexp::Atom(Int(_))` via
    /// `Sexp::as_float`, so the expected-shape label names the union
    /// rather than the narrower Float element-type. INTENTIONALLY NOT
    /// aliased through [`SexpShape`]: the `SexpShape::Float` variant's
    /// label is `"float"` (the NARROWER element-type), not `"number"`,
    /// so this constant has NO peer on the parent-superset algebra to
    /// alias through. Divergence pinned by
    /// `sexp_shape_atom_carving_labels_align_with_expected_kwarg_shape_labels`'s
    /// `assert_ne!(SexpShape::FLOAT_LABEL, ExpectedKwargShape::NUMBER_LABEL)`
    /// disjointness pin — the TWO non-overlapping arms of the 7-arm
    /// closed set are the natural residual once the 5-of-7 subset
    /// carving aliases through [`SexpShape`].
    pub const NUMBER_LABEL: &'static str = "number";

    /// Canonical `&'static str` bytes for the `Bool` expected-shape —
    /// aliases [`SexpShape::BOOL_LABEL`] on the ExpectedKwargShape ⊂
    /// SexpShape 5-of-7 subset carving. Per-role peer of `Self::Bool`
    /// on the closed-set outer algebra. Emitted by `extract_bool` /
    /// `extract_optional_bool` when the kwarg's value isn't a
    /// `Sexp::Atom(Bool(_))`. See [`Self::KEYWORD_LABEL`] for the
    /// alias-chain shape.
    pub const BOOL_LABEL: &'static str = SexpShape::BOOL_LABEL;

    /// Canonical `&'static str` bytes for the `List` expected-shape —
    /// aliases [`SexpShape::LIST_LABEL`] on the ExpectedKwargShape ⊂
    /// SexpShape 5-of-7 subset carving. Per-role peer of `Self::List`
    /// on the closed-set outer algebra; the wider
    /// [`Self::LIST_OF_STRINGS_LABEL`] names the element-typed variant
    /// (which has NO [`SexpShape`] peer — the SexpShape algebra
    /// doesn't type-index list-of-strings as a distinct shape). See
    /// [`Self::KEYWORD_LABEL`] for the alias-chain shape.
    pub const LIST_LABEL: &'static str = SexpShape::LIST_LABEL;

    /// Canonical `&'static str` bytes for the `ListOfStrings`
    /// expected-shape — emitted by `extract_string_list`'s outer-shape
    /// gate when the kwarg's value isn't a `Sexp::List(_)`. The
    /// `"list of strings"` naming is load-bearing: it names the
    /// element-type (String) so the diagnostic reads `expected list of
    /// strings, got string` instead of the ambiguous `expected list,
    /// got string`. The per-item gate fires `STRING_LABEL` (the
    /// narrower element-type failure).
    pub const LIST_OF_STRINGS_LABEL: &'static str = "list of strings";

    /// Closed-set forced-arity ALL array over the canonical expected-
    /// shape `&'static str` bytes, in declaration order matching
    /// [`Self::ALL`] element-wise (pinned by
    /// `expected_kwarg_shape_labels_align_with_all_by_index`). Sibling
    /// posture to `KwargPathKind::LABELS: [&'static str; 3]`,
    /// `MacroDefHead::KEYWORDS: [&'static str; 3]`,
    /// `MacroParams::LAMBDA_LIST_KEYWORDS: [&'static str; 2]`,
    /// `Atom::BOOL_LITERALS: [&'static str; 2]`, and
    /// `QuoteForm::PREFIXES: [&'static str; 4]` — every closed-set
    /// outer projection on the substrate that carries an `&'static
    /// str`-per-variant label now pins its per-role canonical bytes
    /// at ONE `pub const` per role PLUS an ALL array for family-wide
    /// consumers.
    ///
    /// Future consumers that compose against `LABELS`: LSP completion
    /// surfacing the seven expected-shape labels in a
    /// `expected=` metrics query bar, a `tatara-check` coverage
    /// assertion sweeping `LABELS` over workspace `.lisp` files'
    /// kwarg-gate rejection sites, a Sekiban audit-trail metric
    /// labeled by the canonical expected-shape (e.g.
    /// `tatara_lisp_type_mismatch_total{expected="number"}`) whose
    /// metric-label set IS `LABELS`. Adding an eighth variant (e.g.
    /// `Float` once `extract_float` stops accepting integers,
    /// `Symbol`, or a parameterized `ListOfInts`) extends
    /// [`Self::ALL`] AND [`Self::LABELS`] AND [`Self::label`]'s arm
    /// AND one new per-role `pub const` in lockstep — rustc's forced-
    /// arity check on the two `[_; N]` arrays fails compilation if
    /// EITHER ALL array grows without the other.
    pub const LABELS: [&'static str; 7] = [
        Self::KEYWORD_LABEL,
        Self::STRING_LABEL,
        Self::INT_LABEL,
        Self::NUMBER_LABEL,
        Self::BOOL_LABEL,
        Self::LIST_LABEL,
        Self::LIST_OF_STRINGS_LABEL,
    ];

    /// Project the typed `ExpectedKwargShape` to the canonical
    /// `&'static str` literal — feeds the `LispError::TypeMismatch`
    /// Display rendering via the `#[error(...)]` annotation. The
    /// `&'static str` lifetime is load-bearing: it lets the variant
    /// project through this method into the `expected {expected}` slot
    /// of the `#[error(...)]` annotation without an allocation,
    /// parallel to how `MacroDefHead::keyword()`,
    /// `UnquoteForm::marker()`, [`SexpShape::label`], and
    /// `CompilerSpecIoStage::operation()` / `label()` feed their
    /// respective `LispError::*` Display impls.
    ///
    /// Each arm routes through the per-role `pub const` on
    /// `impl Self` ([`Self::KEYWORD_LABEL`], [`Self::STRING_LABEL`],
    /// [`Self::INT_LABEL`], [`Self::NUMBER_LABEL`],
    /// [`Self::BOOL_LABEL`], [`Self::LIST_LABEL`],
    /// [`Self::LIST_OF_STRINGS_LABEL`]) so the seven canonical
    /// expected-shape byte-strings bind at ONE typed source of truth
    /// per role rather than as inline literals scattered across the
    /// `match` body. Sibling posture to
    /// `KwargPathKind::label`'s post-lift arms.
    ///
    /// The bidirectional contract is anchored by tests:
    /// `label_renders_canonical_string_for_every_variant` pins each
    /// variant's canonical literal so a typo in any arm fails-loudly,
    /// `display_matches_label_for_every_variant` pins
    /// Display-equals-label so the `#[error(...)]` annotation's
    /// `{expected}` slot projects byte-for-byte through this method,
    /// and `expected_kwarg_shape_label_round_trips_through_from_str`
    /// pins the `label` ↔ [`FromStr`] round-trip for every variant in
    /// [`Self::ALL`] so the typed surface and the rendered diagnostic
    /// literal cannot drift.
    #[must_use]
    pub fn label(self) -> &'static str {
        match self {
            Self::Keyword => Self::KEYWORD_LABEL,
            Self::String => Self::STRING_LABEL,
            Self::Int => Self::INT_LABEL,
            Self::Number => Self::NUMBER_LABEL,
            Self::Bool => Self::BOOL_LABEL,
            Self::List => Self::LIST_LABEL,
            Self::ListOfStrings => Self::LIST_OF_STRINGS_LABEL,
        }
    }
}

// `impl std::fmt::Display for ExpectedKwargShape` +
// `impl std::str::FromStr for ExpectedKwargShape` +
// `impl tatara_closed_set::ClosedSet for ExpectedKwargShape` +
// `pub struct UnknownExpectedKwargShape(pub String)` are generated by
// `#[derive(tatara_closed_set::DeriveClosedSet)]` on the enum declaration
// above. `label` delegates to the inherent `ExpectedKwargShape::label`
// via `#[closed_set(via = "label")]` — the inherent name coincides
// with the trait method name here; the delegation stays explicit so
// the SAME wiring shape applies whether the inherent projection is
// `label` / `prefix` / `marker` / `keyword` / `as_str`. The `display`
// flag emits the substrate-wide `f.write_str(Self::label(*self))`
// block. `#[closed_set(generate_unknown = "expected kwarg shape")]`
// emits the typed parse-rejection carrier with the substrate-wide
// `Debug + Clone + PartialEq + Eq + thiserror::Error` derives and the
// `#[error("unknown expected kwarg shape: {0}")]` annotation
// byte-for-byte; the explicit label matches the auto-derived
// `pascal_to_spaced_lowercase("ExpectedKwargShape")` projection
// byte-for-byte but pins the pre-lift wording. Round-trip + cross-axis
// rejection (`SexpShape` structural labels `"nil"` / `"symbol"` /
// `"float"` / `"quote"` / `"quasiquote"` / `"unquote"` /
// `"unquote-splice"`) pinned by
// `expected_kwarg_shape_label_round_trips_through_from_str` +
// `expected_kwarg_shape_from_str_accepts_only_canonical_labels`.

/// Closed-set identifier for the outermost shape of a `Sexp` — the twelve
/// reachable shapes the reader can produce (`Nil` ⊎ `Symbol` ⊎ `Keyword` ⊎
/// `String` ⊎ `Int` ⊎ `Float` ⊎ `Bool` ⊎ `List` ⊎ `Quote` ⊎ `Quasiquote` ⊎
/// `Unquote` ⊎ `UnquoteSplice`). Carried as a typed slot on
/// `LispError::TypeMismatch.got` and `LispError::NamedFormNonSymbolName.got`
/// so authoring tools (REPL, LSP, `tatara-check`) bind to variant identity
/// (`SexpShape::Int` etc.) directly rather than substring-matching the
/// rendered `got` literal.
///
/// Mirror at the observed-shape boundary of the prior-run `KwargPath`
/// (kwargs-path-shape closed set), `ExpectedKwargShape` (kwarg-gate's
/// expected-shape closed set), `MacroDefHead` (macro-definition-head
/// closed set), `CompilerSpecIoStage` (disk-persistence surface),
/// `TemplateInvariantKind` (bytecode-runtime surface), and `UnquoteForm`
/// (template-marker syntactic forms) closed-set lifts: those enums key
/// their respective rejection variants on a typed identity carried inside
/// the variant's data shape; this enum keys the THIRD slot (`got`) of
/// every `LispError::TypeMismatch` site on a typed observed-shape identity
/// — alongside the already-typed `form: KwargPath` and
/// `expected: ExpectedKwargShape`. After this lift the type-mismatch
/// variant's identity is fully closed-set typed in ALL THREE of its slots
/// — no `&'static str` projection at any helper boundary, every reachable
/// identity encoded as a variant of a typed enum.
///
/// Adding a future `Sexp` variant (e.g. a hypothetical `Sexp::Vector` for
/// `#(...)` reader syntax, or `Sexp::Map` for `{...}`) requires extending
/// this enum, which rustc-enforces matching at every projection site
/// (`label()`, `crate::domain::sexp_shape`).
///
/// `label(self) -> &'static str` projects the typed `SexpShape` back to
/// the canonical literal for `LispError::Display` rendering. The
/// `&'static str` lifetime is load-bearing: it lets the variant project
/// through this method into the `got {got}` slot of the `#[error(...)]`
/// annotation without an allocation, parallel to how
/// `ExpectedKwargShape::label()`, `MacroDefHead::keyword()`,
/// `UnquoteForm::marker()`, and `CompilerSpecIoStage::operation()` /
/// `label()` feed their respective `LispError::*` Display impls.
///
/// Theory anchor: THEORY.md §V.1 — knowable platform; the closed set of
/// observed-Sexp shapes becomes a TYPE rather than a `&'static str`
/// projection through a string-keyed helper. A regression that drifts the
/// observed-shape label (e.g. a typo `"strin"` for `"string"`) becomes a
/// type error at the call site, not a runtime substring drift. THEORY.md
/// §VI.1 — generation over composition; the typed enum lands the
/// structural-completeness floor for the observed-shape surface, parallel
/// to how `ExpectedKwargShape` lands it for the expected-shape surface,
/// `KwargPath` for the kwargs-path surface, `MacroDefHead` for the
/// macro-definition-head surface, `UnquoteForm` for the template-marker
/// surface, `CompilerSpecIoStage` for the disk-persistence surface, and
/// `TemplateInvariantKind` for the bytecode-runtime surface. THEORY.md
/// §II.1 invariant 1 — typed entry; the observed-shape identity is part
/// of the proof of WHAT the typed-entry gate observed, and the typed enum
/// makes that identity first-class as load-bearing data on the variant
/// rather than as a projection-to-`&'static str` at the helper boundary.
#[derive(Debug, Clone, Copy, PartialEq, Eq, tatara_closed_set::DeriveClosedSet)]
#[closed_set(via = "label", display, generate_unknown = "sexp shape")]
pub enum SexpShape {
    /// `"nil"` — `Sexp::Nil`.
    Nil,
    /// `"symbol"` — `Sexp::Atom(Symbol(_))`.
    Symbol,
    /// `"keyword"` — `Sexp::Atom(Keyword(_))`.
    Keyword,
    /// `"string"` — `Sexp::Atom(Str(_))`.
    String,
    /// `"int"` — `Sexp::Atom(Int(_))`.
    Int,
    /// `"float"` — `Sexp::Atom(Float(_))`.
    Float,
    /// `"bool"` — `Sexp::Atom(Bool(_))`.
    Bool,
    /// `"list"` — `Sexp::List(_)`.
    List,
    /// `"quote"` — `Sexp::Quote(_)`.
    Quote,
    /// `"quasiquote"` — `Sexp::Quasiquote(_)`.
    Quasiquote,
    /// `"unquote"` — `Sexp::Unquote(_)`.
    Unquote,
    /// `"unquote-splice"` — `Sexp::UnquoteSplice(_)`.
    UnquoteSplice,
}

impl SexpShape {
    /// The closed set of reachable `Sexp` outermost shapes — single
    /// source of truth that drives the [`Self::label`] / [`fmt::Display`]
    /// projection AND the [`FromStr`] decode sweep keyed on
    /// [`Self::label`]. Adding a hypothetical thirteenth variant (e.g.
    /// `Vector` for `#(...)` reader syntax, `Map` for `{...}`, or
    /// `Char` for `#\x`) lands at one `ALL` entry + one `label` arm —
    /// exhaustively checked by the compiler (the `[Self; 12]` array
    /// literal forces the arity) AND by the per-variant truth-table
    /// tests below. Sibling closed-set lift to every other typed-shape
    /// enum the substrate carries: this crate's own [`UnquoteForm`]
    /// (the four template markers — the only other closed set on the
    /// `Sexp` algebra with `Sexp variant ↔ enum variant` parity), and
    /// the cross-crate `tatara-process` family
    /// (`ConditionKind::ALL`, `ProcessPhase::ALL`,
    /// `ProcessSignal::ALL`, `ChannelKind::ALL`, `IntentKind::ALL`,
    /// …) every one of which paired its typed projection with `ALL`
    /// before this lift.
    ///
    /// Future consumers that compose against `ALL`:
    /// - LSP / REPL completion for the operator-facing rendered
    ///   shape label (every `expected X, got Y` substring in
    ///   `LispError`'s rendered diagnostics keys on this set);
    /// - `tatara-check` coverage assertions over which `SexpShape`
    ///   variants reach a `TypeMismatch.got` arm at all;
    /// - any future audit-trail metric jointly labeled by
    ///   `SexpShape::label` (e.g.
    ///   `tatara_lisp_type_mismatch_total{got="symbol"}`) — the
    ///   metric label set IS [`Self::ALL`] mapped through
    ///   [`Self::label`].
    pub const ALL: [Self; 12] = [
        Self::Nil,
        Self::Symbol,
        Self::Keyword,
        Self::String,
        Self::Int,
        Self::Float,
        Self::Bool,
        Self::List,
        Self::Quote,
        Self::Quasiquote,
        Self::Unquote,
        Self::UnquoteSplice,
    ];

    /// Canonical `&'static str` bytes for the [`Self::Nil`] outer-shape —
    /// projects [`crate::ast::Sexp::Nil`] into the `got {got}` slot of every
    /// `LispError::*` Display rendering. Per-role peer of `Self::Nil` on
    /// the closed-set outer algebra.
    pub const NIL_LABEL: &'static str = "nil";

    /// Canonical `&'static str` bytes for the [`Self::Symbol`] outer-shape —
    /// projects [`crate::ast::Sexp::Atom`] `(Symbol(_))` into diagnostic
    /// rendering. Per-role peer of `Self::Symbol`.
    pub const SYMBOL_LABEL: &'static str = "symbol";

    /// Canonical `&'static str` bytes for the [`Self::Keyword`] outer-shape —
    /// projects [`crate::ast::Sexp::Atom`] `(Keyword(_))` into diagnostic
    /// rendering. Per-role peer of `Self::Keyword`; matches
    /// [`ExpectedKwargShape::KEYWORD_LABEL`] byte-for-byte — the cross-axis
    /// overlap on the same `Sexp` algebra is intentional and load-bearing,
    /// pinned by `sexp_shape_atom_carving_labels_align_with_expected_kwarg_shape_labels`.
    pub const KEYWORD_LABEL: &'static str = "keyword";

    /// Canonical `&'static str` bytes for the [`Self::String`] outer-shape —
    /// projects [`crate::ast::Sexp::Atom`] `(Str(_))` into diagnostic
    /// rendering. Per-role peer of `Self::String`; matches
    /// [`ExpectedKwargShape::STRING_LABEL`] byte-for-byte.
    pub const STRING_LABEL: &'static str = "string";

    /// Canonical `&'static str` bytes for the [`Self::Int`] outer-shape —
    /// projects [`crate::ast::Sexp::Atom`] `(Int(_))` into diagnostic
    /// rendering. Per-role peer of `Self::Int`; matches
    /// [`ExpectedKwargShape::INT_LABEL`] byte-for-byte.
    pub const INT_LABEL: &'static str = "int";

    /// Canonical `&'static str` bytes for the [`Self::Float`] outer-shape —
    /// projects [`crate::ast::Sexp::Atom`] `(Float(_))` into diagnostic
    /// rendering. Per-role peer of `Self::Float`; distinct from
    /// [`ExpectedKwargShape::NUMBER_LABEL`] (which is the wider numeric-
    /// union label emitted at `extract_float` gates).
    pub const FLOAT_LABEL: &'static str = "float";

    /// Canonical `&'static str` bytes for the [`Self::Bool`] outer-shape —
    /// projects [`crate::ast::Sexp::Atom`] `(Bool(_))` into diagnostic
    /// rendering. Per-role peer of `Self::Bool`; matches
    /// [`ExpectedKwargShape::BOOL_LABEL`] byte-for-byte.
    pub const BOOL_LABEL: &'static str = "bool";

    /// Canonical `&'static str` bytes for the [`Self::List`] outer-shape —
    /// projects [`crate::ast::Sexp::List`] into diagnostic rendering.
    /// Per-role peer of `Self::List`; matches
    /// [`ExpectedKwargShape::LIST_LABEL`] byte-for-byte.
    pub const LIST_LABEL: &'static str = "list";

    /// Canonical `&'static str` bytes for the [`Self::Quote`] outer-shape —
    /// projects [`crate::ast::Sexp::Quote`] into diagnostic rendering.
    /// Per-role peer of `Self::Quote`; matches
    /// [`crate::ast::QuoteForm::QUOTE_IAC_FORGE_TAG`] byte-for-byte — the
    /// cross-axis overlap on the shared quote-family sub-vocabulary is
    /// intentional and load-bearing, pinned by
    /// `sexp_shape_quote_carving_labels_align_with_quote_form_iac_forge_tags`.
    pub const QUOTE_LABEL: &'static str = "quote";

    /// Canonical `&'static str` bytes for the [`Self::Quasiquote`] outer-
    /// shape — projects [`crate::ast::Sexp::Quasiquote`] into diagnostic
    /// rendering. Per-role peer of `Self::Quasiquote`; matches
    /// [`crate::ast::QuoteForm::QUASIQUOTE_IAC_FORGE_TAG`] byte-for-byte.
    pub const QUASIQUOTE_LABEL: &'static str = "quasiquote";

    /// Canonical `&'static str` bytes for the [`Self::Unquote`] outer-shape
    /// — projects [`crate::ast::Sexp::Unquote`] into diagnostic rendering.
    /// Per-role peer of `Self::Unquote`; matches
    /// [`crate::ast::QuoteForm::UNQUOTE_IAC_FORGE_TAG`] byte-for-byte.
    pub const UNQUOTE_LABEL: &'static str = "unquote";

    /// Canonical `&'static str` bytes for the [`Self::UnquoteSplice`]
    /// outer-shape — projects [`crate::ast::Sexp::UnquoteSplice`] into
    /// diagnostic rendering. Per-role peer of `Self::UnquoteSplice`;
    /// DIFFERS from [`crate::ast::QuoteForm::UNQUOTE_SPLICE_IAC_FORGE_TAG`]
    /// (`"unquote-splicing"`) by design — the SexpShape diagnostic layer
    /// uses the SHORTER `"unquote-splice"` bytes across every `LispError::*`
    /// Display rendering while the iac-forge canonical-form tag uses the
    /// LONGER `"unquote-splicing"` for cross-crate byte-identical
    /// interoperability. The two-byte spelling asymmetry is the ONE
    /// intentional exception to the quote-family cross-axis label
    /// alignment; pinned by
    /// `sexp_shape_unquote_splice_label_differs_from_quote_form_iac_forge_tag`.
    pub const UNQUOTE_SPLICE_LABEL: &'static str = "unquote-splice";

    /// Closed-set forced-arity ALL array over the canonical outer-shape
    /// `&'static str` bytes, in declaration order matching [`Self::ALL`]
    /// element-wise (pinned by
    /// `sexp_shape_labels_align_with_all_by_index`). Sibling posture to
    /// [`ExpectedKwargShape::LABELS`] (`[&'static str; 7]`),
    /// [`KwargPathKind::LABELS`] (`[&'static str; 3]`),
    /// [`MacroDefHead::KEYWORDS`] (`[&'static str; 3]`),
    /// [`crate::ast::Atom::BOOL_LITERALS`] (`[&'static str; 2]`), and
    /// [`crate::ast::QuoteForm::PREFIXES`] (`[&'static str; 4]`) — every
    /// closed-set outer projection on the substrate that carries an
    /// `&'static str`-per-variant label now pins its per-role canonical
    /// bytes at ONE `pub const` per role PLUS an ALL array for
    /// family-wide consumers.
    ///
    /// Pre-lift the twelve canonical outer-shape label bytes lived inline
    /// at four sites: [`Self::label`]'s twelve match arms, plus three
    /// truth-table tests
    /// (`sexp_shape_label_renders_canonical_string_for_every_variant`,
    /// `sexp_shape_display_matches_label_for_every_variant`,
    /// `sexp_shape_label_round_trips_through_from_str`) enumerating the
    /// twelve `&'static str` literals byte-for-byte. Post-lift the
    /// per-role bytes bind at ONE `pub const` per role on the typed
    /// [`SexpShape`] algebra so every consumer routes through the typed
    /// constants — the label match arms, the truth-table tests, and every
    /// future consumer (LSP completion, `tatara-check` coverage
    /// assertion, Sekiban audit-trail metric labeled by the shape) picks
    /// up the same canonical bytes from ONE source of truth.
    ///
    /// Future consumers that compose against [`Self::LABELS`]: LSP / REPL
    /// completion surfacing every `got X` diagnostic label in a
    /// `got=` metrics query bar, a `tatara-check` coverage assertion
    /// sweeping [`Self::LABELS`] over workspace `.lisp` files' shape-
    /// rejection sites, a Sekiban audit-trail metric jointly labeled by
    /// the canonical shape (e.g.
    /// `tatara_lisp_type_mismatch_total{got="symbol"}`) whose metric-
    /// label set IS [`Self::LABELS`]. Adding a hypothetical thirteenth
    /// variant (`Vector` for `#(...)` reader syntax, `Map` for `{...}`,
    /// `Char` for `#\x`) extends [`Self::ALL`] AND [`Self::LABELS`] AND
    /// [`Self::label`]'s arm AND one new per-role `pub const` in
    /// lockstep — rustc's forced-arity check on the two `[_; N]` arrays
    /// fails compilation if EITHER ALL array grows without the other.
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the twelve
    /// canonical outer-shape label bytes bind at ONE typed `[&'static
    /// str; 12]` array on the closed-set outer [`SexpShape`] algebra
    /// rather than as twelve inline literals scattered across four
    /// substrate sites. THEORY.md §V.1 — knowable platform; the family's
    /// cardinality becomes a TYPE-level constant on the substrate
    /// algebra rather than a per-consumer hand-rolled enumeration of the
    /// twelve labels. THEORY.md §VI.1 — generation over composition; the
    /// family-wide contract sweeps (alignment with `ALL`, pairwise
    /// disjointness, membership through `label()`) emerge from the
    /// composition of TWO substrate primitives (this `pub const` array +
    /// the twelve per-role `pub const *_LABEL`s) rather than as per-
    /// variant inline assertions the current pins duplicate structurally.
    pub const LABELS: [&'static str; 12] = [
        Self::NIL_LABEL,
        Self::SYMBOL_LABEL,
        Self::KEYWORD_LABEL,
        Self::STRING_LABEL,
        Self::INT_LABEL,
        Self::FLOAT_LABEL,
        Self::BOOL_LABEL,
        Self::LIST_LABEL,
        Self::QUOTE_LABEL,
        Self::QUASIQUOTE_LABEL,
        Self::UNQUOTE_LABEL,
        Self::UNQUOTE_SPLICE_LABEL,
    ];

    /// Project the typed `SexpShape` to the canonical `&'static str`
    /// literal — feeds the `LispError::TypeMismatch` /
    /// `LispError::NamedFormNonSymbolName` Display rendering via the
    /// `#[error(...)]` annotation. The `&'static str` lifetime is
    /// load-bearing: it lets the variant project through this method into
    /// the `got {got}` slot without an allocation, parallel to how
    /// `ExpectedKwargShape::label()`, `MacroDefHead::keyword()`,
    /// `UnquoteForm::marker()`, and `CompilerSpecIoStage::operation()` /
    /// `label()` feed their respective `LispError::*` Display impls.
    ///
    /// Each arm routes through the per-role `pub const` on `impl Self`
    /// ([`Self::NIL_LABEL`], [`Self::SYMBOL_LABEL`],
    /// [`Self::KEYWORD_LABEL`], [`Self::STRING_LABEL`],
    /// [`Self::INT_LABEL`], [`Self::FLOAT_LABEL`], [`Self::BOOL_LABEL`],
    /// [`Self::LIST_LABEL`], [`Self::QUOTE_LABEL`],
    /// [`Self::QUASIQUOTE_LABEL`], [`Self::UNQUOTE_LABEL`],
    /// [`Self::UNQUOTE_SPLICE_LABEL`]) so the twelve canonical
    /// outer-shape byte-strings bind at ONE typed source of truth per
    /// role rather than as inline literals scattered across the `match`
    /// body. Sibling posture to
    /// [`ExpectedKwargShape::label`]'s post-lift arms.
    ///
    /// The bidirectional contract is anchored by tests:
    /// `sexp_shape_label_renders_canonical_string_for_every_variant` pins
    /// each variant's canonical literal so a typo in any arm fails-loudly,
    /// `sexp_shape_display_matches_label_for_every_variant` pins
    /// Display-equals-label so the `#[error(...)]` annotation's `{got}`
    /// slot projects byte-for-byte through this method, and
    /// `sexp_shape_label_round_trips_through_from_str` pins the
    /// `label` ↔ `FromStr` round-trip for every variant in
    /// [`Self::ALL`] so the typed surface and the rendered diagnostic
    /// literal cannot drift.
    #[must_use]
    pub fn label(self) -> &'static str {
        match self {
            Self::Nil => Self::NIL_LABEL,
            Self::Symbol => Self::SYMBOL_LABEL,
            Self::Keyword => Self::KEYWORD_LABEL,
            Self::String => Self::STRING_LABEL,
            Self::Int => Self::INT_LABEL,
            Self::Float => Self::FLOAT_LABEL,
            Self::Bool => Self::BOOL_LABEL,
            Self::List => Self::LIST_LABEL,
            Self::Quote => Self::QUOTE_LABEL,
            Self::Quasiquote => Self::QUASIQUOTE_LABEL,
            Self::Unquote => Self::UNQUOTE_LABEL,
            Self::UnquoteSplice => Self::UNQUOTE_SPLICE_LABEL,
        }
    }

    /// Project the twelve-variant [`SexpShape`] back to its
    /// corresponding [`crate::ast::AtomKind`] iff the shape names an
    /// atomic-payload variant — `Symbol → Some(AtomKind::Symbol)`,
    /// `Keyword → Some(AtomKind::Keyword)`, `String → Some(AtomKind::Str)`,
    /// `Int → Some(AtomKind::Int)`, `Float → Some(AtomKind::Float)`,
    /// `Bool → Some(AtomKind::Bool)`, every other shape (`Nil`,
    /// `List`, every quote-family wrapper) `None`. The 6-of-12 carving
    /// of [`SexpShape`] that the inverse [`crate::ast::AtomKind::sexp_shape`]
    /// embed projection covers — naming the inverse closes the
    /// embed/project section on the (atomic-payload, outer-shape)
    /// algebra.
    ///
    /// Composition law (round-trip on the atom carving):
    /// `AtomKind::sexp_shape(k).as_atom_kind() == Some(k)` for every
    /// `k: AtomKind`. The non-atom shapes form the kernel of the
    /// projection — `SexpShape::List.as_atom_kind() == None`,
    /// `SexpShape::Nil.as_atom_kind() == None`, every quote-family
    /// variant also `None`. The two projections together form an
    /// `Iso(AtomKind, AtomShape ⊂ SexpShape)`: `as_atom_kind` is the
    /// section (every `AtomKind` round-trips through the embed),
    /// `sexp_shape` is the retraction (every atom-shape pre-image
    /// recovers the typed marker). Disjoint with [`Self::as_quote_form`]:
    /// for every variant in [`Self::ALL`], at most ONE of the two
    /// projections returns `Some` — the typed-shape lattice's two
    /// closed-set carvings partition the carve-able SexpShape variants
    /// (every variant is in exactly one of AtomShape, QuoteShape, or
    /// neither — the latter being `Nil` and `List`).
    ///
    /// Pre-lift the docstring on [`crate::ast::AtomKind::sexp_shape`]
    /// explicitly anticipated this dual:
    ///
    /// > "the dual projection `SexpShape::as_atom_kind(self) ->
    /// > Option<AtomKind>` is NOT currently provided because no
    /// > consumer needs it ... If a future authoring tool (LSP /
    /// > REPL / `tatara-check` typed-pattern matcher) wants to lift
    /// > the typed marker out of a diagnostic-side shape identity,
    /// > the dual lands as ONE new `match` over the closed set,
    /// > parallel to the structure here."
    ///
    /// Post-lift the dual lives at this method; the `AtomKind::sexp_shape`
    /// docstring's anticipation is satisfied. Two plausible future
    /// consumers the closed-set projection admits with no new
    /// boilerplate:
    ///   * **LSP / REPL typed-shape filter** — given a
    ///     `LispError::TypeMismatch { got: SexpShape, .. }`, project
    ///     the offending shape through `as_atom_kind()`; iff `Some(k)`,
    ///     the offending value was an atomic payload and the LSP can
    ///     route through `AtomKind`'s diagnostic / completion surface
    ///     (`AtomKind::label`, `AtomKind::ALL`-driven completion list)
    ///     without re-deriving the 6-of-12 carving inline. Iff `None`,
    ///     the surface dispatches to the structural (list / quote-family /
    ///     nil) branch instead.
    ///   * **`tatara-check` typed-pattern matcher** — a future
    ///     `(check-shape-projects-to-atom-kind …)` substrate primitive
    ///     binds to this projection rather than substring-matching the
    ///     rendered label or duplicating the 6-of-12 carving on its
    ///     own.
    ///   * **Diagnostic-side audit-trail metric** — a future
    ///     `tatara_lisp_type_mismatch_atom_kind_total{kind="symbol"}`
    ///     metric reads the typed `AtomKind` directly off the rejected
    ///     `SexpShape` via this projection, with the carving's
    ///     correctness pinned at ONE site (the typed match here)
    ///     rather than across N per-metric inline `match` arms.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the
    /// (SexpShape variant, AtomKind variant) inverse pairing becomes a
    /// TYPE projection on the substrate algebra rather than an inline
    /// 6-of-12 `match` re-derived per call site. THEORY.md §II.1
    /// invariant 2 — free middle; the (atomic-payload, outer-shape)
    /// algebra now binds at TWO typed sites (`AtomKind::sexp_shape`
    /// for the embed, `SexpShape::as_atom_kind` for the project), each
    /// rebuilding the same closed-set pairing — a regression that
    /// drifts ONE direction from the other fails the
    /// `atom_kind_sexp_shape_round_trips_through_as_atom_kind` round-
    /// trip pin below. THEORY.md §VI.1 — generation over composition;
    /// the inverse pairing's ONE typed `match` displaces the speculative
    /// per-consumer 6-of-12 carving (LSP, REPL, `tatara-check`,
    /// metrics) the substrate's authoring surface roadmap anticipates.
    ///
    /// Frontier inspiration: MLIR's `mlir::dyn_cast<AtomicAttr>(attr)`
    /// — the typed soft-downcast from a generic `Attribute` to a
    /// narrower typed `AtomicAttr` interface IS the closed-set
    /// project direction; `SexpShape::as_atom_kind` is the
    /// unstructured-Rust peer on the substrate's typed-shape algebra,
    /// with [`crate::ast::AtomKind`] standing in for MLIR's
    /// `AtomicAttr` interface. Racket's `(syntax->datum stx)` paired
    /// with a closed-set predicate (`number?`, `symbol?`, `string?`,
    /// `boolean?`) — the typed predicate face IS the project direction
    /// on Racket's syntax-datum taxonomy; the substrate's
    /// `as_atom_kind` is the Rust-typed peer where the predicate
    /// surfaces the typed witness alongside the predicate verdict in
    /// ONE `Option<AtomKind>` projection.
    #[must_use]
    pub fn as_atom_kind(self) -> Option<crate::ast::AtomKind> {
        use crate::ast::AtomKind;
        match self {
            Self::Symbol => Some(AtomKind::Symbol),
            Self::Keyword => Some(AtomKind::Keyword),
            Self::String => Some(AtomKind::Str),
            Self::Int => Some(AtomKind::Int),
            Self::Float => Some(AtomKind::Float),
            Self::Bool => Some(AtomKind::Bool),
            Self::Nil
            | Self::List
            | Self::Quote
            | Self::Quasiquote
            | Self::Unquote
            | Self::UnquoteSplice => None,
        }
    }

    /// Project the twelve-variant [`SexpShape`] back to its
    /// corresponding [`crate::ast::QuoteForm`] iff the shape names a
    /// homoiconic quote-family wrapper — `Quote → Some(QuoteForm::Quote)`,
    /// `Quasiquote → Some(QuoteForm::Quasiquote)`, `Unquote →
    /// Some(QuoteForm::Unquote)`, `UnquoteSplice →
    /// Some(QuoteForm::UnquoteSplice)`, every other shape (`Nil`,
    /// `List`, every atomic-payload variant) `None`. The 4-of-12
    /// carving of [`SexpShape`] that the inverse
    /// [`crate::ast::QuoteForm::sexp_shape`] embed projection covers —
    /// naming the inverse closes the embed/project section on the
    /// (quote-family, outer-shape) algebra, sibling to
    /// [`Self::as_atom_kind`] on the atomic-payload axis.
    ///
    /// Composition law (round-trip on the quote-family carving):
    /// `QuoteForm::sexp_shape(qf).as_quote_form() == Some(qf)` for
    /// every `qf: QuoteForm`. The non-quote-family shapes form the
    /// kernel of the projection — `SexpShape::List.as_quote_form() ==
    /// None`, `SexpShape::Nil.as_quote_form() == None`, every atomic-
    /// payload variant also `None`. The two projections together form
    /// an `Iso(QuoteForm, QuoteShape ⊂ SexpShape)`: `as_quote_form`
    /// is the section (every `QuoteForm` round-trips through the
    /// embed), `sexp_shape` is the retraction (every quote-shape
    /// pre-image recovers the typed marker). Disjoint with
    /// [`Self::as_atom_kind`]: for every variant in [`Self::ALL`], at
    /// most ONE of the two projections returns `Some` — the typed-
    /// shape lattice's two closed-set carvings partition the carve-
    /// able SexpShape variants (every variant is in exactly one of
    /// AtomShape, QuoteShape, or neither — the latter being `Nil`
    /// and `List`).
    ///
    /// Pre-lift the docstring on [`crate::ast::QuoteForm::sexp_shape`]
    /// explicitly anticipated this dual:
    ///
    /// > "the dual projection `SexpShape::as_quote_form(self) ->
    /// > Option<QuoteForm>` is NOT currently provided because no
    /// > consumer needs it ... If a future authoring tool (LSP /
    /// > REPL / `tatara-check` typed-pattern matcher) wants to lift
    /// > the typed marker out of a diagnostic-side shape identity,
    /// > the dual lands as ONE new match on the closed set, parallel
    /// > to the structure here."
    ///
    /// Post-lift the dual lives at this method; the
    /// `QuoteForm::sexp_shape` docstring's anticipation is satisfied.
    /// The same plausible future consumers [`Self::as_atom_kind`]
    /// documents apply on the quote-family axis — a typed-shape
    /// filter that narrows a diagnostic to "this rejection was on a
    /// homoiconic prefix-wrapper" iff `as_quote_form().is_some()`
    /// binds to ONE projection rather than re-deriving the 4-of-12
    /// carving inline. A future `tatara-check` predicate
    /// `(check-shape-projects-to-quote-form …)` reads the typed
    /// `QuoteForm` directly off a rejected `SexpShape` via this
    /// projection.
    ///
    /// Theory anchor: same as [`Self::as_atom_kind`]. THEORY.md §V.1
    /// (knowable platform; the inverse pairing is a TYPE projection
    /// rather than an inline 4-of-12 `match`), THEORY.md §II.1
    /// invariant 2 (free middle; the embed/project pair binds at TWO
    /// typed sites — `QuoteForm::sexp_shape` for the embed,
    /// `SexpShape::as_quote_form` for the project — both rebuilding
    /// the same closed-set pairing), THEORY.md §VI.1 (generation
    /// over composition; the inverse 4-of-12 carving lifts to ONE
    /// typed `match`).
    ///
    /// Frontier inspiration: same as [`Self::as_atom_kind`] — MLIR's
    /// `mlir::dyn_cast<QuoteAttr>(attr)` typed soft-downcast on the
    /// quote-family carving of a closed-set attribute union, with
    /// Racket's `(or (quote-syntax? stx) (quasiquote-syntax? stx)
    /// (unquote-syntax? stx) (unquote-splicing-syntax? stx))` as the
    /// closed-form predicate-family sibling whose Rust-typed peer
    /// surfaces the typed witness alongside the predicate verdict in
    /// ONE `Option<QuoteForm>` projection.
    #[must_use]
    pub fn as_quote_form(self) -> Option<crate::ast::QuoteForm> {
        use crate::ast::QuoteForm;
        match self {
            Self::Quote => Some(QuoteForm::Quote),
            Self::Quasiquote => Some(QuoteForm::Quasiquote),
            Self::Unquote => Some(QuoteForm::Unquote),
            Self::UnquoteSplice => Some(QuoteForm::UnquoteSplice),
            Self::Nil
            | Self::List
            | Self::Symbol
            | Self::Keyword
            | Self::String
            | Self::Int
            | Self::Float
            | Self::Bool => None,
        }
    }

    /// Project the twelve-variant [`SexpShape`] back to its
    /// corresponding [`UnquoteForm`] iff the shape names a template-
    /// substitution wrapper — `Unquote → Some(UnquoteForm::Unquote)`,
    /// `UnquoteSplice → Some(UnquoteForm::Splice)`, every other shape
    /// (`Quote`, `Quasiquote`, `Nil`, `List`, every atomic-payload
    /// variant) `None`. The 2-of-12 carving of [`SexpShape`] that the
    /// inverse [`UnquoteForm::sexp_shape`] embed projection covers —
    /// naming the inverse closes the embed/project section on the
    /// (template-substitution subset, outer-shape) algebra, sibling of
    /// the already-closed ([`crate::ast::AtomKind::sexp_shape`],
    /// [`Self::as_atom_kind`]) dual on the 6-of-12 atomic-payload
    /// carving AND ([`crate::ast::QuoteForm::sexp_shape`],
    /// [`Self::as_quote_form`]) dual on the 4-of-12 quote-family
    /// carving.
    ///
    /// Composition law (routes through the quote-family superset):
    /// `self.as_unquote_form() == self.as_quote_form().and_then(
    /// crate::ast::QuoteForm::as_unquote_form)` for every `self:
    /// SexpShape`. The (outer shape, subset marker) pairing binds at
    /// TWO existing closed-set matches ([`Self::as_quote_form`] +
    /// [`crate::ast::QuoteForm::as_unquote_form`]) rather than at a
    /// parallel twelve-arm inline match table here — matching the
    /// posture [`UnquoteForm::sexp_shape`] takes through
    /// [`crate::ast::QuoteForm::sexp_shape`] on the embed direction.
    /// Round-trip law (retraction on the substitution-subset carving):
    /// `UnquoteForm::sexp_shape(uf).as_unquote_form() == Some(uf)` for
    /// every `uf: UnquoteForm`. The two projections together form an
    /// `Iso(UnquoteForm, UnquoteShape ⊂ SexpShape)`:
    /// [`Self::as_unquote_form`] is the section (every `UnquoteForm`
    /// round-trips through the embed), [`UnquoteForm::sexp_shape`] is
    /// the retraction (every substitution-subset shape pre-image
    /// recovers the typed marker).
    ///
    /// Disjoint with [`Self::as_atom_kind`] AND properly subsumed by
    /// [`Self::as_quote_form`]: for every variant in [`Self::ALL`], at
    /// most ONE of ([`Self::as_atom_kind`], [`Self::as_quote_form`])
    /// returns `Some` (the substrate's typed-shape lattice's two closed-
    /// set carvings partition the carve-able SexpShape variants); and
    /// [`Self::as_unquote_form`] returns `Some` iff [`Self::as_quote_form`]
    /// returns `Some(qf)` AND `qf.as_unquote_form()` returns `Some(_)`
    /// (the 2-of-4 template-substitution subset of the 4-of-12 quote-
    /// family carving). The two quote-family shapes that lie OUTSIDE
    /// the substitution subset (`Quote`, `Quasiquote`) form the kernel
    /// of this projection but NOT of [`Self::as_quote_form`] — the
    /// nested subset relationship makes the projections composable.
    ///
    /// Pre-lift the (SexpShape variant, UnquoteForm variant) pairing
    /// had NO typed projection at this closed-set boundary — a
    /// consumer with a `SexpShape` in hand (a `LispError::TypeMismatch
    /// .got` slot's outer-shape identity, a rejected shape from a
    /// typed-entry gate) wanting to narrow to "was this rejection on a
    /// template-substitution wrapper?" had to spell the two-step
    /// composition `shape.as_quote_form().and_then(QuoteForm::as_unquote_form)`
    /// inline. Post-lift the composition binds at ONE typed-algebra
    /// method on the outer [`SexpShape`] algebra, and the pair with
    /// [`UnquoteForm::sexp_shape`] closes the embed/project algebra
    /// dual on the substitution-subset carving.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the inverse
    /// 2-of-12 carving is a TYPE projection on the substrate algebra
    /// rather than an inline `.as_quote_form().and_then(...)` two-step.
    /// THEORY.md §II.1 invariant 2 — free middle; the embed/project
    /// pair binds at TWO typed sites — [`UnquoteForm::sexp_shape`] for
    /// the embed, [`Self::as_unquote_form`] for the project — both
    /// composing through the parent quote-family carving's closed
    /// pair. THEORY.md §VI.1 — generation over composition; the
    /// inverse 2-of-12 carving lifts to ONE typed projection.
    ///
    /// Frontier inspiration: MLIR's `mlir::dyn_cast<UnquoteFamilyOp>(op)`
    /// typed soft-downcast on the substitution-subset carving of a
    /// closed-set operation union — the (op, typed identity) pairing
    /// lives at ONE typed projection composed through the parent
    /// op-family's typed downcast. [`Self::as_unquote_form`] is the
    /// Rust-typed peer on the [`SexpShape`] closed set, with
    /// [`crate::ast::QuoteForm::as_unquote_form`] standing in for the
    /// parent-family-to-subset composition and this projection lifting
    /// the parent-to-parent [`Self::as_quote_form`] composition into a
    /// single typed method the consumer surface binds against directly.
    #[must_use]
    pub fn as_unquote_form(self) -> Option<UnquoteForm> {
        self.as_quote_form()
            .and_then(crate::ast::QuoteForm::as_unquote_form)
    }

    /// Project the twelve-variant [`SexpShape`] back to its corresponding
    /// [`StructuralKind`] iff the shape names a structural-residual
    /// wrapper — `Nil → Some(StructuralKind::Nil)`, `List →
    /// Some(StructuralKind::List)`, every other shape (`Symbol`,
    /// `Keyword`, `String`, `Int`, `Float`, `Bool`, `Quote`,
    /// `Quasiquote`, `Unquote`, `UnquoteSplice`) `None`. The 2-of-12
    /// carving of [`SexpShape`] that the inverse
    /// [`StructuralKind::sexp_shape`] embed projection covers — naming
    /// the inverse closes the (embed, project) algebra dual on the
    /// (structural-residual subset, outer-shape) algebra, THIRD sibling
    /// of the already-closed ([`crate::ast::AtomKind::sexp_shape`],
    /// [`Self::as_atom_kind`]) dual on the 6-of-12 atomic-payload
    /// carving AND ([`crate::ast::QuoteForm::sexp_shape`],
    /// [`Self::as_quote_form`]) dual on the 4-of-12 quote-family
    /// carving.
    ///
    /// Closes the typed-shape lattice's partition: every `SexpShape`
    /// projects through EXACTLY ONE of [`Self::as_atom_kind`],
    /// [`Self::as_quote_form`], [`Self::as_structural_kind`] as
    /// `Some(_)`, and the three carvings cover `SexpShape::ALL`
    /// disjointly (6 + 4 + 2 = 12). The partition is total AND
    /// disjoint on the outer-shape closed set — pre-lift the
    /// "residual" side of the partition lived at ONE inline
    /// `!matches!(shape, SexpShape::Nil | SexpShape::List)` assertion
    /// inside the test-module carving-disjointness pin (the runtime
    /// witness the substrate maintained by test discipline); post-lift
    /// the residual is a TYPED CARVING binding at ONE typed-algebra
    /// method, symmetric with the two already-closed carvings that own
    /// the atomic-payload and quote-family sides of the same partition.
    ///
    /// Composition law (partition-total): for every `self: SexpShape`,
    /// EXACTLY ONE of `self.as_atom_kind().is_some()`,
    /// `self.as_quote_form().is_some()`,
    /// `self.as_structural_kind().is_some()` is `true`. Round-trip law
    /// (retraction on the structural-residual subset carving):
    /// `StructuralKind::sexp_shape(sk).as_structural_kind() ==
    /// Some(sk)` for every `sk: StructuralKind`. The two projections
    /// together form an `Iso(StructuralKind, StructuralShape ⊂
    /// SexpShape)`: [`Self::as_structural_kind`] is the section (every
    /// `StructuralKind` round-trips through the embed),
    /// [`StructuralKind::sexp_shape`] is the retraction (every
    /// structural-residual shape pre-image recovers the typed marker).
    ///
    /// Disjoint with [`Self::as_atom_kind`] AND [`Self::as_quote_form`]:
    /// for every variant in [`Self::ALL`], at most ONE of the THREE
    /// projections returns `Some`. The structural-residual subset
    /// (`Nil` and `List`) is the KERNEL of both the atomic-payload and
    /// quote-family projections and is EXACTLY the IMAGE of this one —
    /// the three projections partition [`Self::ALL`] injectively.
    ///
    /// Pre-lift the (SexpShape variant, StructuralKind variant) pairing
    /// had NO typed projection at this closed-set boundary — a consumer
    /// with a `SexpShape` in hand (a `LispError::TypeMismatch.got`
    /// slot's outer-shape identity, a rejected shape from a typed-entry
    /// gate) wanting to narrow to "was this rejection on the structural
    /// residual (neither atomic nor quote-family)?" had to spell the
    /// two-step negation `shape.as_atom_kind().is_none() &&
    /// shape.as_quote_form().is_none()` OR the inline `matches!(shape,
    /// SexpShape::Nil | SexpShape::List)` at the callsite. Post-lift
    /// the composition binds at ONE typed-algebra method on the outer
    /// [`SexpShape`] algebra, and the pair with
    /// [`StructuralKind::sexp_shape`] closes the embed/project algebra
    /// dual on the structural-residual carving, completing the typed-
    /// shape lattice's third and final closed-set carving.
    ///
    /// Two plausible future consumers the closed-set projection admits
    /// with no new boilerplate:
    ///   * **`tatara-check` typed-shape filter** — a future
    ///     `(check-shape-projects-to-structural …)` substrate primitive
    ///     binds to this projection rather than re-deriving the 2-of-12
    ///     carving inline or negating the two sibling projections. A
    ///     `LispError::TypeMismatch { got: SexpShape, .. }` whose
    ///     offending shape projects through
    ///     `as_structural_kind() == Some(_)` is a rejection on the
    ///     structural residual (an empty [`crate::ast::Sexp::Nil`]
    ///     marker or a bare [`crate::ast::Sexp::List`] shape) rather
    ///     than on an atomic-payload OR quote-family wrapper.
    ///   * **LSP / REPL typed-shape completion** — a future authoring
    ///     surface offering completions filtered by carving axis binds
    ///     to `StructuralKind::ALL` for the "structural" completion
    ///     column rather than re-deriving `Nil | List` inline.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the inverse
    /// 2-of-12 residual carving is a TYPE projection on the substrate
    /// algebra rather than an inline `matches!(shape, SexpShape::Nil |
    /// SexpShape::List)` two-arm predicate. THEORY.md §II.1 invariant
    /// 2 — free middle; the embed/project pair binds at TWO typed
    /// sites — [`StructuralKind::sexp_shape`] for the embed,
    /// [`Self::as_structural_kind`] for the project — completing the
    /// third and final closed-set carving of the outer-shape algebra.
    /// THEORY.md §VI.1 — generation over composition; the residual
    /// 2-of-12 carving lifts to ONE typed projection AND makes the
    /// partition-total invariant (every `SexpShape` is in EXACTLY ONE
    /// of the three carvings) a TYPED THEOREM rather than a runtime
    /// `matches!` assertion.
    ///
    /// Frontier inspiration: MLIR's `mlir::dyn_cast<StructuralOp>(op)`
    /// typed soft-downcast on the residual carving of a closed-set
    /// operation union — the (op, typed identity) pairing lives at ONE
    /// typed projection on the outer op-family algebra, sibling of the
    /// atomic-payload and quote-family carvings' typed downcasts.
    /// [`Self::as_structural_kind`] is the Rust-typed peer on the
    /// [`SexpShape`] closed set, completing the three-carving partition
    /// the substrate's typed-shape lattice carries. Racket's
    /// `(or (null? datum) (pair? datum))` closed-form predicate on the
    /// (nil-or-list) residual whose Rust-typed peer surfaces the typed
    /// witness alongside the predicate verdict in ONE
    /// `Option<StructuralKind>` projection.
    #[must_use]
    pub fn as_structural_kind(self) -> Option<StructuralKind> {
        match self {
            Self::Nil => Some(StructuralKind::Nil),
            Self::List => Some(StructuralKind::List),
            Self::Symbol
            | Self::Keyword
            | Self::String
            | Self::Int
            | Self::Float
            | Self::Bool
            | Self::Quote
            | Self::Quasiquote
            | Self::Unquote
            | Self::UnquoteSplice => None,
        }
    }

    /// Project the twelve-variant [`SexpShape`] into the canonical
    /// iac-forge interop tag string iff the shape names a homoiconic
    /// quote-family wrapper — `Quote → Some("quote")`, `Quasiquote →
    /// Some("quasiquote")`, `Unquote → Some("unquote")`, `UnquoteSplice
    /// → Some("unquote-splicing")`, every other shape (`Nil`, `List`,
    /// every atomic-payload variant) `None`. The 4-of-12 partial
    /// projection on the closed-set [`SexpShape`] algebra that surfaces
    /// [`crate::ast::QuoteForm::iac_forge_tag`]'s cross-crate canonical-
    /// form tag surface at the outer-shape algebra level.
    ///
    /// Composition law: `self.iac_forge_tag() ==
    /// self.as_quote_form().map(crate::ast::QuoteForm::iac_forge_tag)`
    /// for every `self: SexpShape` — the (outer shape, canonical iac-
    /// forge tag) pairing binds through the pre-existing quote-family
    /// carving ([`Self::as_quote_form`]) composed with the closed-set
    /// tag projection ([`crate::ast::QuoteForm::iac_forge_tag`]) rather
    /// than at a parallel four-arm inline match table here — matching
    /// the posture [`Self::as_unquote_form`] takes through
    /// [`crate::ast::QuoteForm::as_unquote_form`] on the 2-of-4
    /// template-substitution subset carving. `None` on every non-quote-
    /// family shape (six atomic-payload variants + `Nil` + `List`) — the
    /// eight-shape kernel of the projection matches the kernel of
    /// [`Self::as_quote_form`] exactly.
    ///
    /// The SIXTH consumer of the outer-shape algebra's shape-level
    /// projection surface, sibling of [`Self::label`] (operator-facing
    /// diagnostic-label surface, all twelve arms), [`Self::hash_discriminator`]
    /// (outer-`Sexp` cache-key discriminator byte, all twelve arms
    /// → `{0..=6}`), [`Self::as_atom_kind`] (6-of-12 atomic-payload
    /// carving), [`Self::as_quote_form`] (4-of-12 quote-family carving),
    /// [`Self::as_structural_kind`] (2-of-12 structural-residual
    /// carving), and [`Self::as_unquote_form`] (2-of-12 template-
    /// substitution subset carving composed through the parent quote-
    /// family carving). Post-lift the outer-shape algebra closes over
    /// seven typed projection surfaces, each rebuilt from the SAME
    /// closed twelve-arm set — a regression that drifts ONE projection
    /// against the algebra's shape-identity fails-loudly at rustc's
    /// exhaustiveness rather than silently at runtime.
    ///
    /// Pre-lift the (SexpShape variant, canonical iac-forge tag) pairing
    /// had no typed projection at the outer-shape algebra level — a
    /// consumer with a `SexpShape` in hand (a `LispError::TypeMismatch
    /// .got` slot's outer-shape identity, a rejected shape from a
    /// typed-entry gate, an LSP / REPL / audit-trail metric keyed on the
    /// observed outer shape) wanting the cross-crate iac-forge canonical
    /// tag had to re-embed the shape into a quote-family typed marker
    /// via [`Self::as_quote_form`] then compose through
    /// [`crate::ast::QuoteForm::iac_forge_tag`] inline. Post-lift the
    /// composition binds at ONE method on the outer [`SexpShape`]
    /// algebra — the (outer shape, canonical iac-forge tag) pairing lives
    /// at ONE typed projection matching the shape-level algebra sweep
    /// the six sibling projections established.
    ///
    /// The `Option<&'static str>` return shape is the natural typed peer
    /// of [`crate::ast::QuoteForm::iac_forge_tag`]'s total `&'static str`
    /// return: the quote-family superset TOTALS on the four-arm closed
    /// set, and the outer twelve-arm closed set's projection PARTIALIZES
    /// on the eight non-quote-family shapes. Same shape as
    /// [`Self::as_atom_kind`] / [`Self::as_quote_form`] /
    /// [`Self::as_structural_kind`] / [`Self::as_unquote_form`] — each
    /// carving lifts a total sub-algebra projection to a partial outer-
    /// shape projection with `None` on the residual arms, so a consumer
    /// keying on "iff this outer shape has a canonical iac-forge tag"
    /// binds against the closed set's typed image directly rather than
    /// substring-matching the shape label.
    ///
    /// The `&'static str` lifetime is load-bearing: every iac-forge
    /// consumer projects through this method into the canonical
    /// 2-element-list head without an allocation, parallel to how
    /// [`crate::ast::QuoteForm::iac_forge_tag`] on the sub-carving,
    /// [`Self::label`] on the outer-shape diagnostic surface,
    /// [`crate::ast::QuoteForm::prefix`] on the Display / reader
    /// prefix surface, and [`UnquoteForm::marker`] on the template
    /// marker axis project their respective closed sets. A future
    /// homoiconic prefix-wrapper (e.g. hypothetical `,~` reverse-
    /// unquote) extends [`crate::ast::QuoteForm`] AND [`Self`]'s
    /// closed set together — rustc binds the iac-forge canonical-form
    /// surface to the extended algebra at ONE arm each through
    /// exhaustiveness, with the composition through [`Self::as_quote_form`]
    /// pulling the new variant's tag into this projection mechanically.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the
    /// (SexpShape variant, canonical iac-forge tag) pairing becomes a
    /// TYPE projection on the outer-shape algebra rather than an inline
    /// `.as_quote_form().map(...)` two-step at every consumer. A typo
    /// or swap at the projection site is no longer a runtime tag drift
    /// but a compile error against the typed composition — the
    /// `SexpShape` ↔ `QuoteForm` ↔ tag string chain is rustc-enforced
    /// end-to-end. THEORY.md §II.1 invariant 2 — free middle; the
    /// (outer shape, canonical iac-forge tag) pairing now binds at ONE
    /// site on the outer-shape algebra, composing through the pre-
    /// existing four-arm sub-carving's tag projection rather than
    /// duplicating the four-arm match here. THEORY.md §VI.1 —
    /// generation over composition; the outer-shape algebra's typed
    /// projection surface closes over SEVEN methods (label,
    /// hash_discriminator, four carvings, iac_forge_tag) each keyed on
    /// the SAME closed twelve-arm set.
    ///
    /// Frontier inspiration: MLIR's `mlir::TypeSwitch<T>` typed
    /// pattern-match combinator on a closed union — narrowing to a
    /// specific typed case yields the typed downcast + operations on
    /// that case in ONE typed step. [`Self::iac_forge_tag`] is the
    /// Rust-typed peer where the "narrow to quote-family" step
    /// ([`Self::as_quote_form`]) composes with the "read the case's
    /// canonical tag" step ([`crate::ast::QuoteForm::iac_forge_tag`])
    /// into ONE outer-shape projection. Racket's `(match shape
    /// [(? quote-shape? qs) (quote-shape->iac-forge-tag qs)] [_ #f])`
    /// closed-form match on the shape-taxonomy union — the outer
    /// pattern's partial projection to the canonical form IS the shape
    /// this method lifts to a typed Rust closed-set match.
    #[must_use]
    pub fn iac_forge_tag(self) -> Option<&'static str> {
        self.as_quote_form()
            .map(crate::ast::QuoteForm::iac_forge_tag)
    }

    /// Project the twelve-variant [`SexpShape`] into the canonical
    /// reader-punctuation prefix string iff the shape names a homoiconic
    /// quote-family wrapper — `Quote → Some("'")`, `Quasiquote →
    /// Some("`")`, `Unquote → Some(",")`, `UnquoteSplice → Some(",@")`,
    /// every other shape (`Nil`, `List`, every atomic-payload variant)
    /// `None`. The 4-of-12 partial projection on the closed-set
    /// [`SexpShape`] algebra that surfaces
    /// [`crate::ast::QuoteForm::prefix`]'s reader-punctuation vocabulary
    /// at the outer-shape algebra level.
    ///
    /// Composition law: `self.prefix() ==
    /// self.as_quote_form().map(crate::ast::QuoteForm::prefix)` for every
    /// `self: SexpShape` — the (outer shape, reader-punctuation prefix)
    /// pairing binds through the pre-existing quote-family carving
    /// ([`Self::as_quote_form`]) composed with the closed-set prefix
    /// projection ([`crate::ast::QuoteForm::prefix`]) rather than at a
    /// parallel four-arm inline match table here — matching the posture
    /// [`Self::iac_forge_tag`] takes through
    /// [`crate::ast::QuoteForm::iac_forge_tag`] on the cross-crate
    /// canonical-form tag axis and [`Self::as_unquote_form`] takes
    /// through [`crate::ast::QuoteForm::as_unquote_form`] on the 2-of-4
    /// template-substitution subset carving. `None` on every non-quote-
    /// family shape (six atomic-payload variants + `Nil` + `List`) — the
    /// eight-shape kernel of the projection matches the kernel of
    /// [`Self::as_quote_form`] AND [`Self::iac_forge_tag`] byte-for-byte.
    ///
    /// The EIGHTH consumer of the outer-shape algebra's shape-level
    /// projection surface, sibling of [`Self::label`] (operator-facing
    /// diagnostic-label surface, all twelve arms),
    /// [`Self::hash_discriminator`] (outer-`Sexp` cache-key discriminator
    /// byte, all twelve arms → `{0..=6}`), [`Self::as_atom_kind`]
    /// (6-of-12 atomic-payload carving), [`Self::as_quote_form`]
    /// (4-of-12 quote-family carving), [`Self::as_structural_kind`]
    /// (2-of-12 structural-residual carving), [`Self::as_unquote_form`]
    /// (2-of-12 template-substitution subset carving composed through
    /// the parent quote-family carving), and [`Self::iac_forge_tag`]
    /// (4-of-12 cross-crate canonical-form tag projection). Post-lift
    /// the outer-shape algebra closes over EIGHT typed projection
    /// surfaces, each rebuilt from the SAME closed twelve-arm set — a
    /// regression that drifts ONE projection against the algebra's
    /// shape-identity fails-loudly at rustc's exhaustiveness rather than
    /// silently at runtime.
    ///
    /// Pre-lift the (SexpShape variant, reader-punctuation prefix)
    /// pairing had no typed projection at the outer-shape algebra level
    /// — a consumer with a [`SexpShape`] in hand (a
    /// [`LispError::TypeMismatch`]'s `got` slot's outer-shape identity,
    /// a rejected shape from a typed-entry gate, an LSP hover / REPL
    /// completion / audit-trail metric keyed on the observed outer
    /// shape) wanting the reader's canonical homoiconic prefix character
    /// had to re-embed the shape into a quote-family typed marker via
    /// [`Self::as_quote_form`] then compose through
    /// [`crate::ast::QuoteForm::prefix`] inline. Post-lift the
    /// composition binds at ONE method on the outer [`SexpShape`]
    /// algebra — the (outer shape, reader-punctuation prefix) pairing
    /// lives at ONE typed projection matching the shape-level algebra
    /// sweep the seven sibling projections established.
    ///
    /// The `Option<&'static str>` return shape is the natural typed peer
    /// of [`crate::ast::QuoteForm::prefix`]'s total `&'static str`
    /// return: the quote-family superset TOTALS on the four-arm closed
    /// set, and the outer twelve-arm closed set's projection PARTIALIZES
    /// on the eight non-quote-family shapes. Same shape as
    /// [`Self::as_atom_kind`] / [`Self::as_quote_form`] /
    /// [`Self::as_structural_kind`] / [`Self::as_unquote_form`] /
    /// [`Self::iac_forge_tag`] — each carving lifts a total sub-algebra
    /// projection to a partial outer-shape projection with `None` on
    /// the residual arms, so a consumer keying on "iff this outer shape
    /// has a canonical reader-punctuation prefix" binds against the
    /// closed set's typed image directly rather than substring-matching
    /// the shape label.
    ///
    /// The reader-punctuation vocabulary this method projects (`"'"` /
    /// `` "`" `` / `","` / `",@"`) is INTENTIONALLY DISJOINT from the
    /// two sibling `&'static str` projection axes:
    ///
    /// * [`Self::iac_forge_tag`] — cross-crate canonical form
    ///   (`"quote"` / `"quasiquote"` / `"unquote"` /
    ///   `"unquote-splicing"`), BLAKE3 attestation keys, render-cache
    ///   shape (load-bearing for byte-identical inter-crate compatibility
    ///   with the iac-forge ecosystem).
    /// * [`Self::label`] — operator-facing diagnostic label (`"quote"` /
    ///   `"quasiquote"` / `"unquote"` / `"unquote-splice"`),
    ///   [`LispError::TypeMismatch`]'s `got` rendering, REPL / LSP
    ///   shape-of-witness surface.
    ///
    /// This method projects the reader's SOURCE-TEXT vocabulary — the
    /// four punctuation characters that appear literally in Lisp source
    /// at each variant's homoiconic prefix. The three closed-set
    /// projections key the SAME twelve-arm shape algebra on THREE
    /// distinct `&'static str` vocabularies (source-punctuation,
    /// diagnostic-label, cross-crate canonical-form); consolidating any
    /// two would silently break either the reader round-trip, the
    /// operator-facing diagnostic surface, OR the iac-forge attestation
    /// pipeline. The three vocabularies' distinctness is pinned bit-for-
    /// bit through the composition law across the closed-set typed
    /// algebra.
    ///
    /// The `&'static str` lifetime is load-bearing: every reader / LSP
    /// / REPL / diagnostic consumer projects through this method into
    /// the canonical prefix character without an allocation, parallel to
    /// how [`crate::ast::QuoteForm::prefix`] on the sub-carving,
    /// [`Self::iac_forge_tag`] on the cross-crate canonical-form axis,
    /// [`Self::label`] on the outer-shape diagnostic surface, and
    /// [`UnquoteForm::marker`] on the template marker axis project their
    /// respective closed sets. A future homoiconic prefix-wrapper (e.g.
    /// hypothetical `,~` reverse-unquote) extends
    /// [`crate::ast::QuoteForm`] AND [`Self`]'s closed set together —
    /// rustc binds the reader-punctuation surface to the extended
    /// algebra at ONE arm each through exhaustiveness, with the
    /// composition through [`Self::as_quote_form`] pulling the new
    /// variant's prefix into this projection mechanically.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the
    /// (SexpShape variant, reader-punctuation prefix) pairing becomes a
    /// TYPE projection on the outer-shape algebra rather than an inline
    /// `.as_quote_form().map(...)` two-step at every consumer. A typo
    /// or swap at the projection site is no longer a runtime prefix
    /// drift but a compile error against the typed composition — the
    /// `SexpShape` ↔ `QuoteForm` ↔ prefix character chain is
    /// rustc-enforced end-to-end. THEORY.md §II.1 invariant 2 — free
    /// middle; the (outer shape, reader-punctuation prefix) pairing now
    /// binds at ONE site on the outer-shape algebra, composing through
    /// the pre-existing four-arm sub-carving's prefix projection rather
    /// than duplicating the four-arm match here. THEORY.md §VI.1 —
    /// generation over composition; the outer-shape algebra's typed
    /// projection surface closes over EIGHT methods (label,
    /// hash_discriminator, four carvings, iac_forge_tag, prefix) each
    /// keyed on the SAME closed twelve-arm set.
    ///
    /// Frontier inspiration: MLIR's `mlir::TypeSwitch<T>` typed
    /// pattern-match combinator on a closed union — narrowing to a
    /// specific typed case yields the typed downcast + operations on
    /// that case in ONE typed step. [`Self::prefix`] is the Rust-typed
    /// peer where the "narrow to quote-family" step
    /// ([`Self::as_quote_form`]) composes with the "read the case's
    /// reader-punctuation prefix" step
    /// ([`crate::ast::QuoteForm::prefix`]) into ONE outer-shape
    /// projection. Racket's `(match shape [(? quote-shape? qs)
    /// (quote-shape->reader-prefix qs)] [_ #f])` closed-form match on
    /// the shape-taxonomy union — the outer pattern's partial projection
    /// to the source-punctuation form IS the shape this method lifts to
    /// a typed Rust closed-set match.
    #[must_use]
    pub fn prefix(self) -> Option<&'static str> {
        self.as_quote_form().map(crate::ast::QuoteForm::prefix)
    }

    /// Project the typed [`SexpShape`] into the outer-`Sexp`
    /// [`Hash for Sexp`](crate::ast::Sexp) cache-key discriminator byte
    /// `{0..=6}` — the SHAPE-LEVEL peer of
    /// [`crate::ast::Sexp::hash_discriminator`] one algebra level up.
    /// The twelve outer-shape arms collapse to seven outer bytes: the six
    /// atomic-payload arms (`Symbol`, `Keyword`, `String`, `Int`, `Float`,
    /// `Bool`) all project to the outer Atom marker byte `1u8` (their
    /// per-atom-kind inner byte lives nested inside
    /// [`Hash for Atom`](crate::ast::Atom) via
    /// [`crate::ast::AtomKind::hash_discriminator`]'s `{0..=5}` payload
    /// carving, NOT surfaced here); the two structural-residual arms
    /// (`Nil`, `List`) delegate through
    /// [`StructuralKind::hash_discriminator`] for `{0, 2}`; the four
    /// quote-family arms (`Quote`, `Quasiquote`, `Unquote`,
    /// `UnquoteSplice`) delegate through
    /// [`crate::ast::QuoteForm::hash_discriminator`] for `{3..=6}`. The
    /// byte partition is byte-identical to
    /// [`crate::ast::Sexp::hash_discriminator`]'s outer sweep, so the
    /// substrate's macro-expansion cache
    /// ([`crate::macro_expand::Expander`]'s cache) key stays bit-for-bit
    /// stable across the shape-level lift.
    ///
    /// Composition law: `sexp.hash_discriminator() ==
    /// sexp.shape().hash_discriminator()` for every `sexp: &Sexp` — the
    /// outer-`Sexp` cache-key discriminator method routes through
    /// [`crate::ast::Sexp::shape`] into THIS method, which in turn
    /// routes into the three closed-set carvings' discriminator
    /// methods. Post-lift the outer-`Sexp` cache-key algebra closes at
    /// FIVE typed layers:
    ///   1. [`crate::ast::Sexp::hash_discriminator`] — 7-arm outer
    ///      dispatch on the outer `Sexp` algebra;
    ///   2. [`Self::hash_discriminator`] — 12-arm shape-level dispatch on
    ///      the [`SexpShape`] algebra (this method);
    ///   3. [`StructuralKind::hash_discriminator`] — 2-arm
    ///      structural-residual sub-carving for `{0, 2}`;
    ///   4. [`crate::ast::QuoteForm::hash_discriminator`] — 4-arm
    ///      quote-family sub-carving for `{3..=6}`;
    ///   5. [`crate::ast::AtomKind::hash_discriminator`] — 6-arm
    ///      atomic-payload sub-carving for `{0..=5}` (nested inside
    ///      `Hash for Atom` under outer byte `1u8`, NOT surfaced through
    ///      this shape-level method).
    ///
    /// Pre-lift the outer-`Sexp` cache-key algebra bottomed out at the
    /// three sub-carvings' discriminator methods directly via
    /// [`crate::ast::Sexp::hash_discriminator`]'s seven arms — no
    /// intermediate shape-level projection existed. Consumers that had a
    /// typed [`SexpShape`] identity in hand (a
    /// `LispError::TypeMismatch.got` slot, a rejected shape from a
    /// typed-entry gate, a future authoring-tool audit-trail metric keyed
    /// on the observed shape) wanting the outer cache-key byte had to
    /// re-embed the typed shape into a [`crate::ast::Sexp`] value and
    /// route through the outer method — an unnecessary allocation. Post-
    /// lift the shape-level projection is a NAMED PRIMITIVE on the closed-
    /// set [`SexpShape`] algebra sitting next to the three sibling shape-
    /// level projections ([`Self::label`], [`Self::as_atom_kind`],
    /// [`Self::as_quote_form`], [`Self::as_structural_kind`],
    /// [`Self::as_unquote_form`]) — the outer cache-key partition
    /// becomes a typed identity on the shape algebra rather than a
    /// projection through the outer-`Sexp` value carrier.
    ///
    /// `pub(crate)` because the byte-discriminator surface is an
    /// implementation detail of the substrate's `Hash for Sexp` cache-
    /// key contract; exposing it publicly would leak the cache-key shape
    /// through the API without enabling any external consumer the public
    /// projections ([`Self::label`], [`Self::as_atom_kind`],
    /// [`Self::as_quote_form`], [`Self::as_structural_kind`]) don't
    /// already serve. Same posture as
    /// [`crate::ast::Sexp::hash_discriminator`],
    /// [`crate::ast::AtomKind::hash_discriminator`],
    /// [`crate::ast::QuoteForm::hash_discriminator`], and
    /// [`StructuralKind::hash_discriminator`].
    ///
    /// A future thirteenth [`SexpShape`] variant (e.g. `Vector` for
    /// `#(...)` reader syntax, `Map` for `{...}`, `Char` for `#\x`)
    /// picks a fresh cache-key byte outside `{0..=6}` (e.g. `7u8`),
    /// extends either [`StructuralKind`] / [`crate::ast::AtomKind`] /
    /// [`crate::ast::QuoteForm`] (if it names an existing sub-carving)
    /// or a fresh sub-algebra, and lands at ONE new arm here — rustc
    /// binds the consistency through exhaustiveness over the closed
    /// [`SexpShape`] enum.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the
    /// (SexpShape variant, outer cache-key byte) pairing becomes a TYPE
    /// projection on the substrate's shape algebra rather than requiring
    /// a re-embed into [`crate::ast::Sexp`] followed by an outer
    /// dispatch. A typo or swap at the shape-level projection site is
    /// a compile error against the typed projection rather than a
    /// silent runtime cache-key drift. THEORY.md §II.1 invariant 2 —
    /// free middle; the outer-`Sexp` cache-key algebra now closes over
    /// FIVE typed layers (outer, shape, three sub-carvings) with rustc-
    /// enforced consistency across each — a regression that drifts ONE
    /// layer's discriminator bytes from the others cannot reach the
    /// substrate's runtime cache. THEORY.md §VI.1 — generation over
    /// composition; the shape-level projection is the missing algebra
    /// layer between the outer-`Sexp` and the three sub-carvings — the
    /// four pre-existing typed layers become a full FIVE-layer typed
    /// composition through ONE new named projection.
    #[must_use]
    pub(crate) fn hash_discriminator(self) -> u8 {
        match self {
            Self::Nil => StructuralKind::Nil.hash_discriminator(),
            Self::List => StructuralKind::List.hash_discriminator(),
            Self::Symbol | Self::Keyword | Self::String | Self::Int | Self::Float | Self::Bool => {
                crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR
            }
            Self::Quote => crate::ast::QuoteForm::Quote.hash_discriminator(),
            Self::Quasiquote => crate::ast::QuoteForm::Quasiquote.hash_discriminator(),
            Self::Unquote => crate::ast::QuoteForm::Unquote.hash_discriminator(),
            Self::UnquoteSplice => crate::ast::QuoteForm::UnquoteSplice.hash_discriminator(),
        }
    }

    /// Canonical `u8` outer-`Sexp` cache-key byte for the [`Self::Nil`]
    /// outer shape — aliases [`StructuralKind::NIL_HASH_DISCRIMINATOR`]
    /// on the StructuralKind ⊂ SexpShape carving so the marker-level
    /// byte binds at ONE `pub(crate) const` on the SUB-CARVING's
    /// per-role primitive rather than at TWO sites (the sub-carving's
    /// per-role byte AND a parallel outer-shape inline literal). The
    /// canonical source of the byte lives on the sub-carving; this
    /// outer-shape peer alias projects it into the twelve-arm
    /// [`SexpShape`] algebra at zero-drift cost.
    ///
    /// Sibling posture to the twelve peer per-role `*_LABEL` aliases
    /// on [`Self`] — the `Nil` outer-shape per-role LABEL is canonical
    /// on [`Self`] and is aliased INTO [`StructuralKind::NIL_LABEL`];
    /// this per-role HASH_DISCRIMINATOR alias runs in the OPPOSITE
    /// direction because the outer-`Sexp` cache-key byte's canonical
    /// source is the sub-carving (which the outer `Sexp` dispatch
    /// composes through). The load-bearing invariant across the two
    /// axes is byte-identity: the outer-shape peer alias equals the
    /// sub-carving's canonical byte at rustc-time through the
    /// `const` initializer.
    pub(crate) const NIL_HASH_DISCRIMINATOR: u8 = StructuralKind::NIL_HASH_DISCRIMINATOR;

    /// Canonical `u8` outer-`Sexp` cache-key byte for the [`Self::Symbol`]
    /// outer shape — aliases [`crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR`]
    /// on the AtomKind ⊂ SexpShape carving. Every atomic-payload outer
    /// shape shares this outer marker byte because the per-atom-kind
    /// specialisation lives at the NESTED INNER
    /// [`crate::ast::AtomKind::HASH_DISCRIMINATORS`] `{0..=5}` carve
    /// inside `Hash for Atom`, NOT surfaced through this outer shape-
    /// level projection.
    pub(crate) const SYMBOL_HASH_DISCRIMINATOR: u8 = crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR;

    /// Canonical `u8` outer-`Sexp` cache-key byte for the [`Self::Keyword`]
    /// outer shape — aliases [`crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR`]
    /// on the AtomKind ⊂ SexpShape carving. Six-way collapse peer of
    /// [`Self::SYMBOL_HASH_DISCRIMINATOR`].
    pub(crate) const KEYWORD_HASH_DISCRIMINATOR: u8 =
        crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR;

    /// Canonical `u8` outer-`Sexp` cache-key byte for the [`Self::String`]
    /// outer shape — aliases [`crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR`].
    /// Six-way collapse peer.
    pub(crate) const STRING_HASH_DISCRIMINATOR: u8 = crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR;

    /// Canonical `u8` outer-`Sexp` cache-key byte for the [`Self::Int`]
    /// outer shape — aliases [`crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR`].
    /// Six-way collapse peer.
    pub(crate) const INT_HASH_DISCRIMINATOR: u8 = crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR;

    /// Canonical `u8` outer-`Sexp` cache-key byte for the [`Self::Float`]
    /// outer shape — aliases [`crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR`].
    /// Six-way collapse peer.
    pub(crate) const FLOAT_HASH_DISCRIMINATOR: u8 = crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR;

    /// Canonical `u8` outer-`Sexp` cache-key byte for the [`Self::Bool`]
    /// outer shape — aliases [`crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR`].
    /// Six-way collapse peer of the atomic-outer sextet.
    pub(crate) const BOOL_HASH_DISCRIMINATOR: u8 = crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR;

    /// Canonical `u8` outer-`Sexp` cache-key byte for the [`Self::List`]
    /// outer shape — aliases [`StructuralKind::LIST_HASH_DISCRIMINATOR`]
    /// on the StructuralKind ⊂ SexpShape carving. Structural-residual
    /// peer of [`Self::NIL_HASH_DISCRIMINATOR`]; the gap at `1u8`
    /// between the two structural-residual bytes reserves the outer
    /// atomic-carve byte the six-way atomic-outer sextet collapses to.
    pub(crate) const LIST_HASH_DISCRIMINATOR: u8 = StructuralKind::LIST_HASH_DISCRIMINATOR;

    /// Canonical `u8` outer-`Sexp` cache-key byte for the [`Self::Quote`]
    /// outer shape — aliases [`crate::ast::QuoteForm::QUOTE_HASH_DISCRIMINATOR`]
    /// on the QuoteForm ⊂ SexpShape carving.
    pub(crate) const QUOTE_HASH_DISCRIMINATOR: u8 = crate::ast::QuoteForm::QUOTE_HASH_DISCRIMINATOR;

    /// Canonical `u8` outer-`Sexp` cache-key byte for the
    /// [`Self::Quasiquote`] outer shape — aliases
    /// [`crate::ast::QuoteForm::QUASIQUOTE_HASH_DISCRIMINATOR`].
    pub(crate) const QUASIQUOTE_HASH_DISCRIMINATOR: u8 =
        crate::ast::QuoteForm::QUASIQUOTE_HASH_DISCRIMINATOR;

    /// Canonical `u8` outer-`Sexp` cache-key byte for the [`Self::Unquote`]
    /// outer shape — aliases [`crate::ast::QuoteForm::UNQUOTE_HASH_DISCRIMINATOR`].
    pub(crate) const UNQUOTE_HASH_DISCRIMINATOR: u8 =
        crate::ast::QuoteForm::UNQUOTE_HASH_DISCRIMINATOR;

    /// Canonical `u8` outer-`Sexp` cache-key byte for the
    /// [`Self::UnquoteSplice`] outer shape — aliases
    /// [`crate::ast::QuoteForm::UNQUOTE_SPLICE_HASH_DISCRIMINATOR`].
    pub(crate) const UNQUOTE_SPLICE_HASH_DISCRIMINATOR: u8 =
        crate::ast::QuoteForm::UNQUOTE_SPLICE_HASH_DISCRIMINATOR;

    /// Closed-set forced-arity ALL array over the canonical outer-`Sexp`
    /// cache-key `u8` bytes, in declaration order matching [`Self::ALL`]
    /// element-wise (pinned by
    /// `sexp_shape_hash_discriminators_align_with_all_by_index`).
    /// Sibling posture to [`Self::LABELS`] (`[&'static str; 12]` — the
    /// diagnostic-label axis on the same twelve-variant closed set) AND
    /// to the sub-carvings' HASH_DISCRIMINATORS peers:
    /// [`StructuralKind::HASH_DISCRIMINATORS`] (`[u8; 2]` — `{0, 2}`),
    /// [`crate::ast::QuoteForm::HASH_DISCRIMINATORS`] (`[u8; 4]` — `{3..=6}`),
    /// [`crate::ast::AtomKind::HASH_DISCRIMINATORS`] (`[u8; 6]` — the
    /// NESTED INNER `{0..=5}` bytes inside `Hash for Atom` under the
    /// outer `1u8` marker), and [`crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR`]
    /// (scalar `1u8` — the six-way outer-collapse byte). This lift joins
    /// the outer-shape closed set to the family-wide ALL-array posture
    /// every sibling closed set already carries, closing the SIXTH
    /// per-family axis on the [`SexpShape`] algebra (ALL, LABELS,
    /// as_atom_kind, as_quote_form, as_structural_kind, plus this).
    ///
    /// Pre-lift the twelve outer-shape cache-key bytes had NO family-wide
    /// forced-arity primitive on the outer-shape algebra — a consumer
    /// wanting to sweep the outer partition through a `zip(SexpShape::ALL,
    /// bytes)` had to compose the twelve bytes inline by dispatching
    /// through [`Self::hash_discriminator`] at runtime OR by re-deriving
    /// the twelve-arm collapse against the three sub-carvings'
    /// HASH_DISCRIMINATORS arrays + the atomic outer-marker byte at every
    /// call site. Post-lift the twelve bytes bind at ONE typed `[u8; 12]`
    /// primitive on the outer-shape algebra composed from the sub-
    /// carvings' canonical bytes — a future LSP / REPL completion bar
    /// keyed on the shape's cache-key byte, a `tatara-check` coverage
    /// sweep over the outer partition, or a Sekiban audit-trail metric
    /// jointly labeled by the outer-shape byte picks up the same
    /// canonical bytes from ONE source of truth.
    ///
    /// Composition law (pinned by
    /// `sexp_shape_hash_discriminators_align_with_hash_discriminator_by_index`):
    /// for every `i in 0..12`, `Self::HASH_DISCRIMINATORS[i] ==
    /// Self::ALL[i].hash_discriminator()`. Sibling to the peer alignment
    /// pins on the three sub-carvings' HASH_DISCRIMINATORS arrays — this
    /// pin closes the family-wide alignment at the OUTER twelve-arm
    /// algebra so a regression that reorders ONE array without reordering
    /// the other silently misaligns every `zip(ALL, HASH_DISCRIMINATORS)`
    /// consumer.
    ///
    /// Partition closure (pinned by
    /// `sexp_shape_hash_discriminators_cover_outer_partition_zero_through_six`):
    /// the twelve bytes collect to exactly `{0..=6}` as a set — the
    /// same outer-partition space [`Self::hash_discriminator`] surjects
    /// onto. Sibling to the pre-existing
    /// `sexp_shape_hash_discriminator_covers_outer_partition_zero_through_six`
    /// projection-driven pin — that pin closes the partition through
    /// the projection method; this pin closes it at the array level so
    /// a regression that drifts the array's contents without changing
    /// the method surfaces here.
    ///
    /// The `#[allow(dead_code)]` posture matches
    /// [`StructuralKind::HASH_DISCRIMINATORS`] /
    /// [`crate::ast::QuoteForm::HASH_DISCRIMINATORS`] /
    /// [`crate::ast::AtomKind::HASH_DISCRIMINATORS`]: the substrate's
    /// current [`Self::hash_discriminator`] body dispatches through the
    /// twelve-arm per-role per-variant match rather than through an
    /// [`Self::HASH_DISCRIMINATORS`] index lookup (patterns cannot be
    /// array-indexing expressions in the current const-fn grammar); the
    /// lift lands the substrate primitive so future consumers keyed on
    /// the whole outer-shape cache-key algebra (a future `tatara-check`
    /// predicate `(check-outer-shape-partition-injective …)`; a future
    /// `TypedRewriter<ShapeOp>` sweep zipping ALL / LABELS /
    /// HASH_DISCRIMINATORS in lockstep) pick it up through ONE typed
    /// primitive.
    ///
    /// A hypothetical thirteenth [`SexpShape`] variant (`Vector` for
    /// `#(...)`, `Map` for `{...}`, `Char` for `#\x`) extends [`Self::ALL`]
    /// AND [`Self::LABELS`] AND [`Self::HASH_DISCRIMINATORS`] AND adds
    /// ONE new per-role `pub(crate) const *_HASH_DISCRIMINATOR` alias in
    /// lockstep — rustc's forced-arity check on the three `[_; N]`
    /// arrays fails compilation if ONE array grows without the others,
    /// closing the extensibility gap the pre-lift outer-shape algebra
    /// silently allowed at the [`Self::hash_discriminator`] match body.
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the twelve
    /// canonical outer-shape cache-key bytes bind at ONE typed
    /// `[u8; 12]` array on the closed-set outer [`SexpShape`] algebra
    /// rather than at zero-primitive-plus-runtime-dispatch through the
    /// three sub-carvings' twelve-arm collapse. THEORY.md §V.1 —
    /// knowable platform; the family's cardinality becomes a
    /// TYPE-level constant on the substrate algebra rather than a
    /// per-consumer runtime dispatch through the match table. THEORY.md
    /// §V.3 — three-pillar attestation; the outer-shape cache-key
    /// partition is the substrate's outer `Sexp` `intent_hash`
    /// composition axis — binding the twelve-arm ALL array on the typed
    /// algebra makes attestation-key drift a compile error rather than
    /// a silent BLAKE3 mis-hash. THEORY.md §VI.1 — generation over
    /// composition; the family-wide contract sweeps (alignment with
    /// `ALL`, membership through [`Self::hash_discriminator`], partition
    /// closure onto `{0..=6}`) emerge from the composition of ONE
    /// substrate primitive (this `pub(crate) const` array) rather than
    /// as per-variant inline assertions at each call site.
    #[allow(dead_code)]
    pub(crate) const HASH_DISCRIMINATORS: [u8; 12] = [
        Self::NIL_HASH_DISCRIMINATOR,
        Self::SYMBOL_HASH_DISCRIMINATOR,
        Self::KEYWORD_HASH_DISCRIMINATOR,
        Self::STRING_HASH_DISCRIMINATOR,
        Self::INT_HASH_DISCRIMINATOR,
        Self::FLOAT_HASH_DISCRIMINATOR,
        Self::BOOL_HASH_DISCRIMINATOR,
        Self::LIST_HASH_DISCRIMINATOR,
        Self::QUOTE_HASH_DISCRIMINATOR,
        Self::QUASIQUOTE_HASH_DISCRIMINATOR,
        Self::UNQUOTE_HASH_DISCRIMINATOR,
        Self::UNQUOTE_SPLICE_HASH_DISCRIMINATOR,
    ];
}

// `impl std::fmt::Display for SexpShape` + `impl std::str::FromStr for
// SexpShape` + `impl tatara_closed_set::ClosedSet for SexpShape` +
// `pub struct UnknownSexpShape(pub String)` are generated by
// `#[derive(tatara_closed_set::DeriveClosedSet)]` on the enum declaration
// above. `label` delegates to the inherent `SexpShape::label` via
// `#[closed_set(via = "label")]` — the inherent name coincides with
// the trait method name here; the delegation stays explicit so the
// SAME wiring shape applies whether the inherent projection is `label`
// / `prefix` / `marker` / `keyword` / `as_str`. The `display` flag
// emits the substrate-wide `f.write_str(Self::label(*self))` block.
// `#[closed_set(generate_unknown = "sexp shape")]` emits the typed
// parse-rejection carrier with the substrate-wide `Debug + Clone +
// PartialEq + Eq + thiserror::Error` derives and the `#[error("unknown
// sexp shape: {0}")]` annotation byte-for-byte; the explicit label
// matches the auto-derived `pascal_to_spaced_lowercase("SexpShape")`
// projection byte-for-byte but pins the pre-lift wording. Round-trip
// + cross-axis rejection (`ExpectedKwargShape` labels `"number"` /
// `"list of strings"` whose vocabulary partially overlaps SexpShape on
// five of seven entries) pinned by
// `sexp_shape_label_round_trips_through_from_str` +
// `sexp_shape_from_str_accepts_only_canonical_labels`.

/// Closed-set identifier for the STRUCTURAL-RESIDUAL carving of the
/// twelve-variant [`SexpShape`] outer-shape lattice — the 2-of-12
/// subset that names the two outermost shapes lying outside BOTH
/// the atomic-payload carving ([`crate::ast::AtomKind`], 6-of-12) and
/// the quote-family carving ([`crate::ast::QuoteForm`], 4-of-12):
/// [`crate::ast::Sexp::Nil`] (the empty-result marker projecting to
/// [`SexpShape::Nil`]) and [`crate::ast::Sexp::List`] (the
/// payload-bearing container projecting to [`SexpShape::List`]).
///
/// Third-and-final closed-set carving of [`SexpShape`], sibling of
/// [`crate::ast::AtomKind`] (the 6-of-12 atomic-payload carving) and
/// [`crate::ast::QuoteForm`] (the 4-of-12 quote-family carving). The
/// three carvings partition [`SexpShape::ALL`] disjointly (6 + 4 + 2 =
/// 12) — every outer shape is in EXACTLY ONE carving, and the
/// partition-total invariant becomes a TYPED THEOREM through the
/// three sibling projections
/// ([`SexpShape::as_atom_kind`], [`SexpShape::as_quote_form`],
/// [`SexpShape::as_structural_kind`]) rather than through a runtime
/// `matches!(shape, SexpShape::Nil | SexpShape::List)` predicate that
/// the substrate maintained by test discipline at the carving-
/// disjointness pin pre-lift.
///
/// Mirror at the residual-carving boundary of the prior-run
/// [`crate::ast::AtomKind`] (atomic-payload closed set),
/// [`crate::ast::QuoteForm`] (quote-family closed set), and
/// [`UnquoteForm`] (template-substitution subset closed set) lifts:
/// those enums key their respective carvings on a typed identity
/// carried inside their variant listings; this enum keys the RESIDUAL
/// carving that lies outside all three of them on the same
/// [`SexpShape`] outer-shape lattice, closing the three-carving
/// partition.
///
/// Theory anchor: THEORY.md §V.1 — knowable platform; the residual
/// carving becomes a TYPE rather than an inline
/// `matches!(shape, SexpShape::Nil | SexpShape::List)` predicate the
/// substrate maintained by callsite discipline. THEORY.md §VI.1 —
/// generation over composition; the typed enum lands the structural-
/// completeness floor for the residual outer-shape surface, parallel
/// to how [`crate::ast::AtomKind`] lands it for the atomic-payload
/// carving and [`crate::ast::QuoteForm`] lands it for the quote-family
/// carving. THEORY.md §II.1 invariant 1 — typed entry; the
/// (structural-residual identity, outer shape) pairing is first-class
/// load-bearing data on the substrate algebra rather than a runtime
/// negation of the two sibling carvings.
#[derive(Debug, Clone, Copy, PartialEq, Eq, tatara_closed_set::DeriveClosedSet)]
#[closed_set(via = "label", display, generate_unknown = "structural kind")]
pub enum StructuralKind {
    /// `[`crate::ast::Sexp::Nil`]` — the empty-result marker projecting
    /// to [`SexpShape::Nil`]. `"nil"` diagnostic label (byte-for-byte
    /// identical to [`SexpShape::Nil`]'s label under the
    /// [`Self::sexp_shape`] composition).
    Nil,
    /// `[`crate::ast::Sexp::List(_)`]` — the payload-bearing container
    /// projecting to [`SexpShape::List`]. `"list"` diagnostic label
    /// (byte-for-byte identical to [`SexpShape::List`]'s label under
    /// the [`Self::sexp_shape`] composition).
    List,
}

impl StructuralKind {
    /// The closed set of two structural-residual outer shapes — single
    /// source of truth that drives the [`Self::label`] / [`fmt::Display`]
    /// projection AND the [`FromStr`] decode sweep keyed on
    /// [`Self::label`]. Adding a hypothetical third structural-residual
    /// variant (e.g. `Vector` for `#(...)` reader syntax, `Map` for
    /// `{...}`, or `Char` for `#\x` — each of which extends
    /// [`SexpShape::ALL`] AND joins THIS enum's residual carving iff
    /// it lies outside BOTH the atomic-payload carving and the
    /// quote-family carving) lands at one [`Self::ALL`] entry + one
    /// [`Self::sexp_shape`] arm + one [`SexpShape::as_structural_kind`]
    /// arm — exhaustively checked by the compiler (the `[Self; 2]`
    /// array literal forces the arity) AND by the per-variant truth-
    /// table tests below.
    ///
    /// Sibling closed-set lift to every other typed-shape enum the
    /// substrate carries: this crate's own [`SexpShape::ALL`] (the
    /// twelve reachable outer shapes — superset of this residual's
    /// two via [`Self::sexp_shape`]), [`crate::ast::AtomKind::ALL`]
    /// (the six atomic-payload kinds — peer 6-of-12 carving of
    /// [`SexpShape`]), [`crate::ast::QuoteForm::ALL`] (the four
    /// homoiconic prefix-wrappers — peer 4-of-12 carving of
    /// [`SexpShape`]), [`UnquoteForm::ALL`] (the two template-
    /// substitution markers — proper 2-of-4 subset of [`crate::ast::QuoteForm`]),
    /// and the cross-crate `tatara-process` family (`ConditionKind::ALL`,
    /// `ProcessPhase::ALL`, `ProcessSignal::ALL`, `ChannelKind::ALL`,
    /// `IntentKind::ALL`, `LifetimeKind::ALL`, `RequestorKind::ALL`,
    /// `ReceiptKind::ALL`, …) every one of which paired its typed
    /// projection with `ALL` before this lift.
    ///
    /// Future consumers that compose against `ALL`: LSP / REPL
    /// completion for the operator-facing rendered residual-shape
    /// label under the "structural" carving-axis column; a future
    /// `tatara-check` predicate `(check-shape-projects-to-structural
    /// …)` that filters diagnostics to "was this rejection on the
    /// structural residual (neither atomic nor quote-family)?"; any
    /// future audit-trail metric jointly labeled by [`Self::label`]
    /// (e.g. `tatara_lisp_structural_shape_total{shape="list"}`) —
    /// the metric label set IS [`Self::ALL`] mapped through
    /// [`Self::label`]; any future structural rewriter (typed analogue
    /// of MLIR's `op.walk<StructuralOp>()`) that wants to sweep over
    /// every residual shape in a typed sequence.
    pub const ALL: [Self; 2] = [Self::Nil, Self::List];

    /// Canonical `&'static str` bytes for the [`Self::Nil`] structural-
    /// residual marker — aliases [`SexpShape::NIL_LABEL`] on the
    /// StructuralKind ⊂ SexpShape carving so the marker-level per-role
    /// bytes bind at ONE `pub const` on the parent superset's residual
    /// arm rather than at TWO sites (the per-role `pub const` AND a
    /// parallel inline literal). Per-role peer of `Self::Nil` on the
    /// closed-set structural-residual algebra; consumers reach for
    /// `StructuralKind::NIL_LABEL` when the caller has a variant in
    /// hand at compile time and wants the canonical diagnostic bytes
    /// without runtime dispatch through [`Self::label`].
    ///
    /// Sibling posture to the peer 6-of-12 atomic-payload carving's
    /// per-role aliases ([`crate::ast::AtomKind::SYMBOL_LABEL`] …
    /// [`crate::ast::AtomKind::BOOL_LABEL`] — every one an alias of
    /// its [`SexpShape`] peer) and the peer 4-of-12 quote-family
    /// carving's per-role prefixes on [`crate::ast::QuoteForm`] — the
    /// third and final closed-set carving of [`SexpShape`] now
    /// surfaces its per-role marker bytes through the same alias-chain
    /// shape rather than through the composition
    /// [`Self::sexp_shape`] + [`SexpShape::label`] alone.
    pub const NIL_LABEL: &'static str = SexpShape::NIL_LABEL;

    /// Canonical `&'static str` bytes for the [`Self::List`]
    /// structural-residual marker — aliases [`SexpShape::LIST_LABEL`]
    /// on the StructuralKind ⊂ SexpShape carving. Per-role peer of
    /// `Self::List`; matches [`ExpectedKwargShape::LIST_LABEL`] byte-
    /// for-byte through the SexpShape canonical site (the same
    /// cross-axis overlap [`SexpShape::LIST_LABEL`]'s docstring pins).
    pub const LIST_LABEL: &'static str = SexpShape::LIST_LABEL;

    /// Closed-set forced-arity ALL array over the canonical structural-
    /// residual marker `&'static str` bytes, in declaration order
    /// matching [`Self::ALL`] element-wise (pinned by
    /// `structural_kind_labels_align_with_all_by_index`). Sibling
    /// posture to [`SexpShape::LABELS`] (`[&'static str; 12]` — the
    /// superset carving this StructuralKind subset embeds into),
    /// [`crate::ast::AtomKind::LABELS`] (`[&'static str; 6]` — the
    /// peer 6-of-12 atomic-payload carving's ALL array),
    /// [`ExpectedKwargShape::LABELS`] (`[&'static str; 7]`),
    /// [`KwargPathKind::LABELS`] (`[&'static str; 3]`),
    /// [`MacroDefHead::KEYWORDS`] (`[&'static str; 3]`),
    /// [`crate::ast::Atom::BOOL_LITERALS`] (`[&'static str; 2]`), and
    /// [`crate::ast::QuoteForm::PREFIXES`] (`[&'static str; 4]`) —
    /// every closed-set outer projection on the substrate that carries
    /// an `&'static str`-per-variant label now pins its per-role
    /// canonical bytes at ONE `pub const` per role PLUS an ALL array
    /// for family-wide consumers.
    ///
    /// Pre-lift the two structural-residual marker bytes had NO per-
    /// role primitive on this closed-set algebra — a consumer with a
    /// `StructuralKind` variant in hand at compile time reaching for
    /// the canonical diagnostic bytes had to spell
    /// `StructuralKind::Nil.label()` (runtime dispatch through the
    /// composition [`Self::sexp_shape`] + [`SexpShape::label`]) OR
    /// reach across the algebra boundary into
    /// [`SexpShape::NIL_LABEL`] and re-derive the StructuralKind ⊂
    /// SexpShape variant pairing at the call site. Post-lift the TWO
    /// canonical bytes bind at ONE `pub const` per role on the typed
    /// [`StructuralKind`] algebra AND at [`Self::LABELS`] as a family-
    /// wide forced-arity array — a future LSP / REPL completion bar
    /// keyed on `StructuralKind::LABELS` for the "structural" carving-
    /// axis column, a `tatara-check` coverage sweep over the residual
    /// arms of a `TypeMismatch.got` corpus, or a Sekiban audit-trail
    /// metric jointly labeled by the structural marker
    /// (`tatara_lisp_structural_shape_total{kind="list"}`) reads
    /// through the typed constants on this subset algebra without
    /// re-deriving the 2-of-12 carving inline.
    ///
    /// Each entry is byte-for-byte identical to the corresponding
    /// [`SexpShape`] residual arm — an intentional cross-axis overlap
    /// pinned by
    /// `structural_kind_per_role_labels_alias_sexp_shape_per_role_labels_byte_for_byte`
    /// so a future label rename on EITHER side (a SexpShape `"nil"` →
    /// `"empty"` drift, or a StructuralKind rename that skips the
    /// alias) fails-loudly at the alias test rather than as a silent
    /// operator-facing vocabulary fracture. Adding a hypothetical
    /// third structural-residual variant (e.g. `Vector` for `#(...)`
    /// reader syntax, `Map` for `{...}`) extends [`Self::ALL`] AND
    /// [`Self::LABELS`] AND adds ONE per-role `pub const` alias in
    /// lockstep — rustc's forced-arity check on the two `[_; N]`
    /// arrays fails compilation if EITHER ALL array grows without the
    /// other.
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the two
    /// canonical structural-residual marker bytes bind at ONE typed
    /// `[&'static str; 2]` array on the closed-set StructuralKind
    /// algebra rather than at zero-primitive-on-this-subset-plus-two-
    /// inline-lookups scattered across the substrate. THEORY.md §V.1
    /// — knowable platform; the family's cardinality becomes a TYPE-
    /// level constant on the substrate algebra rather than a per-
    /// consumer runtime dispatch through the composition. THEORY.md
    /// §VI.1 — generation over composition; the family-wide contract
    /// sweeps (alignment with `ALL`, pairwise disjointness, membership
    /// through [`Self::label`]) emerge from the composition of TWO
    /// substrate primitives (this `pub const` array + the two per-
    /// role `pub const *_LABEL` aliases) rather than as per-variant
    /// inline assertions duplicated at each call site.
    pub const LABELS: [&'static str; 2] = [Self::NIL_LABEL, Self::LIST_LABEL];

    /// Project the typed `StructuralKind` to the canonical `&'static
    /// str` diagnostic label — `"nil"` for [`Self::Nil`], `"list"` for
    /// [`Self::List`]. Each label is byte-for-byte identical to the
    /// corresponding [`SexpShape`] variant's label — and post-lift
    /// this agreement is STRUCTURAL rather than a two-literal-
    /// discipline site pinned by a cross-projection test.
    ///
    /// Composition law: `StructuralKind::label(sk) ==
    /// StructuralKind::sexp_shape(sk).label()` for every `sk:
    /// StructuralKind`. Body composes [`Self::sexp_shape`] (the typed
    /// projection lifting each StructuralKind variant into its peer
    /// [`SexpShape`] variant) with [`SexpShape::label`] (the canonical
    /// `&'static str` projection on the superset's twelve-variant
    /// closed set), so the two residual-arm labels live at ONE
    /// canonical site ([`SexpShape::label`]) rather than at TWO
    /// ([`SexpShape::label`] AND a parallel two-arm match here).
    ///
    /// Same lift posture as the sibling
    /// [`crate::ast::AtomKind::label`] ⊂ [`SexpShape::label`]
    /// composition (via [`crate::ast::AtomKind::sexp_shape`]) and
    /// [`UnquoteForm::marker`] ⊂ [`crate::ast::QuoteForm::prefix`]
    /// composition (via [`UnquoteForm::to_quote_form`]): the typed
    /// projection sits on the value, and the consumer composes
    /// through the existing structural pairing rather than re-
    /// deriving the per-variant literal. The `&'static str` lifetime
    /// is load-bearing: the composition allocates nothing at runtime
    /// ([`Self::sexp_shape`] returns a `Copy` value and
    /// [`SexpShape::label`] yields `&'static str`).
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the
    /// StructuralKind ⊂ SexpShape label-vocabulary containment
    /// becomes a TYPED CONSEQUENCE of the [`Self::sexp_shape`] +
    /// [`SexpShape::label`] composition rather than literal discipline
    /// at two sites. THEORY.md §VI.1 — generation over composition;
    /// the two residual-arm labels live at ONE canonical site
    /// ([`SexpShape::label`]) and this method generates its identity
    /// through the typed-projection composition. THEORY.md §II.1
    /// invariant 2 — free middle; consumers of the [`StructuralKind`]
    /// algebra route through ONE typed closed-set projection family
    /// with no per-consumer literal duplication.
    #[must_use]
    pub fn label(self) -> &'static str {
        self.sexp_shape().label()
    }

    /// Project the typed marker into its matching [`SexpShape`]
    /// variant — `Nil → SexpShape::Nil`, `List → SexpShape::List`.
    /// ONE projection on the closed-set structural-residual algebra
    /// that binds the (StructuralKind variant, SexpShape variant)
    /// pairing at ONE site on the typed algebra rather than at two
    /// byte-identical inline arms scattered across consumers. Direct
    /// sibling to [`crate::ast::AtomKind::sexp_shape`] (the 6-of-12
    /// atomic-payload carving's embed) and
    /// [`crate::ast::QuoteForm::sexp_shape`] (the 4-of-12 quote-family
    /// carving's embed) — all three embeds land at ONE typed method
    /// per closed-set carving, symmetric across the partition.
    ///
    /// Bidirectional dual: the inverse projection
    /// [`SexpShape::as_structural_kind`] (12→2, partial) covers the
    /// 2-of-12 carving of [`SexpShape`] this embed reaches. The pair
    /// `(StructuralKind::sexp_shape, SexpShape::as_structural_kind)`
    /// forms an `Iso(StructuralKind, StructuralShape ⊂ SexpShape)`:
    /// every typed marker round-trips through the embed
    /// (`StructuralKind::sexp_shape(sk).as_structural_kind() ==
    /// Some(sk)` for every `sk: StructuralKind`), every structural-
    /// residual shape pre-image recovers the typed marker. The ten
    /// non-residual shapes (`Symbol`, `Keyword`, `String`, `Int`,
    /// `Float`, `Bool`, `Quote`, `Quasiquote`, `Unquote`,
    /// `UnquoteSplice`) form the kernel of the inverse —
    /// `as_structural_kind` returns `None` for them.
    ///
    /// Composition law (partition-total, jointly with the two sibling
    /// carvings): for every `shape: SexpShape`, EXACTLY ONE of
    /// `shape.as_atom_kind()`, `shape.as_quote_form()`,
    /// `shape.as_structural_kind()` is `Some(_)`. Pinned by the joint
    /// partition test in this module, so a regression that drifts any
    /// of the three carvings' partition-membership (an
    /// [`crate::ast::AtomKind::sexp_shape`] arm, a
    /// [`crate::ast::QuoteForm::sexp_shape`] arm, or this
    /// [`Self::sexp_shape`] arm) surfaces immediately.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the
    /// (StructuralKind variant, SexpShape variant) pairing becomes a
    /// TYPE projection on the substrate algebra rather than a runtime
    /// `matches!(shape, SexpShape::Nil | SexpShape::List)` predicate.
    /// A typo or swap at the shape-projection site is no longer a
    /// runtime drift but a compile error against the typed projection.
    /// THEORY.md §II.1 invariant 2 — free middle; the (embed, project)
    /// pair binds at TWO typed sites — [`Self::sexp_shape`] for the
    /// embed, [`SexpShape::as_structural_kind`] for the project —
    /// completing the third and final closed-set carving of the
    /// outer-shape algebra. THEORY.md §VI.1 — generation over
    /// composition; the two residual arms lift to ONE typed method,
    /// and the partition-total invariant across the three carvings
    /// becomes a TYPED THEOREM rather than a test assertion.
    #[must_use]
    pub fn sexp_shape(self) -> SexpShape {
        match self {
            Self::Nil => Self::NIL_SHAPE,
            Self::List => Self::LIST_SHAPE,
        }
    }

    /// Canonical [`SexpShape`] embed target for the [`Self::Nil`]
    /// structural-residual arm on the StructuralKind ⊂ SexpShape
    /// 2-of-12 carving — [`SexpShape::Nil`]. Per-role peer of
    /// `Self::Nil` on the closed-set structural-residual → outer-shape
    /// embed axis; consumers with a `StructuralKind` variant in hand
    /// at compile time bind the canonical embed target through ONE
    /// typed `pub const` per role rather than through runtime dispatch
    /// via [`Self::sexp_shape`] or by re-deriving the StructuralKind ⊂
    /// SexpShape variant pairing inline.
    ///
    /// Sibling posture to [`Self::NIL_LABEL`] (the per-role diagnostic
    /// label alias) and [`Self::NIL_HASH_DISCRIMINATOR`] (the per-role
    /// outer-Sexp cache-key byte) on the closed-set StructuralKind
    /// algebra — each closes a distinct per-role sub-vocabulary axis
    /// on the StructuralKind carving. This constant closes the THIRD
    /// per-role axis on [`StructuralKind`] (the `SexpShape`-embed
    /// axis, paired with the pre-existing `&'static str`
    /// diagnostic-label axis + the `u8` cache-key axis) at ONE typed
    /// alias through the peer superset variant on the [`SexpShape`]
    /// closed set.
    ///
    /// Sibling posture to the peer 6-of-12 atomic-payload carving's
    /// per-role SHAPE aliases
    /// ([`crate::ast::AtomKind::SYMBOL_SHAPE`] …
    /// [`crate::ast::AtomKind::BOOL_SHAPE`]) and the peer 4-of-12
    /// quote-family carving's per-role SHAPE aliases
    /// ([`crate::ast::QuoteForm::QUOTE_SHAPE`] …
    /// [`crate::ast::QuoteForm::UNQUOTE_SPLICE_SHAPE`]). Post-lift the
    /// SexpShape's per-carving embed-target axis is uniformly surfaced
    /// through per-role `pub const *_SHAPE` aliases on every
    /// sub-carving that carries a bidirectional (embed, project)
    /// `Iso(_, _ ⊂ SexpShape)` — `AtomKind` (6), `QuoteForm` (4), and
    /// now `StructuralKind` (2) — closing the third and final peer of
    /// the twelve-arm superset.
    pub const NIL_SHAPE: SexpShape = SexpShape::Nil;

    /// Canonical [`SexpShape`] embed target for the [`Self::List`]
    /// structural-residual arm on the StructuralKind ⊂ SexpShape
    /// 2-of-12 carving — [`SexpShape::List`]. Per-role peer of
    /// `Self::List`. See [`Self::NIL_SHAPE`] for the alias-chain shape
    /// every sibling shares.
    pub const LIST_SHAPE: SexpShape = SexpShape::List;

    /// Closed-set forced-arity ALL array over the canonical
    /// [`SexpShape`] embed targets on the StructuralKind ⊂ SexpShape
    /// 2-of-12 carving, in declaration order matching [`Self::ALL`]
    /// element-wise (pinned by
    /// `structural_kind_shapes_align_with_all_by_index`). Sibling
    /// posture to [`Self::LABELS`] (`[&'static str; 2]` — per-role
    /// diagnostic bytes) and [`Self::HASH_DISCRIMINATORS`] (`[u8; 2]`
    /// — per-role outer-Sexp cache-key bytes) on the SAME closed-set
    /// StructuralKind algebra; where those two arrays lift per-role
    /// `&'static str` and `u8` sub-vocabularies onto the substrate,
    /// this array lifts the per-role [`SexpShape`] embed-target
    /// sub-vocabulary at the same `[_; 2]` forced arity.
    ///
    /// Sibling posture to [`crate::ast::AtomKind::SHAPES`]
    /// (`[SexpShape; 6]`) and [`crate::ast::QuoteForm::SHAPES`]
    /// (`[SexpShape; 4]`) — the two peer carvings' family-wide
    /// embed-target arrays on the AtomKind ⊂ SexpShape 6-of-12 and
    /// QuoteForm ⊂ SexpShape 4-of-12 carvings. Together the THREE
    /// `SHAPES` arrays (6 + 4 + 2 = 12) cover EVERY sub-carving of
    /// [`SexpShape`] that carries a bidirectional `Iso(_, _ ⊂
    /// SexpShape)` at the same `[SexpShape; N]` forced-arity shape —
    /// a family-wide sweep zipping every carving's `ALL` + `SHAPES` in
    /// lockstep now closes over the FULL 12-arm outer-shape algebra at
    /// ONE typed pair-of-arrays per carving. This lift closes the
    /// THIRD and FINAL peer array — post-lift the substrate's every
    /// closed-set carving of [`SexpShape`] has its embed-target
    /// sub-vocabulary surfaced through a per-role `pub const` + ALL
    /// array uniformly.
    ///
    /// Pre-lift the two [`SexpShape`] embed targets had NO per-role
    /// primitive on this closed-set algebra — a consumer with a
    /// [`StructuralKind`] variant in hand at compile time reaching for
    /// the canonical embed target had to spell
    /// `StructuralKind::Nil.sexp_shape()` (runtime dispatch through
    /// the two-arm match body) OR re-derive the StructuralKind ⊂
    /// SexpShape variant pairing at the call site by importing both
    /// enums and spelling `SexpShape::Nil` inline. Post-lift the TWO
    /// canonical embed targets bind at ONE `pub const` per role on the
    /// typed [`StructuralKind`] algebra AND at [`Self::SHAPES`] as a
    /// family-wide forced-arity array — a future LSP / REPL completion
    /// bar keyed on `StructuralKind::SHAPES` for the "which SexpShape
    /// does this StructuralKind embed into?" outer-shape column, a
    /// `tatara-check` coverage sweep zipping `StructuralKind::ALL` /
    /// `LABELS` / `HASH_DISCRIMINATORS` / `SHAPES` in lockstep for a
    /// family-wide (variant, label, byte, embed-target) quadruple
    /// render, or a Sekiban audit-trail metric jointly labeled by the
    /// embed-target's SexpShape identity reads through the typed
    /// constants on this subset algebra without re-deriving the 2-of-12
    /// carving inline.
    ///
    /// Round-trip identity with the inverse projection
    /// [`SexpShape::as_structural_kind`]: for every index `i`,
    /// `Self::SHAPES[i].as_structural_kind() == Some(Self::ALL[i])`
    /// (pinned by
    /// `structural_kind_shapes_align_with_all_by_index_through_as_structural_kind`)
    /// — the embed / project section closes as a family-wide array-
    /// indexed law rather than as a per-variant assertion sweep.
    /// Adding a hypothetical third structural-residual variant (e.g.
    /// `Vector` for `#(...)` reader syntax, `Map` for `{...}`, or
    /// `Char` for `#\x` — each of which extends [`SexpShape::ALL`]
    /// AND joins THIS carving iff it lies outside BOTH the
    /// atomic-payload and quote-family carvings) extends [`Self::ALL`]
    /// AND [`Self::SHAPES`] AND [`SexpShape::ALL`] AND adds ONE
    /// per-role `pub const *_SHAPE` in lockstep — rustc's forced-arity
    /// check on the two `[_; N]` arrays fails compilation if EITHER
    /// ALL array grows without the other, AND the peer
    /// [`SexpShape::as_structural_kind`] arm must grow in lockstep to
    /// preserve the round-trip identity.
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the two
    /// canonical [`SexpShape`] embed targets bind at ONE typed
    /// `[SexpShape; 2]` array on the closed-set StructuralKind algebra
    /// rather than at zero-primitive-on-this-subset-plus-two-inline-
    /// lookups scattered across the substrate. Closes the THIRD
    /// per-role `pub const` axis on the StructuralKind carving
    /// alongside the pre-existing LABELS + HASH_DISCRIMINATORS axes.
    /// THEORY.md §V.1 — knowable platform; the family's cardinality
    /// becomes a TYPE-level constant on the substrate algebra rather
    /// than a per-consumer runtime dispatch through the composition. A
    /// regression that drifts the (StructuralKind variant, SexpShape
    /// variant) pairing at ONE of the three typed sites (per-role
    /// alias, family-wide array, projection method) fails-loudly at
    /// the array-indexed sweep rather than as a silent operator-facing
    /// diagnostic drift. THEORY.md §II.1 invariant 2 — free middle;
    /// the (embed, project) pair binds at THREE typed sites now — the
    /// projection method [`Self::sexp_shape`], this family-wide array,
    /// AND the peer inverse [`SexpShape::as_structural_kind`] — with
    /// rustc-enforced consistency across all three. THEORY.md §VI.1
    /// — generation over composition; the family-wide contract sweeps
    /// (alignment with `ALL`, round-trip through
    /// `as_structural_kind`, membership through `sexp_shape`, pairwise
    /// injectivity across the two embed targets) emerge from the
    /// composition of TWO substrate primitives (this `pub const`
    /// array + the two per-role `pub const *_SHAPE` aliases) rather
    /// than as per-variant inline assertions duplicated at each call
    /// site.
    pub const SHAPES: [SexpShape; 2] = [Self::NIL_SHAPE, Self::LIST_SHAPE];

    /// Stable, per-variant byte discriminator that paired with the
    /// residual outer-shape hash body builds the substrate's
    /// [`Hash for Sexp`](crate::ast::Sexp) projection at the two
    /// structural-residual arms — `0u8` for [`Self::Nil`], `2u8` for
    /// [`Self::List`]. The byte values are load-bearing because the
    /// macro-expansion cache ([`crate::macro_expand::Expander`]'s cache)
    /// keys on the hash of `(macro_name, args)`, and every `Sexp`
    /// participates in that hash — changing a discriminator silently
    /// invalidates every cached expansion across the substrate AND
    /// risks collision with the reserved bytes the other two
    /// closed-set carvings' arms use (`1u8` for the [`crate::ast::Sexp::Atom`]
    /// outer-carve marker, `3..=6` for the quote-family via
    /// [`crate::ast::QuoteForm::hash_discriminator`]).
    ///
    /// The closed set ensures the two arms partition `{0, 2}`
    /// injectively. Disjointness across the outer-Sexp discriminator
    /// space is structural rather than overlap-induced hash
    /// collision: [`crate::ast::Sexp::Atom(_)`]'s outer-carve byte
    /// (`1u8`, single-arm literal inside [`Hash for Sexp`](crate::ast::Sexp))
    /// AND [`crate::ast::QuoteForm::hash_discriminator`]'s
    /// `{3, 4, 5, 6}` partition sit around this carving's `{0, 2}`
    /// with a compile-time-checked prefix-uniqueness contract
    /// [`Hash for Sexp`](crate::ast::Sexp)'s outer match maintains
    /// through the exhaustive closed-set arm coverage. A future
    /// structural-residual, quote-family, or atomic-kind extension
    /// must extend both this method's arms AND the sibling
    /// discriminator methods in lockstep, with rustc binding the
    /// consistency through exhaustiveness over each closed enum.
    ///
    /// The SIBLING of the two prior-run discriminator lifts on the
    /// same outer-Sexp Hash body: [`crate::ast::AtomKind::hash_discriminator`]
    /// carries the six-variant atomic-payload carve's inner cache-key
    /// bytes at the nested `Atom::hash` level, and
    /// [`crate::ast::QuoteForm::hash_discriminator`] carries the four-
    /// variant quote-family carve's outer-Sexp cache-key bytes at the
    /// same `Hash for Sexp` body. Post-lift the SAME shape lands at
    /// the structural-residual axis — every carving now surfaces its
    /// hash-projection through ONE typed method rather than through
    /// per-arm inline byte literals at the [`Hash for Sexp`](crate::ast::Sexp)
    /// body. The three carvings' `hash_discriminator` methods form
    /// the joint bit-map onto the outer-Sexp cache-key space, and
    /// their partition-disjointness is the substrate's cache-key
    /// prefix-uniqueness contract.
    ///
    /// `pub(crate)` because the byte-discriminator surface is an
    /// implementation detail of the substrate's [`Hash for Sexp`](crate::ast::Sexp)
    /// cache-key contract; exposing it publicly would leak the
    /// cache-key shape through the API without enabling any external
    /// consumer the public projections ([`Self::label`],
    /// [`Self::sexp_shape`]) don't already serve. Same posture as
    /// [`crate::ast::AtomKind::hash_discriminator`] and
    /// [`crate::ast::QuoteForm::hash_discriminator`].
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the
    /// (StructuralKind variant, cache-key byte) pairing becomes a TYPE
    /// projection on the substrate algebra rather than two `0u8`/`2u8`
    /// inline literals in [`Hash for Sexp`](crate::ast::Sexp). A typo
    /// or swap at the hash-projection site is no longer a runtime
    /// cache-key drift but a compile error against the typed
    /// projection. THEORY.md §II.1 invariant 2 — free middle; ALL
    /// THREE closed-set carvings (atomic-payload via
    /// [`crate::ast::AtomKind::hash_discriminator`], quote-family via
    /// [`crate::ast::QuoteForm::hash_discriminator`], structural-
    /// residual via this method) now route through a typed
    /// closed-set match family, so a regression that drifts ONE
    /// carving's discriminator bytes from the others cannot reach
    /// the substrate's runtime cache. THEORY.md §VI.1 — generation
    /// over composition; the two `0u8`/`2u8` residual-arm literals
    /// appeared inline at [`Hash for Sexp`](crate::ast::Sexp) — past
    /// the ≥2 PRIME-DIRECTIVE trigger once the structural shape is
    /// named, and post-lift this method's two arms are the ONE
    /// canonical site the outer-Sexp Hash body composes through.
    /// Canonical `u8` cache-key byte for [`Self::Nil`]'s
    /// [`Self::hash_discriminator`] arm — `0`. Per-role peer of
    /// [`Self::Nil`] on the closed-set structural-residual cache-key-
    /// byte axis; consumers reach for
    /// `StructuralKind::NIL_HASH_DISCRIMINATOR` when the caller has a
    /// variant in hand at compile time and wants the canonical byte
    /// without runtime dispatch through [`Self::hash_discriminator`].
    /// The byte is load-bearing because the macro-expansion cache
    /// ([`crate::macro_expand::Expander`]'s cache) keys on
    /// [`Hash for Sexp`](crate::ast::Sexp), and any renumbering
    /// silently invalidates every cached expansion AND risks collision
    /// with the reserved bytes the other two closed-set carvings' arms
    /// use (`1u8` for the [`crate::ast::Sexp::Atom`] outer-carve
    /// marker, `3..=6` for the quote-family via
    /// [`crate::ast::QuoteForm::hash_discriminator`]).
    ///
    /// Sibling posture to
    /// [`crate::ast::AtomKind::SYMBOL_HASH_DISCRIMINATOR`] on the
    /// atomic-payload sub-carving of the SAME outer-`Sexp` Hash body
    /// AND to [`crate::ast::QuoteForm::QUOTE_HASH_DISCRIMINATOR`] on
    /// the quote-family sub-carving — the third and final closed-set
    /// carving of [`SexpShape`] now surfaces its per-role cache-key
    /// bytes at ONE `pub(crate) const` per variant PLUS a family-wide
    /// [`Self::HASH_DISCRIMINATORS`] array.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 5 — composition
    /// preserves proofs; the alias-chain composition law
    /// `StructuralKind::HASH_DISCRIMINATORS[i] ==
    /// StructuralKind::ALL[i].hash_discriminator()` binds the family-
    /// wide array to the projection method at rustc time, pinned by
    /// byte equality. THEORY.md §III — the typescape; the two
    /// canonical cache-key bytes bind at ONE `pub(crate) const` per
    /// role on the typed algebra rather than as inline `u8` literals
    /// in the [`Self::hash_discriminator`] match arms.
    pub(crate) const NIL_HASH_DISCRIMINATOR: u8 = 0;

    /// Canonical `u8` cache-key byte for [`Self::List`]'s
    /// [`Self::hash_discriminator`] arm — `2`. Sibling of
    /// [`Self::NIL_HASH_DISCRIMINATOR`] on the closed-set per-role
    /// structural-residual cache-key-byte axis; see
    /// [`Self::NIL_HASH_DISCRIMINATOR`] for the algebra-level round-
    /// trip + disjointness contracts every sibling shares.
    ///
    /// The gap at `1u8` between [`Self::NIL_HASH_DISCRIMINATOR`] and
    /// this constant is intentional and load-bearing: it reserves the
    /// outer-carve byte [`crate::ast::Sexp::Atom(_)`] uses at the
    /// outer [`Hash for Sexp`](crate::ast::Sexp) body — the joint
    /// partition `{0, 1, 2, 3, 4, 5, 6}` binds bit-for-bit across the
    /// three closed-set carvings AND the atomic-carve outer marker.
    pub(crate) const LIST_HASH_DISCRIMINATOR: u8 = 2;

    /// Closed-set forced-arity ALL array over the canonical
    /// structural-residual cache-key `u8` bytes, in declaration order
    /// matching [`Self::ALL`] element-wise (pinned by
    /// `structural_kind_hash_discriminators_align_with_all_by_index`).
    /// Sibling posture to [`Self::LABELS`] (`[&'static str; 2]` — the
    /// diagnostic-label `&'static str` axis on the SAME closed set),
    /// [`crate::ast::AtomKind::HASH_DISCRIMINATORS`] (`[u8; 6]` — the
    /// atomic-payload sub-carving's cache-key-byte peer at the nested
    /// [`crate::ast::Atom`] Hash level), and
    /// [`crate::ast::QuoteForm::HASH_DISCRIMINATORS`] (`[u8; 4]` —
    /// the quote-family sub-carving's cache-key-byte peer at the same
    /// outer [`Hash for Sexp`](crate::ast::Sexp) body). Every closed-
    /// set carving of [`SexpShape`] now pins its per-role canonical
    /// cache-key bytes at ONE `pub(crate) const` per role PLUS an ALL
    /// array for family-wide consumers.
    ///
    /// Pre-lift the two cache-key bytes had NO per-role primitive on
    /// this closed-set algebra — a consumer with a [`StructuralKind`]
    /// variant in hand at compile time reaching for the canonical byte
    /// had to spell `StructuralKind::Nil.hash_discriminator()`
    /// (runtime dispatch through the match arm) OR reach across into
    /// the inline `0u8` at the pre-lift match arm's [`Self::Nil`]
    /// branch and re-derive the (variant, byte) pairing at the call
    /// site. Post-lift the TWO canonical bytes bind at ONE
    /// `pub(crate) const` per role on the typed [`StructuralKind`]
    /// algebra AND at [`Self::HASH_DISCRIMINATORS`] as a family-wide
    /// forced-arity array — a future substrate-facing cache-key
    /// introspection tool (a `tatara-check` predicate `(check-outer-
    /// sexp-cache-key-partition-injective …)` that asserts the joint
    /// `{0, 1, 2, 3, 4, 5, 6}` partition structurally by sweeping the
    /// three carvings' `HASH_DISCRIMINATORS` arrays, a Sekiban audit-
    /// trail metric jointly labeled by the structural-residual cache-
    /// key partition, a future `TypedRewriter<StructuralKindOp>` sweep
    /// zipping ALL / LABELS / HASH_DISCRIMINATORS in lockstep for a
    /// family-wide (variant, label, byte) triple render) reads
    /// through the typed constants without re-deriving the two-arm
    /// carving inline.
    ///
    /// Each entry is byte-for-byte identical to the pre-lift inline
    /// `u8` literal at the corresponding [`Self::hash_discriminator`]
    /// arm — pinned by
    /// `structural_kind_hash_discriminators_pin_legacy_cache_key_bytes`
    /// so a regression that drifts ONE `pub(crate) const` from its
    /// pre-lift byte silently invalidates every cached expansion of
    /// a [`crate::ast::Sexp::Nil`] / [`crate::ast::Sexp::List`]
    /// participating in [`crate::macro_expand::Expander::cache`],
    /// fails-loudly at the alias test rather than at a silent cache
    /// mis-hash. Adding a hypothetical third structural-residual
    /// variant (e.g. `Vector` for `#(...)` reader syntax, `Map` for
    /// `{...}`) extends [`Self::ALL`] AND [`Self::HASH_DISCRIMINATORS`]
    /// AND adds ONE per-role `pub(crate) const` in lockstep — rustc's
    /// forced-arity check on the two `[_; N]` arrays fails
    /// compilation if EITHER array grows without the other, closing
    /// the extensibility gap that pre-lift silently allowed a
    /// discriminator collision on `7u8` (the next free byte on the
    /// outer [`Sexp`](crate::ast::Sexp) cache-key space) or an
    /// accidental re-use of the `1u8` outer-carve byte reserved for
    /// [`crate::ast::Sexp::Atom(_)`].
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the two
    /// canonical cache-key bytes bind at ONE typed `[u8; 2]` array on
    /// the closed-set [`StructuralKind`] algebra rather than at zero-
    /// primitive-plus-two-inline-`u8`-literals scattered across the
    /// [`Self::hash_discriminator`] match arms. THEORY.md §V.1 —
    /// knowable platform; the family's cardinality becomes a TYPE-
    /// level constant on the substrate algebra rather than a per-
    /// consumer runtime dispatch through the match table. THEORY.md
    /// §V.3 — three-pillar attestation; the cache-key partition is
    /// the substrate's outer [`Sexp`](crate::ast::Sexp) `intent_hash`
    /// composition axis for every structural-residual arm — binding
    /// the two bytes on the typed algebra makes attestation-key drift
    /// a compile error rather than a silent BLAKE3 mis-hash.
    /// THEORY.md §VI.1 — generation over composition; the family-
    /// wide contract sweeps (alignment with `ALL`, pairwise
    /// disjointness, membership through [`Self::hash_discriminator`])
    /// emerge from the composition of TWO substrate primitives (this
    /// `pub(crate) const` array + the two per-role
    /// `pub(crate) const *_HASH_DISCRIMINATOR` aliases) rather than
    /// as per-variant inline assertions duplicated at each call site.
    ///
    /// The `#[allow(dead_code)]` posture matches
    /// [`crate::ast::AtomKind::HASH_DISCRIMINATORS`] and
    /// [`crate::ast::QuoteForm::HASH_DISCRIMINATORS`]: the substrate's
    /// current [`Hash for Sexp`](crate::ast::Sexp) body composes
    /// through the per-variant [`Self::hash_discriminator`] projection
    /// arm-by-arm rather than sweeping the family-wide array, so no
    /// non-test caller currently reaches this ALL array directly. The
    /// lift lands the substrate primitive so future consumers keyed
    /// on the whole family (a future
    /// [`crate::macro_expand::Expander`] cache-warmup pass that
    /// hashes the structural-residual byte-set upfront, a future
    /// `tatara-check` predicate `(check-outer-sexp-cache-key-
    /// partition-injective …)` that verifies the joint
    /// `{0, 1, 2, 3, 4, 5, 6}` partition structurally, a future
    /// `TypedRewriter<StructuralKindOp>` sweep zipping ALL / LABELS /
    /// HASH_DISCRIMINATORS in lockstep for a family-wide (variant,
    /// label, byte) triple render) bind to ONE `[u8; 2]` primitive
    /// rather than re-deriving the array inline per callsite.
    #[allow(dead_code)]
    pub(crate) const HASH_DISCRIMINATORS: [u8; 2] =
        [Self::NIL_HASH_DISCRIMINATOR, Self::LIST_HASH_DISCRIMINATOR];

    #[must_use]
    pub(crate) fn hash_discriminator(self) -> u8 {
        match self {
            Self::Nil => Self::NIL_HASH_DISCRIMINATOR,
            Self::List => Self::LIST_HASH_DISCRIMINATOR,
        }
    }
}

// `impl std::fmt::Display for StructuralKind` + `impl std::str::FromStr
// for StructuralKind` + `impl tatara_closed_set::ClosedSet for StructuralKind` +
// `pub struct UnknownStructuralKind(pub String)` are generated by
// `#[derive(tatara_closed_set::DeriveClosedSet)]` on the enum declaration
// above. `label` delegates to the inherent `StructuralKind::label` via
// `#[closed_set(via = "label")]` — the inherent name coincides with
// the trait method name here; the delegation stays explicit so the
// SAME wiring shape applies whether the inherent projection is `label`
// / `prefix` / `marker` / `keyword` / `as_str`. The `display` flag
// emits the substrate-wide `f.write_str(Self::label(*self))` block.
// `#[closed_set(generate_unknown = "structural kind")]` emits the typed
// parse-rejection carrier with the substrate-wide `Debug + Clone +
// PartialEq + Eq + thiserror::Error` derives and the `#[error("unknown
// structural kind: {0}")]` annotation byte-for-byte; the explicit label
// matches the auto-derived `pascal_to_spaced_lowercase("StructuralKind")`
// projection byte-for-byte but pins the pre-lift wording. Round-trip +
// cross-axis rejection (the label vocabulary partially overlaps
// [`SexpShape`]'s labels on the two residual entries `"nil"` and
// `"list"`; the disjointness contract is that a `FromStr` on THIS
// closed set MUST reject the ten non-residual `SexpShape` labels since
// they lie outside the carving) pinned by
// `structural_kind_label_round_trips_through_from_str` +
// `structural_kind_from_str_rejects_non_structural_sexp_shape_labels`.

/// Typed witness of an offending `Sexp` at a typed-entry rejection
/// boundary — the joint identity (shape + literal) the substrate's
/// diagnostic surface owes the operator. Pairs the closed-set
/// `SexpShape` projection (the twelve reachable Sexp outermost shapes
/// the reader can produce) with the `Sexp::Display` projection (the
/// literal value the operator wrote: `5`, `:foo`, `(list 1 2)`,
/// `notify-ref`, etc.).
///
/// Mirror at the offending-value boundary of the prior-run
/// `SexpShape` (typed-shape closed set), `ExpectedKwargShape`
/// (expected-shape closed set), `KwargPath` (kwargs-path shapes),
/// `MacroDefHead` (macro-definition-head closed set), `UnquoteForm`
/// (template-marker syntactic forms), `CompilerSpecIoStage`
/// (disk-persistence surface), and `TemplateInvariantKind`
/// (bytecode-runtime surface) closed-set lifts: those enums key
/// rejection variants on a typed identity carried inside the
/// variant's data shape; `SexpWitness` keys the OFFENDING-VALUE side
/// (the `got: String` Sexp::Display slots on `NonSymbolUnquoteTarget`,
/// `SpliceOutsideList`, `NonSymbolParam`, `RestParamMissingName`,
/// `DefmacroNonSymbolName`, `DefmacroNonListParams`,
/// `MissingHeadSymbol`, and any future variant taking a `&Sexp` at
/// the helper boundary) on a typed joint identity so authoring tools
/// (REPL, LSP, `tatara-check`) bind to BOTH `witness.shape` (the
/// structural identity — pattern-matchable on `SexpShape::List` etc.)
/// AND `witness.display` (the literal value — renderable verbatim)
/// without losing either side.
///
/// Before this struct landed, the six error-builder helpers in
/// `macro_expand.rs` (`non_symbol_unquote_target`, `splice_outside_list`,
/// `non_symbol_param`, `rest_param_missing_name`,
/// `defmacro_non_symbol_name`, `defmacro_non_list_params`) and one
/// in `domain.rs` (`missing_head_err`'s caller) each projected `&Sexp
/// → String` via `Sexp::to_string()` at the boundary — the structural
/// `SexpShape` was lost. After this primitive lands, every offending-
/// value variant slot that takes a `SexpWitness` carries the typed
/// shape AND the literal jointly in ONE owned value the variant lives
/// independent of the call frame on.
///
/// The byte-for-byte rendering contract is preserved: `Display` for
/// `SexpWitness` writes only the `display` field, so a variant whose
/// `#[error(...)]` annotation projects through `{got}` renders
/// byte-identically to the legacy `got: String` shape — every
/// downstream substring-grep consumer (`tatara-check`, REPL) passes
/// unchanged. The gain is structural: tools that pattern-match on
/// `witness.shape == SexpShape::List` now bind to the typed identity
/// directly instead of substring-parsing the rendered literal.
///
/// `Clone + Debug + PartialEq + Eq` are retained (same posture as
/// every other owned-data `LispError` field); `Copy` is dropped
/// because the `display: String` is not `Copy`. When a future run
/// gives `Sexp` source spans, `pos: Option<usize>` lands here in ONE
/// place and every offending-value site picks up positional rendering
/// with no per-variant edit — the same future-proofing posture
/// `KwargPath`, `SexpShape`, and `ExpectedKwargShape` already carry.
///
/// Theory anchor: THEORY.md §V.1 — knowable platform; the offending-
/// value's joint identity (structural shape + renderable literal)
/// becomes a TYPE rather than a `String` projection at the helper
/// boundary that discards the shape. After this primitive lands the
/// substrate's understanding of "the offending Sexp at a typed-entry
/// rejection" lives in ONE typed struct the diagnostic promotions
/// hang off of. THEORY.md §VI.1 — generation over composition; seven
/// inline `got.to_string()` projections at error-builder boundaries
/// (six in `macro_expand.rs`, one in `domain.rs::missing_head_err`'s
/// caller) is past the three-times-rule trigger. THEORY.md §II.1
/// invariant 1 — typed entry; the offending Sexp's identity is part
/// of the proof of WHAT the typed-entry gate rejected, and the typed
/// witness makes both halves of that identity (shape + literal)
/// load-bearing data on the variant rather than the literal-only
/// `String` projection the legacy shape carried.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SexpWitness {
    /// Structural identity — the typed-shape projection (`SexpShape::Int`,
    /// `SexpShape::List`, etc.). Pattern-matchable; future `pos: Option<usize>`
    /// promotions land alongside this field once `Sexp` carries spans.
    pub shape: SexpShape,
    /// Renderable identity — the `Sexp::Display` projection (`"5"`,
    /// `"(list 1 2)"`, `":foo"`, etc.). Owned so the witness lives
    /// independent of the call frame and crosses thread boundaries
    /// cleanly. Feeds the `#[error(...)]` annotation's `{got}` slot
    /// via `SexpWitness`'s `Display` impl.
    pub display: String,
}

impl SexpWitness {
    /// Owned constructor — pairs a typed `SexpShape` with an owned
    /// `String` projection of the offending `Sexp::Display`. Used by
    /// the `sexp_witness(&Sexp)` projection helper in `domain.rs`;
    /// hand-written `TataraDomain` impls that need to construct a
    /// witness at their own call boundary route through this
    /// constructor.
    #[must_use]
    pub fn new(shape: SexpShape, display: impl Into<String>) -> Self {
        Self {
            shape,
            display: display.into(),
        }
    }
}

impl std::fmt::Display for SexpWitness {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // Render the literal only — the byte-for-byte legacy rendering
        // of every `got: String` variant slot that projected through
        // `Sexp::Display`. Authoring tools that substring-grep on the
        // rendered diagnostic see no drift; tools that pattern-match
        // on the variant's `SexpWitness`-shaped `got` slot bind to
        // `witness.shape` directly.
        f.write_str(&self.display)
    }
}

fn unbound_hint_suffix(prefix: UnquoteForm, hint: Option<&str>) -> String {
    match hint {
        Some(h) => format!("; did you mean {}{h}?", prefix.marker()),
        None => String::new(),
    }
}

/// Renders the bare parenthetical suffix shared by EVERY `*_suffix`
/// diagnostic helper: a single leading space, an open paren, the
/// already-formatted `body`, and a close paren — ` ({body})`.
///
/// This is the lowest layer of the suffix-wrapping algebra. Four helpers
/// append a parenthetical structural-detail clause to a `#[error(...)]`
/// prefix and ALL FOUR share this exact skeleton — the leading space and the
/// parens:
///   * `unknown_among_suffix` wraps a `did you mean …?; …` / bare candidate
///     clause (the kwarg + registry gates);
///   * `rest_param_missing_name_suffix` wraps the `rest marker at position …`
///     clause;
///   * `missing_head_symbol_suffix` wraps the `got …` / `empty list` clause.
///
/// Owning the leading-space-and-parens HERE means it cannot drift across the
/// four renderers: a regression that drops the leading space at one site,
/// moves a paren, or doubles a space is structurally impossible because there
/// is exactly ONE wrapping implementation. Each helper keeps ONLY its own
/// body-construction and binds it to this primitive.
fn paren_suffix(body: &str) -> String {
    format!(" ({body})")
}

/// Renders the parenthetical "unknown X among a known set" suffix shared by
/// the kwarg gate (`UnknownKwarg`) and the registry gate
/// (`UnknownDomainKeyword`). `hint` is the already-formatted near-miss
/// suggestion (`:foo` for kwargs, `(foo ...)` for registry keywords); `body`
/// is the already-formatted candidate clause (`allowed: :a, :b` /
/// `registered: x, y` / `no domains registered`).
///
/// This layer owns ONLY the `did you mean {hint}?; ` join when a hint is
/// present, so the two gates whose docs declare they "share ONE structural
/// shape" cannot drift apart in that join. The bare-parenthetical wrapping —
/// the leading space and the parens — is delegated to `paren_suffix`, the one
/// skeleton every `*_suffix` helper binds to.
fn unknown_among_suffix(hint: Option<&str>, body: &str) -> String {
    match hint {
        Some(h) => paren_suffix(&format!("did you mean {h}?; {body}")),
        None => paren_suffix(body),
    }
}

fn unknown_kwarg_suffix(hint: Option<&str>, allowed: &[String]) -> String {
    let allowed_list = allowed
        .iter()
        .map(|s| format!(":{s}"))
        .collect::<Vec<_>>()
        .join(", ");
    unknown_among_suffix(
        hint.map(|h| format!(":{h}")).as_deref(),
        &format!("allowed: {allowed_list}"),
    )
}

fn rest_param_missing_name_suffix(rest_position: usize, got: Option<&str>) -> String {
    let body = match got {
        Some(g) => format!("rest marker at position {rest_position}, got {g}"),
        None => format!("rest marker at position {rest_position}, none provided"),
    };
    paren_suffix(&body)
}

fn rest_param_trailing_tokens_suffix(rest_position: usize, extra: usize, first: &str) -> String {
    paren_suffix(&format!(
        "rest marker at position {rest_position}, {extra} trailing after name, first: {first}"
    ))
}

fn optional_marker_repeated_suffix(first_position: usize, second_position: usize) -> String {
    paren_suffix(&format!(
        "first &optional at position {first_position}, second at position {second_position}"
    ))
}

fn optional_param_malformed_suffix(
    position: usize,
    reason: OptionalParamMalformedReason,
) -> String {
    paren_suffix(&format!("position {position}, {}", reason.label()))
}

fn missing_head_symbol_suffix(got: Option<&str>) -> String {
    let body = match got {
        Some(g) => format!("got {g}"),
        None => "empty list".to_string(),
    };
    paren_suffix(&body)
}

fn unknown_domain_keyword_suffix(hint: Option<&str>, registered: &[String]) -> String {
    let body = if registered.is_empty() {
        "no domains registered".to_string()
    } else {
        format!("registered: {}", registered.join(", "))
    };
    unknown_among_suffix(hint.map(|h| format!("({h} ...)")).as_deref(), &body)
}

impl LispError {
    /// Byte offset of the failure into the source, when locatable.
    ///
    /// A PROJECTION of [`LispError::span`] — `span().map(|s| s.start)` and
    /// nothing else. Pre-lift this carried its own copy of the exhaustive
    /// positional/non-positional classification, so a new variant had to
    /// be classified TWICE and the two matches were free to disagree about
    /// whether an error is locatable. Post-lift `span` is the single
    /// classification site; this is the point-shaped view of it, kept
    /// because `format_diagnostic`'s `--> label:line:col` header names one
    /// byte, not a range.
    #[must_use]
    pub fn position(&self) -> Option<usize> {
        self.span().map(|span| span.start)
    }

    /// Source `Span` of the failure, when locatable.
    ///
    /// THE classification site: a variant is locatable iff it appears in
    /// the `Some(..)` arms below. Variants without a location (`Type`,
    /// `Compile`, …) return `None`, so callers render a snippet only when
    /// the substrate has the information to do so; adding a variant
    /// without classifying it here is a non-exhaustive-match build
    /// failure, not a silently-positionless error.
    ///
    /// The range — not just the start — is what lets
    /// `crate::diagnostic::format_diagnostic` underline the offending
    /// FORM rather than its first byte. A zero-width span is legal and
    /// means "point here" (see `Eof`); `caret_run` clamps it up to one
    /// caret.
    #[must_use]
    pub fn span(&self) -> Option<Span> {
        match self {
            // `UnexpectedChar` predates the span lift and is not
            // constructed anywhere in the workspace today (measured: the
            // declaration, this arm, and one unit pin). Its span is
            // nonetheless exact rather than invented — a `char` occupies
            // `len_utf8()` bytes from the offset it was found at.
            Self::UnexpectedChar(c, pos) => Some(Span::new(*pos, pos + c.len_utf8())),
            Self::UnterminatedString(span) => Some(*span),
            Self::UnmatchedParen { span }
            | Self::UnmatchedOpenParen { span }
            | Self::Eof { span } => Some(*span),
            Self::InvalidNumber(_)
            | Self::UnknownSymbol(_)
            | Self::Type { .. }
            | Self::Compile { .. }
            | Self::TypeMismatch { .. }
            | Self::HeadMismatch { .. }
            | Self::Unknown { .. }
            | Self::Missing(_)
            | Self::OddKwargs { .. }
            | Self::UnboundTemplateVar { .. }
            | Self::DuplicateKwarg { .. }
            | Self::MissingKwarg { .. }
            | Self::UnknownKwarg { .. }
            | Self::UnknownDomainKeyword { .. }
            | Self::NonSymbolUnquoteTarget { .. }
            | Self::SpliceOutsideList { .. }
            | Self::MissingMacroArg { .. }
            | Self::TooManyMacroArgs { .. }
            | Self::NonSymbolParam { .. }
            | Self::RestParamMissingName { .. }
            | Self::RestParamTrailingTokens { .. }
            | Self::OptionalMarkerRepeated { .. }
            | Self::OptionalParamMalformed { .. }
            | Self::DefmacroArity { .. }
            | Self::DefmacroNonSymbolName { .. }
            | Self::DefmacroNonListParams { .. }
            | Self::NotAListForm { .. }
            | Self::MissingHeadSymbol { .. }
            | Self::NamedFormMissingName { .. }
            | Self::NamedFormNonSymbolName { .. }
            | Self::RewriterNonList { .. }
            | Self::DomainSerialize { .. }
            | Self::KwargDeserialize { .. }
            | Self::CompilerSpecIo { .. }
            | Self::TemplateInvariant { .. }
            | Self::ExpansionDepthExceeded { .. }
            | Self::ExpansionSizeExceeded { .. }
            | Self::MacroBodySizeExceeded { .. }
            | Self::RegisteredMacrosExceeded { .. }
            | Self::MacroArityExceeded { .. } => None,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::{
        missing_head_symbol_suffix, optional_marker_repeated_suffix,
        optional_param_malformed_suffix, paren_suffix, rest_param_missing_name_suffix,
        rest_param_trailing_tokens_suffix, unknown_among_suffix, unknown_domain_keyword_suffix,
        unknown_kwarg_suffix, CompilerSpecIoStage, ExpectedKwargShape, KwargPath, KwargPathKind,
        LispError, MacroDefHead, OptionalParamMalformedReason, SexpShape, SexpWitness,
        StructuralKind, TemplateInvariantKind, UnknownExpectedKwargShape, UnknownKwargPathKind,
        UnknownMacroDefHead, UnknownSexpShape, UnknownUnquoteForm, UnquoteForm,
    };
    use crate::span::Span;

    #[test]
    fn position_extracts_offset_from_positional_variants() {
        assert_eq!(LispError::UnexpectedChar('?', 7).position(), Some(7));
        assert_eq!(
            LispError::UnterminatedString(Span::new(11, 15)).position(),
            Some(11)
        );
        assert_eq!(
            LispError::UnmatchedParen {
                span: Span::new(3, 4)
            }
            .position(),
            Some(3)
        );
        assert_eq!(
            LispError::UnmatchedOpenParen {
                span: Span::new(0, 6)
            }
            .position(),
            Some(0)
        );
        assert_eq!(
            LispError::Eof {
                span: Span::new(42, 42)
            }
            .position(),
            Some(42)
        );
    }

    #[test]
    fn span_carries_the_full_range_position_projects_the_start_of() {
        // `position()` is now `span().map(|s| s.start)` — one
        // classification, two views. Pin BOTH views on the same values so
        // a regression that re-splits them (a variant locatable through
        // one accessor but not the other) fails here rather than showing
        // up as a diagnostic that renders a header without a caret.
        let cases = [
            (
                LispError::UnterminatedString(Span::new(11, 15)),
                Span::new(11, 15),
            ),
            (
                LispError::UnmatchedParen {
                    span: Span::new(3, 4),
                },
                Span::new(3, 4),
            ),
            (
                LispError::UnmatchedOpenParen {
                    span: Span::new(0, 6),
                },
                Span::new(0, 6),
            ),
            (
                LispError::Eof {
                    span: Span::new(42, 42),
                },
                Span::new(42, 42),
            ),
            // `UnexpectedChar` still stores a bare offset; its span is
            // derived from the char's own UTF-8 width, so a multi-byte
            // char reports the bytes it actually occupies.
            (LispError::UnexpectedChar('?', 7), Span::new(7, 8)),
            (LispError::UnexpectedChar('é', 7), Span::new(7, 9)),
        ];
        for (err, expected) in cases {
            assert_eq!(err.span(), Some(expected), "span mismatch for {err:?}");
            assert_eq!(
                err.position(),
                Some(expected.start),
                "position must project span.start for {err:?}"
            );
        }
    }

    #[test]
    fn span_is_none_exactly_where_position_is_none() {
        // The other half of the one-classification invariant: a
        // non-locatable error is non-locatable through both views.
        let err = LispError::Compile {
            form: ":threshold".into(),
            message: "expected number".into(),
        };
        assert_eq!(err.span(), None);
        assert_eq!(err.position(), None);
    }

    #[test]
    fn position_is_none_for_non_positional_variants() {
        assert_eq!(
            LispError::OddKwargs {
                dangling: ":query".into()
            }
            .position(),
            None
        );
        assert_eq!(LispError::Missing("name").position(), None);
        assert_eq!(LispError::InvalidNumber("nan".into()).position(), None);
        assert_eq!(LispError::UnknownSymbol("foo".into()).position(), None);
        assert_eq!(
            LispError::Type {
                expected: "int",
                got: "string".into()
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::Compile {
                form: ":x".into(),
                message: "bad".into()
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::TypeMismatch {
                form: KwargPath::named("x"),
                expected: ExpectedKwargShape::String,
                got: SexpShape::Int,
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::HeadMismatch {
                keyword: "defmonitor",
                got: "not-a-monitor".into(),
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::Unknown {
                category: "domain",
                value: "defx".into()
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::UnboundTemplateVar {
                prefix: UnquoteForm::Unquote,
                name: "xx".into(),
                hint: Some("x".into()),
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::UnboundTemplateVar {
                prefix: UnquoteForm::Splice,
                name: "ys".into(),
                hint: None,
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::DuplicateKwarg { key: "name".into() }.position(),
            None
        );
        assert_eq!(
            LispError::MissingKwarg { key: "name".into() }.position(),
            None
        );
        assert_eq!(
            LispError::UnknownKwarg {
                key: "tthreshold".into(),
                hint: Some("threshold".into()),
                allowed: vec!["name".into(), "threshold".into()],
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::UnknownDomainKeyword {
                keyword: "defmoniter".into(),
                hint: Some("defmonitor".into()),
                registered: vec!["defalertpolicy".into(), "defmonitor".into()],
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::NonSymbolUnquoteTarget {
                prefix: UnquoteForm::Unquote,
                got: SexpWitness::new(SexpShape::List, "(list 1 2)"),
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::NonSymbolUnquoteTarget {
                prefix: UnquoteForm::Splice,
                got: SexpWitness::new(SexpShape::Int, "5"),
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::SpliceOutsideList {
                got: SexpWitness::new(SexpShape::Symbol, "xs"),
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::SpliceOutsideList {
                got: SexpWitness::new(SexpShape::List, "(list 1 2)"),
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::MissingMacroArg {
                macro_name: "wrap".into(),
                param: "b".into(),
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::MissingMacroArg {
                macro_name: "call".into(),
                param: "f".into(),
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::TooManyMacroArgs {
                macro_name: "pair".into(),
                expected: 2,
                got: 3,
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::TooManyMacroArgs {
                macro_name: "wrap".into(),
                expected: 1,
                got: 5,
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::NonSymbolParam {
                position: 0,
                got: SexpWitness::new(SexpShape::Int, "5"),
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::NonSymbolParam {
                position: 2,
                got: SexpWitness::new(SexpShape::List, "(nested)"),
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::RestParamMissingName {
                rest_position: 1,
                got: None,
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::RestParamMissingName {
                rest_position: 0,
                got: Some(SexpWitness::new(SexpShape::Int, "5")),
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::OptionalParamMalformed {
                position: 1,
                got: SexpWitness::new(SexpShape::List, "()"),
                reason: OptionalParamMalformedReason::EmptyList,
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::OptionalParamMalformed {
                position: 3,
                got: SexpWitness::new(SexpShape::List, "(x 1 2)"),
                reason: OptionalParamMalformedReason::ExtraElements { length: 3 },
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::DefmacroArity {
                head: MacroDefHead::Defmacro,
                arity: 1,
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::DefmacroArity {
                head: MacroDefHead::Defcheck,
                arity: 3,
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::DefmacroNonSymbolName {
                head: MacroDefHead::Defmacro,
                got: SexpWitness::new(SexpShape::Int, "5"),
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::DefmacroNonListParams {
                head: MacroDefHead::Defmacro,
                got: SexpWitness::new(SexpShape::Symbol, "x"),
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::DefmacroNonListParams {
                head: MacroDefHead::Defcheck,
                got: SexpWitness::new(SexpShape::Keyword, ":foo"),
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::DefmacroNonSymbolName {
                head: MacroDefHead::DefpointTemplate,
                got: SexpWitness::new(SexpShape::Keyword, ":foo"),
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::NotAListForm {
                keyword: "defmonitor",
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::NotAListForm {
                keyword: "defpoint",
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::MissingHeadSymbol {
                keyword: "defmonitor",
                got: None,
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::MissingHeadSymbol {
                keyword: "defpoint",
                got: Some(SexpWitness::new(SexpShape::Int, "5")),
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::NamedFormMissingName {
                keyword: "defpoint",
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::NamedFormMissingName {
                keyword: "defalertpolicy",
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::NamedFormNonSymbolName {
                keyword: "defpoint",
                got: SexpShape::Int,
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::NamedFormNonSymbolName {
                keyword: "defalertpolicy",
                got: SexpShape::List,
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::RewriterNonList {
                keyword: "defmonitor",
                got: SexpWitness::new(SexpShape::Int, "42"),
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::DomainSerialize {
                keyword: "defmonitor",
                message: "expected value at line 1 column 1".into(),
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::DomainSerialize {
                keyword: "defalertpolicy",
                message: "key must be a string".into(),
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::KwargDeserialize {
                path: KwargPath::named("level"),
                message: "unknown variant `NotASeverity`".into(),
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::KwargDeserialize {
                path: KwargPath::item("steps", 1),
                message: "invalid type: integer `7`, expected a string".into(),
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::CompilerSpecIo {
                stage: super::CompilerSpecIoStage::RealizeToDiskSerialize,
                message: "expected struct CompilerSpec".into(),
            }
            .position(),
            None
        );
        assert_eq!(
            LispError::CompilerSpecIo {
                stage: super::CompilerSpecIoStage::LoadFromDiskDeserialize,
                message: "expected value at line 1 column 1".into(),
            }
            .position(),
            None
        );
    }

    #[test]
    fn missing_head_symbol_display_with_empty_list_renders_legacy_prefix_and_empty_marker() {
        // `()` — list[0] doesn't exist. The variant renders the
        // legacy prefix `compile error in {keyword}: missing head
        // symbol` byte-for-byte AND names the structural reason
        // `(empty list)` parenthetically — same posture as how
        // `RestParamMissingName` renders `(rest marker at position
        // N, none provided)` and how `UnknownDomainKeyword` renders
        // `(no domains registered)` for the empty-side case. A
        // regression that drops either fragment fails-loudly here.
        let err = LispError::MissingHeadSymbol {
            keyword: "defmonitor",
            got: None,
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defmonitor: missing head symbol (empty list)"
        );
    }

    #[test]
    fn missing_head_symbol_display_with_int_got_renders_legacy_prefix_and_got() {
        // `(5 …)` — list[0] is the int `5`, not a symbol. The variant
        // renders both the keyword AND the offending head's
        // `Sexp::Display` projection — both fields are first-class
        // structural data, not embedded substrings of `message`. The
        // prefix `compile error in {keyword}: missing head symbol`
        // matches the legacy `Compile { form: keyword.to_string(),
        // message: "missing head symbol" }` byte-for-byte; the
        // structural detail (`(got 5)`) is appended.
        let err = LispError::MissingHeadSymbol {
            keyword: "defmonitor",
            got: Some(SexpWitness::new(SexpShape::Int, "5")),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defmonitor: missing head symbol (got 5)"
        );
    }

    #[test]
    fn missing_head_symbol_display_carries_keyword_atom_got_unchanged() {
        // `(:foo …)` — list[0] is a keyword atom. `Sexp::Display` for
        // `Atom::Keyword(s)` writes `:s`; pin that the variant's
        // Display passes the keyword form through unchanged so an
        // LSP that surfaces "you wrote `:foo` where a head symbol
        // was expected" gains the literal keyword value as data, no
        // re-parsing required.
        let err = LispError::MissingHeadSymbol {
            keyword: "defalertpolicy",
            got: Some(SexpWitness::new(SexpShape::Keyword, ":foo")),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defalertpolicy: missing head symbol (got :foo)"
        );
    }

    #[test]
    fn missing_head_symbol_display_carries_string_got_unchanged() {
        // `Sexp::Display` for `Atom::Str(s)` writes `"s"` (with quotes);
        // pin that the variant's Display passes the string form through
        // unchanged so an LSP that surfaces "you wrote `\"name\"` where
        // a head symbol was expected" gains the literal value as data,
        // no re-parsing required.
        let err = LispError::MissingHeadSymbol {
            keyword: "defmonitor",
            got: Some(SexpWitness::new(SexpShape::String, "\"name\"")),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defmonitor: missing head symbol (got \"name\")"
        );
    }

    #[test]
    fn missing_head_symbol_display_carries_nested_list_got_unchanged() {
        // `((nested) …)` — list[0] is itself a list. The nested form
        // round-trips through `Sexp::Display` into the variant's `got`
        // slot unchanged so the operator sees what they wrote.
        let err = LispError::MissingHeadSymbol {
            keyword: "defmonitor",
            got: Some(SexpWitness::new(SexpShape::List, "(nested)")),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defmonitor: missing head symbol (got (nested))"
        );
    }

    #[test]
    fn missing_head_symbol_display_preserves_legacy_substring_for_message_grep() {
        // Pin the legacy substring — `"missing head symbol"` — as a
        // separate assertion so a regression that drifts the wording
        // (e.g., to "no head symbol" or "head must be a symbol")
        // fails-loudly here even if the appended parenthetical changes
        // shape. The substring is what consumers downstream
        // (`tatara-check`, the REPL) substring-match on today; the
        // prefix matches the legacy `Compile { form:
        // keyword.to_string(), message: "missing head symbol" }`
        // byte-for-byte.
        let err = LispError::MissingHeadSymbol {
            keyword: "defmonitor",
            got: None,
        };
        let msg = format!("{err}");
        assert!(
            msg.contains("missing head symbol"),
            "expected legacy substring in message, got: {msg}"
        );
        assert!(
            msg.contains("compile error in defmonitor:"),
            "expected legacy form-label prefix in message, got: {msg}"
        );
    }

    #[test]
    fn missing_head_symbol_got_carries_typed_witness_through_variant_slot() {
        // Pin the structural binding AND the Display projection on
        // `LispError::MissingHeadSymbol.got`. After this lift the
        // variant's typed slot is `Option<SexpWitness>` — the joint
        // `SexpWitness` identity (the same primitive `SpliceOutsideList.got`,
        // `NonSymbolUnquoteTarget.got`, `NonSymbolParam.got`,
        // `DefmacroNonSymbolName.got`, `DefmacroNonListParams.got`,
        // and `RestParamMissingName.got` already carry) wrapped in
        // `Option` because the head slot bifurcates structurally
        // between "missing entirely" (`None`, empty list) and
        // "present but malformed" (`Some(SexpWitness)`, non-symbol
        // head). The typed witness lands on the `Some` arm only. A
        // regression that re-collapses to a free-form `Option<String>`
        // got slot (losing the rustc-enforced closed-set guarantee
        // on shape identity at the outer typed-entry gate's
        // non-symbol-head rejection variant) fails-loudly here.
        // Display via `SexpWitness::Display` writes only the `display`
        // field so the rendered `(got <display>)` clause is
        // byte-for-byte identical to the pre-lift `Option<String>`
        // shape; downstream substring-grep consumers (`tatara-check`,
        // REPL) see no drift.
        let err = LispError::MissingHeadSymbol {
            keyword: "defmonitor",
            got: Some(SexpWitness::new(SexpShape::Int, "5")),
        };
        match &err {
            LispError::MissingHeadSymbol { keyword, got } => {
                assert_eq!(*keyword, "defmonitor");
                let witness = got.as_ref().expect("got must be Some");
                assert_eq!(witness.shape, SexpShape::Int);
                assert_eq!(witness.display, "5");
            }
            other => panic!("expected MissingHeadSymbol, got {other:?}"),
        }
        assert_eq!(
            format!("{err}"),
            "compile error in defmonitor: missing head symbol (got 5)"
        );
    }

    #[test]
    fn missing_head_symbol_got_distinguishes_int_from_keyword_at_variant_slot() {
        // Pin the typed-shape bifurcation at the variant slot — `5`
        // (int atom at the head slot) and `:foo` (keyword atom at
        // the head slot) BOTH route to `MissingHeadSymbol` on the
        // `Some` arm, but the typed `got.shape` slot distinguishes
        // them structurally — `SexpShape::Int` vs.
        // `SexpShape::Keyword`. Sibling pin for the same structural-
        // shape-bifurcation property
        // `rest_param_missing_name_got_distinguishes_int_from_keyword_at_variant_slot`
        // pins on `RestParamMissingName`. A regression that erases
        // the typed shape (e.g., reverts to `got: Option<String>`)
        // would lose this distinction — tooling that wants to surface
        // "you wrote an int `5` where a head symbol was expected" vs.
        // "you wrote a keyword `:foo` where a head symbol was
        // expected (did you mean `foo`?)" would have to substring-
        // grep the `display` field, brittle.
        let err_int = LispError::MissingHeadSymbol {
            keyword: "defmonitor",
            got: Some(SexpWitness::new(SexpShape::Int, "5")),
        };
        let err_kw = LispError::MissingHeadSymbol {
            keyword: "defalertpolicy",
            got: Some(SexpWitness::new(SexpShape::Keyword, ":foo")),
        };
        let (int_shape, kw_shape) = (
            match &err_int {
                LispError::MissingHeadSymbol { got: Some(w), .. } => w.shape,
                _ => unreachable!(),
            },
            match &err_kw {
                LispError::MissingHeadSymbol { got: Some(w), .. } => w.shape,
                _ => unreachable!(),
            },
        );
        assert_ne!(
            int_shape, kw_shape,
            "Int and Keyword witnesses must remain structurally distinct at the variant slot",
        );
        assert_eq!(int_shape, SexpShape::Int);
        assert_eq!(kw_shape, SexpShape::Keyword);
    }

    #[test]
    fn missing_head_symbol_and_rest_param_gate_share_one_witness_primitive() {
        // Pin that ALL SEVEN Sexp-display-source `got` slots in the
        // substrate (`SpliceOutsideList`, `NonSymbolUnquoteTarget`,
        // `NonSymbolParam`, `DefmacroNonSymbolName`,
        // `DefmacroNonListParams`, `RestParamMissingName`,
        // `MissingHeadSymbol`) carry the SAME typed `SexpWitness`
        // primitive — the closed set of "offending inner Sexp"
        // identities is bound by ONE typed primitive across SEVEN
        // rejection surfaces: the template-gate's `,X/,@X` pair, the
        // defmacro-syntax-gate's `parse_params` walker (BOTH
        // non-symbol-param AND post-`&rest`-non-symbol-follower
        // rejection points), BOTH of the defmacro-syntax-gate's outer
        // `macro_def_from` rejection points (name-symbol AND
        // param-list), AND the outer `compile_from_sexp` typed-entry
        // gate's non-symbol-head rejection point. With this lift
        // EVERY `Sexp::Display`-source `got` slot in the substrate is
        // structurally unified end-to-end. The `Option`-wrap on
        // `MissingHeadSymbol.got` and `RestParamMissingName.got` is
        // the bifurcation between "missing entirely" and "present but
        // malformed"; the typed witness rides on the `Some` arm and
        // is structurally identical to the other five variants' got
        // slots. A regression that diverges the slot type on any one
        // variant (e.g., re-collapses `MissingHeadSymbol.got` to
        // `Option<String>` while leaving the others typed) fails-
        // loudly here because the assignment round-trips the witness
        // across all seven slot types. Sibling pin to
        // `rest_param_missing_name_and_macro_def_gate_share_one_witness_primitive`
        // — extending the typed-identity unification contract from
        // six slots to seven, closing the contract.
        let same_witness = SexpWitness::new(SexpShape::List, "(nested)");
        let missing_head = LispError::MissingHeadSymbol {
            keyword: "defmonitor",
            got: Some(same_witness.clone()),
        };
        let rest_param_missing_name = LispError::RestParamMissingName {
            rest_position: 0,
            got: Some(same_witness.clone()),
        };
        let defmacro_non_list_params = LispError::DefmacroNonListParams {
            head: MacroDefHead::Defmacro,
            got: same_witness.clone(),
        };
        let defmacro_non_symbol_name = LispError::DefmacroNonSymbolName {
            head: MacroDefHead::Defmacro,
            got: same_witness.clone(),
        };
        let non_symbol_param = LispError::NonSymbolParam {
            position: 0,
            got: same_witness.clone(),
        };
        let non_symbol_target = LispError::NonSymbolUnquoteTarget {
            prefix: UnquoteForm::Unquote,
            got: same_witness.clone(),
        };
        let splice_outside = LispError::SpliceOutsideList {
            got: same_witness.clone(),
        };
        match (
            &missing_head,
            &rest_param_missing_name,
            &defmacro_non_list_params,
            &defmacro_non_symbol_name,
            &non_symbol_param,
            &non_symbol_target,
            &splice_outside,
        ) {
            (
                LispError::MissingHeadSymbol { got: Some(a), .. },
                LispError::RestParamMissingName { got: Some(b), .. },
                LispError::DefmacroNonListParams { got: c, .. },
                LispError::DefmacroNonSymbolName { got: d, .. },
                LispError::NonSymbolParam { got: e, .. },
                LispError::NonSymbolUnquoteTarget { got: f, .. },
                LispError::SpliceOutsideList { got: g },
            ) => {
                assert_eq!(a.shape, b.shape);
                assert_eq!(b.shape, c.shape);
                assert_eq!(c.shape, d.shape);
                assert_eq!(d.shape, e.shape);
                assert_eq!(e.shape, f.shape);
                assert_eq!(f.shape, g.shape);
                assert_eq!(a.display, b.display);
                assert_eq!(b.display, c.display);
                assert_eq!(c.display, d.display);
                assert_eq!(d.display, e.display);
                assert_eq!(e.display, f.display);
                assert_eq!(f.display, g.display);
                assert_eq!(*a, same_witness);
                assert_eq!(*b, same_witness);
                assert_eq!(*c, same_witness);
                assert_eq!(*d, same_witness);
                assert_eq!(*e, same_witness);
                assert_eq!(*f, same_witness);
                assert_eq!(*g, same_witness);
            }
            _ => unreachable!(),
        }
    }

    #[test]
    fn not_a_list_form_display_renders_legacy_compile_shape() {
        // Pin the rendered diagnostic byte-for-byte against the
        // legacy `Compile { form: keyword.to_string(), message:
        // "expected list form" }` shape. Authoring tools that
        // substring-grep on the rendered message see no drift; tools
        // that pattern-match on the variant gain structural binding.
        let err = LispError::NotAListForm {
            keyword: "defmonitor",
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defmonitor: expected list form"
        );
    }

    #[test]
    fn not_a_list_form_display_carries_keyword_unchanged() {
        // Pin path-uniformity across distinct keywords — every
        // `TataraDomain` impl funnels through `not_a_list_form_err`
        // with its own `Self::KEYWORD`, so the variant's `keyword`
        // slot must round-trip every literal the derive macro
        // accepts. A regression that drops or rewrites the keyword
        // (e.g., lowercasing, stripping the `def` prefix) fails-
        // loudly here.
        let err = LispError::NotAListForm {
            keyword: "defpoint",
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defpoint: expected list form"
        );
    }

    #[test]
    fn not_a_list_form_display_preserves_legacy_substring_for_message_grep() {
        // Pin the legacy substring — `"expected list form"` — as a
        // separate assertion so a regression that drifts the
        // wording (e.g., to "expected list" or "must be a list")
        // fails-loudly here even if the prefix changes shape.
        // The substring is what consumers downstream
        // (`tatara-check`, the REPL) substring-match on today; the
        // prefix matches the legacy `Compile { form:
        // keyword.to_string(), message: "expected list form" }`
        // byte-for-byte.
        let err = LispError::NotAListForm {
            keyword: "defalertpolicy",
        };
        let msg = format!("{err}");
        assert!(
            msg.contains("expected list form"),
            "expected legacy substring in message, got: {msg}"
        );
        assert!(
            msg.contains("compile error in defalertpolicy:"),
            "expected legacy form-label prefix in message, got: {msg}"
        );
    }

    #[test]
    fn unknown_kwarg_display_with_hint_renders_did_you_mean_then_allowed_list() {
        // The variant renders byte-for-byte the same string the legacy
        // `Compile { form: ":tthreshold", message: "unknown keyword (did
        // you mean :threshold?; allowed: :a, :b, :c)" }` shape produced,
        // so authoring tools (REPL, LSP, `tatara-check`) that
        // substring-match on the rendered diagnostic see no drift; tools
        // that pattern-match on the variant gain structural binding.
        let err = LispError::UnknownKwarg {
            key: "tthreshold".into(),
            hint: Some("threshold".into()),
            allowed: vec!["name".into(), "query".into(), "threshold".into()],
        };
        assert_eq!(
            format!("{err}"),
            "compile error in :tthreshold: unknown keyword \
             (did you mean :threshold?; allowed: :name, :query, :threshold)"
        );
    }

    #[test]
    fn unknown_kwarg_display_without_hint_renders_allowed_list_only() {
        // No hint: the rendered message has the allowed list but no `did
        // you mean` clause. A wrong hint is worse than no hint — the
        // slot stays empty unless `suggest` ranks a candidate within
        // the bounded edit distance.
        let err = LispError::UnknownKwarg {
            key: "totally-unrelated".into(),
            hint: None,
            allowed: vec!["name".into(), "query".into(), "threshold".into()],
        };
        assert_eq!(
            format!("{err}"),
            "compile error in :totally-unrelated: unknown keyword \
             (allowed: :name, :query, :threshold)"
        );
    }

    #[test]
    fn unknown_kwarg_display_carries_kebab_case_keys_unchanged() {
        // `:notify-ref`, `:window-seconds`, every kebab-cased kwarg name
        // round-trips through both the offending-key slot AND the
        // allowed-list slot unchanged. Pinning this contract means a
        // regression that camelCases or lowercases either side fails-
        // loudly here.
        let err = LispError::UnknownKwarg {
            key: "windou-seconds".into(),
            hint: Some("window-seconds".into()),
            allowed: vec!["notify-ref".into(), "window-seconds".into()],
        };
        assert_eq!(
            format!("{err}"),
            "compile error in :windou-seconds: unknown keyword \
             (did you mean :window-seconds?; allowed: :notify-ref, :window-seconds)"
        );
    }

    #[test]
    fn duplicate_kwarg_display_matches_legacy_compile_shape() {
        // The variant renders byte-for-byte the same string the legacy
        // `Compile { form: ":name", message: "duplicate keyword" }` shape
        // produced, so authoring tools (REPL, LSP, `tatara-check`) that
        // substring-match on the rendered diagnostic see no drift; tools
        // that pattern-match on the variant gain structural binding.
        let err = LispError::DuplicateKwarg { key: "name".into() };
        assert_eq!(
            format!("{err}"),
            "compile error in :name: duplicate keyword"
        );
    }

    #[test]
    fn duplicate_kwarg_display_carries_kebab_case_keys_unchanged() {
        // `:notify-ref`, `:window-seconds`, every kebab-cased kwarg name
        // round-trips through the variant's Display unchanged. Pinning
        // this contract means a regression that camelCases or lowercases
        // the key in the rendered message fails-loudly.
        let err = LispError::DuplicateKwarg {
            key: "notify-ref".into(),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in :notify-ref: duplicate keyword"
        );
    }

    #[test]
    fn missing_kwarg_display_matches_legacy_compile_shape() {
        // The variant renders byte-for-byte the same string the legacy
        // `Compile { form: ":threshold", message: "required but not provided" }`
        // shape produced, so authoring tools (REPL, LSP, `tatara-check`) that
        // substring-match on the rendered diagnostic see no drift; tools
        // that pattern-match on the variant gain structural binding.
        let err = LispError::MissingKwarg {
            key: "threshold".into(),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in :threshold: required but not provided"
        );
    }

    #[test]
    fn missing_kwarg_display_carries_kebab_case_keys_unchanged() {
        // `:notify-ref`, `:window-seconds`, every kebab-cased kwarg name
        // round-trips through the variant's Display unchanged. Pinning
        // this contract means a regression that camelCases or lowercases
        // the key in the rendered message fails-loudly.
        let err = LispError::MissingKwarg {
            key: "notify-ref".into(),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in :notify-ref: required but not provided"
        );
    }

    #[test]
    fn unbound_template_var_display_without_hint_matches_legacy_compile_shape() {
        // Without a hint the variant renders byte-for-byte the same string
        // the legacy `Compile { form: ",x", message: "unbound" }` shape
        // produced, so authoring tools that substring-match on the rendered
        // diagnostic see no drift.
        let err = LispError::UnboundTemplateVar {
            prefix: UnquoteForm::Unquote,
            name: "y".into(),
            hint: None,
        };
        assert_eq!(format!("{err}"), "compile error in ,y: unbound");
    }

    #[test]
    fn unbound_template_var_display_appends_hint_suffix_when_present() {
        // With a hint the message gains a `"; did you mean ,X?"` suffix —
        // the prefix is preserved in the hint so the operator can copy-paste
        // the suggestion verbatim.
        let err = LispError::UnboundTemplateVar {
            prefix: UnquoteForm::Unquote,
            name: "xs".into(),
            hint: Some("x".into()),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in ,xs: unbound; did you mean ,x?"
        );
    }

    #[test]
    fn unknown_domain_keyword_display_with_hint_renders_did_you_mean_then_registered_list() {
        // The variant names the offending keyword's full call shape
        // (`(defmoniter ...)`), the structural near-miss in the same call
        // shape (`(defmonitor ...)`), and the sorted registered set.
        // Authoring tools that pattern-match on the variant gain
        // structural binding to `keyword` / `hint` / `registered` —
        // tools that substring-match on the rendered diagnostic see a
        // stable shape.
        let err = LispError::UnknownDomainKeyword {
            keyword: "defmoniter".into(),
            hint: Some("defmonitor".into()),
            registered: vec![
                "defalertpolicy".into(),
                "defmonitor".into(),
                "defnotify".into(),
            ],
        };
        assert_eq!(
            format!("{err}"),
            "unknown domain keyword: (defmoniter ...) \
             (did you mean (defmonitor ...)?; \
             registered: defalertpolicy, defmonitor, defnotify)"
        );
    }

    #[test]
    fn unknown_domain_keyword_display_without_hint_renders_registered_list_only() {
        // No near-miss within the bounded edit distance: the rendered
        // message has the registered list but no `did you mean` clause.
        // A wrong hint is worse than no hint — the slot stays empty
        // unless `suggest_keyword` ranks a candidate within the bound.
        let err = LispError::UnknownDomainKeyword {
            keyword: "totally-unrelated".into(),
            hint: None,
            registered: vec!["defalertpolicy".into(), "defmonitor".into()],
        };
        assert_eq!(
            format!("{err}"),
            "unknown domain keyword: (totally-unrelated ...) \
             (registered: defalertpolicy, defmonitor)"
        );
    }

    #[test]
    fn unknown_domain_keyword_display_with_empty_registry_renders_no_domains_registered() {
        // The substrate names the structural reason — the registry has
        // no candidates at all — instead of a misleading empty
        // `registered: ` suffix. A typo against an empty registry is
        // unambiguously a registry-seeding bug, not a near-miss.
        let err = LispError::UnknownDomainKeyword {
            keyword: "defmonitor".into(),
            hint: None,
            registered: vec![],
        };
        assert_eq!(
            format!("{err}"),
            "unknown domain keyword: (defmonitor ...) (no domains registered)"
        );
    }

    #[test]
    fn unknown_domain_keyword_display_carries_kebab_case_keywords_unchanged() {
        // Kebab-cased domain keywords (`defalert-policy`,
        // `defprocess-spec`) round-trip through the offending-keyword
        // slot AND the registered-list slot unchanged. Pinning this
        // contract means a regression that camelCases or lowercases
        // either side fails-loudly here.
        let err = LispError::UnknownDomainKeyword {
            keyword: "defalert-policiy".into(),
            hint: Some("defalert-policy".into()),
            registered: vec!["defalert-policy".into(), "defprocess-spec".into()],
        };
        assert_eq!(
            format!("{err}"),
            "unknown domain keyword: (defalert-policiy ...) \
             (did you mean (defalert-policy ...)?; \
             registered: defalert-policy, defprocess-spec)"
        );
    }

    #[test]
    fn unknown_among_suffix_owns_the_parenthetical_wrapping_skeleton() {
        // The Some-arm owns the `did you mean {hint}?; {body}` join; both arms
        // delegate the bare leading-space-and-parens to `paren_suffix`. Both
        // gates whose docs declare they "share ONE structural shape" wrap
        // through this skeleton, so a regression that drifts the join fails
        // here; one that drifts the bare wrapping fails in
        // `every_suffix_helper_wraps_through_one_paren_primitive`.
        assert_eq!(
            unknown_among_suffix(Some(":threshold"), "allowed: :name, :threshold"),
            " (did you mean :threshold?; allowed: :name, :threshold)"
        );
        assert_eq!(
            unknown_among_suffix(None, "allowed: :name, :threshold"),
            " (allowed: :name, :threshold)"
        );
    }

    #[test]
    fn optional_param_malformed_display_renders_typed_reason_in_suffix() {
        // The variant's Display threads BOTH the offending list literal
        // (`got` via SexpWitness's Display projection) AND the typed
        // `reason`'s label into the rendered message — the prefix names
        // the malformed-spec failure mode, the parenthetical suffix names
        // position + reason. Authoring tools (REPL, LSP, `tatara-check`)
        // pattern-match on the variant for structural binding; tools that
        // substring-match see a stable shape parallel to the existing
        // `OptionalMarkerRepeated` Display.
        let empty = LispError::OptionalParamMalformed {
            position: 1,
            got: SexpWitness::new(SexpShape::List, "()"),
            reason: OptionalParamMalformedReason::EmptyList,
        };
        assert_eq!(
            format!("{empty}"),
            "compile error in defmacro params: malformed &optional spec, got () (position 1, empty list)"
        );
        let missing = LispError::OptionalParamMalformed {
            position: 2,
            got: SexpWitness::new(SexpShape::List, "(x)"),
            reason: OptionalParamMalformedReason::MissingDefault,
        };
        assert_eq!(
            format!("{missing}"),
            "compile error in defmacro params: malformed &optional spec, got (x) (position 2, missing default)"
        );
        let extra = LispError::OptionalParamMalformed {
            position: 3,
            got: SexpWitness::new(SexpShape::List, "(x 1 2)"),
            reason: OptionalParamMalformedReason::ExtraElements { length: 3 },
        };
        assert_eq!(
            format!("{extra}"),
            "compile error in defmacro params: malformed &optional spec, got (x 1 2) (position 3, 3 elements (need 2))"
        );
        let nonsym = LispError::OptionalParamMalformed {
            position: 0,
            got: SexpWitness::new(SexpShape::List, "(5 default)"),
            reason: OptionalParamMalformedReason::NonSymbolName,
        };
        assert_eq!(
            format!("{nonsym}"),
            "compile error in defmacro params: malformed &optional spec, got (5 default) (position 0, name not a symbol)"
        );
    }

    #[test]
    fn optional_param_malformed_reason_static_labels_pin_legacy_label_bytes() {
        // Each per-role `pub const *_LABEL: &'static str` on the closed-set
        // `OptionalParamMalformedReason` algebra binds byte-for-byte to the
        // pre-lift inline literal at `label()`'s matching arm — so a
        // regression that renames ONE constant silently fractures the
        // operator-facing rejection wording. The three static-subset arms
        // route through the typed constants; the fourth arm
        // (`ExtraElements`) formats a `usize` payload dynamically and is
        // excluded from this pin.
        assert_eq!(OptionalParamMalformedReason::EMPTY_LIST_LABEL, "empty list");
        assert_eq!(
            OptionalParamMalformedReason::MISSING_DEFAULT_LABEL,
            "missing default"
        );
        assert_eq!(
            OptionalParamMalformedReason::NON_SYMBOL_NAME_LABEL,
            "name not a symbol"
        );

        // The `label()` projection routes through the typed per-role
        // constants — pinned by string equality against each constant.
        assert_eq!(
            OptionalParamMalformedReason::EmptyList.label(),
            OptionalParamMalformedReason::EMPTY_LIST_LABEL
        );
        assert_eq!(
            OptionalParamMalformedReason::MissingDefault.label(),
            OptionalParamMalformedReason::MISSING_DEFAULT_LABEL
        );
        assert_eq!(
            OptionalParamMalformedReason::NonSymbolName.label(),
            OptionalParamMalformedReason::NON_SYMBOL_NAME_LABEL
        );

        // The dynamic `ExtraElements` arm is EXCLUDED from the static
        // subset — its label is `format!("{length} elements (need 2)")`
        // and cannot bind to a `&'static str` constant. The three
        // per-role constants close the STATIC subset; the fourth arm
        // stays inline at `label()`.
        assert_eq!(
            OptionalParamMalformedReason::ExtraElements { length: 4 }.label(),
            "4 elements (need 2)"
        );

        // Family-wide `STATIC_LABELS` array closes the 3-of-4 carving —
        // `[&'static str; 3]` with rustc-enforced arity.
        assert_eq!(OptionalParamMalformedReason::STATIC_LABELS.len(), 3);
        assert_eq!(
            OptionalParamMalformedReason::STATIC_LABELS,
            [
                OptionalParamMalformedReason::EMPTY_LIST_LABEL,
                OptionalParamMalformedReason::MISSING_DEFAULT_LABEL,
                OptionalParamMalformedReason::NON_SYMBOL_NAME_LABEL,
            ]
        );

        // Pairwise disjointness across the static subset — a future
        // rename that collides `MISSING_DEFAULT_LABEL` onto the
        // `EMPTY_LIST_LABEL` bytes silently merges two distinct
        // rejection wordings into one; the disjointness pin fails-
        // loudly at rustc-test time rather than at silent operator-
        // facing vocabulary fracture.
        let labels = OptionalParamMalformedReason::STATIC_LABELS;
        for i in 0..labels.len() {
            for j in (i + 1)..labels.len() {
                assert_ne!(
                    labels[i], labels[j],
                    "OptionalParamMalformedReason::STATIC_LABELS[{i}] and [{j}] collide on `{}`",
                    labels[i]
                );
            }
        }
    }

    #[test]
    fn optional_param_spec_arity_pins_canonical_accept_target() {
        // The canonical accept-arity of the `&optional (NAME DEFAULT)`
        // list-spec is exactly TWO elements — a symbol head naming the
        // optional plus a default form. Pinning the const here means a
        // regression that bumps the accept-arity (e.g. an evaluator
        // lands and CL's `(name default supplied-p)` shape becomes
        // admissible) MUST also update this pin — which forces the
        // `ExtraElements` label's `"need N"` suffix + every truth-table
        // test's rendered-diagnostic assertion to be re-derived in
        // lockstep rather than silently drifting the accept target from
        // its operator-facing wording.
        assert_eq!(OptionalParamMalformedReason::OPTIONAL_PARAM_SPEC_ARITY, 2);
    }

    #[test]
    fn classify_arity_projects_arity_to_typed_rejection_reason() {
        // The typed classifier closes the arity-to-reason projection at
        // ONE typed function on the algebra — arity 0 → EmptyList,
        // arity 1 → MissingDefault, arity == accept-target → None,
        // arity ≥3 → ExtraElements{length}. The fourth variant
        // NonSymbolName is NOT arity-derivable and stays at the
        // caller's head-symbol gate.
        use OptionalParamMalformedReason as R;
        assert_eq!(R::classify_arity(0), Some(R::EmptyList));
        assert_eq!(R::classify_arity(1), Some(R::MissingDefault));
        // Accept-arity: the classifier returns None because arity alone
        // does not decide the head-symbol gate.
        assert_eq!(R::classify_arity(R::OPTIONAL_PARAM_SPEC_ARITY), None);
        assert_eq!(R::classify_arity(2), None);
        // ExtraElements payload carries the offending arity verbatim so
        // the operator-facing diagnostic can name "N elements (need 2)"
        // exactly. Pin arity-3, arity-4, and arity-17 to close the
        // range of the ≥3 arm.
        assert_eq!(R::classify_arity(3), Some(R::ExtraElements { length: 3 }));
        assert_eq!(R::classify_arity(4), Some(R::ExtraElements { length: 4 }));
        assert_eq!(R::classify_arity(17), Some(R::ExtraElements { length: 17 }));
    }

    #[test]
    fn extra_elements_label_derives_target_arity_from_typed_constant() {
        // The `ExtraElements` arm's dynamic label suffix embeds
        // [`OptionalParamMalformedReason::OPTIONAL_PARAM_SPEC_ARITY`]
        // via `format!("{length} elements (need {})", …)` — pin that a
        // future bump to the accept-arity propagates through the label
        // in lockstep rather than leaving the suffix stuck at the pre-
        // lift literal `2`. The bytes `"3 elements (need 2)"` /
        // `"7 elements (need 2)"` are the current cross-product of
        // (offending arity, accept-arity) values.
        assert_eq!(
            OptionalParamMalformedReason::ExtraElements { length: 3 }.label(),
            "3 elements (need 2)"
        );
        assert_eq!(
            OptionalParamMalformedReason::ExtraElements { length: 7 }.label(),
            "7 elements (need 2)"
        );
        // Cross-check: the `2` in `"need 2"` IS the typed constant, not
        // a bare literal — a rename of the const to a different value
        // fails this assertion with a clear diff.
        assert!(OptionalParamMalformedReason::ExtraElements { length: 3 }
            .label()
            .ends_with(&format!(
                "(need {})",
                OptionalParamMalformedReason::OPTIONAL_PARAM_SPEC_ARITY
            )));
    }

    #[test]
    fn label_static_projects_static_subset_to_typed_option() {
        // The typed STATIC-subset projection carves the 4-arm closed set
        // along the same 3-of-4 axis STATIC_LABELS enumerates — three
        // arms whose diagnostic bytes bind at a `pub const &'static str`
        // (`Some(bytes)`) and one dynamic arm (`ExtraElements`) whose
        // bytes format a `usize` payload (`None`).
        //
        // Pre-lift the STATIC-subset selector was three inline
        // `matches!(reason, EmptyList | MissingDefault | NonSymbolName)`
        // gates duplicated across consumers (`label`'s three static match
        // arms, plus any downstream site that wanted a zero-allocation
        // path over the static subset). Post-lift the carving binds at
        // ONE typed function on the algebra with rustc-enforced exhaust-
        // iveness — a hypothetical fifth static arm extends the match
        // body AND `STATIC_LABELS` in lockstep.
        use OptionalParamMalformedReason as R;
        assert_eq!(R::EmptyList.label_static(), Some(R::EMPTY_LIST_LABEL));
        assert_eq!(
            R::MissingDefault.label_static(),
            Some(R::MISSING_DEFAULT_LABEL)
        );
        assert_eq!(
            R::NonSymbolName.label_static(),
            Some(R::NON_SYMBOL_NAME_LABEL)
        );
        // ExtraElements returns None regardless of the `length` payload —
        // the projection is payload-invariant on the dynamic arm.
        assert_eq!(R::ExtraElements { length: 3 }.label_static(), None);
        assert_eq!(R::ExtraElements { length: 0 }.label_static(), None);
        assert_eq!(R::ExtraElements { length: 42 }.label_static(), None);

        // Composition with `label()`: for every static arm,
        // `label_static().unwrap().to_string() == label()` byte-for-byte
        // — the `label()` body threads through `label_static` for the
        // static subset rather than re-deriving the per-role match arms
        // inline.
        for reason in [R::EmptyList, R::MissingDefault, R::NonSymbolName] {
            assert_eq!(reason.label_static().unwrap().to_string(), reason.label());
        }
    }

    #[test]
    fn label_static_matches_static_labels_array_in_declaration_order() {
        // The three `Some(&'static str)` results, taken in the closed
        // set's declaration order (EmptyList, MissingDefault,
        // NonSymbolName — same order as STATIC_LABELS), equal
        // STATIC_LABELS byte-for-byte. This pins the carving axis: the
        // `label_static` projection and the `STATIC_LABELS` array carve
        // the same 3-of-4 subset in the same order. A future rename that
        // reorders one against the other (e.g. swaps two variants in
        // `label_static`'s match without updating `STATIC_LABELS`) fails
        // here.
        use OptionalParamMalformedReason as R;
        let projected = [
            R::EmptyList.label_static().unwrap(),
            R::MissingDefault.label_static().unwrap(),
            R::NonSymbolName.label_static().unwrap(),
        ];
        assert_eq!(projected, R::STATIC_LABELS);
    }

    #[test]
    fn label_static_composes_with_classify_arity_over_the_3_of_4_carving() {
        // The two typed subset projections carve the same closed set
        // along overlapping 3-of-4 axes:
        //
        //   * `classify_arity(n)` returns `Option<Self>` — `None` at
        //     accept-arity, `Some(reason)` for the 3-of-4 arity-derivable
        //     rejections (EmptyList, MissingDefault, ExtraElements).
        //   * `label_static(reason)` returns `Option<&'static str>` —
        //     `Some(bytes)` for the 3-of-4 static arms (EmptyList,
        //     MissingDefault, NonSymbolName), `None` for ExtraElements.
        //
        // The 2-of-4 intersection (EmptyList, MissingDefault) is the
        // arms both carvings agree on: classify_arity emits them AND
        // label_static gives them a `&'static str`. Composition pins:
        // for arity 0 or 1 the pipeline yields a `Some(&'static str)`.
        use OptionalParamMalformedReason as R;
        assert_eq!(
            R::classify_arity(0).and_then(R::label_static),
            Some(R::EMPTY_LIST_LABEL)
        );
        assert_eq!(
            R::classify_arity(1).and_then(R::label_static),
            Some(R::MISSING_DEFAULT_LABEL)
        );
        // At accept-arity, `classify_arity` returns None — the
        // composition short-circuits.
        assert_eq!(
            R::classify_arity(R::OPTIONAL_PARAM_SPEC_ARITY).and_then(R::label_static),
            None
        );
        // At arity ≥3, `classify_arity` returns
        // `Some(ExtraElements{length})` and `label_static` returns None
        // — the composition also short-circuits, because the two
        // carvings' `None` arms disagree (arity-derivable but NOT
        // static-labeled).
        assert_eq!(R::classify_arity(3).and_then(R::label_static), None);
        assert_eq!(R::classify_arity(17).and_then(R::label_static), None);
    }

    #[test]
    fn label_delegates_static_arms_through_label_static() {
        // The `label()` body composes `label_static()` (the STATIC-subset
        // projection) with an `unwrap_or_else` fallthrough onto the
        // dynamic `ExtraElements` format arm. Pin that the three static
        // arms' `label()` bytes ARE the `label_static()` bytes with a
        // `.to_string()` allocation, and the fourth arm's `label()`
        // bytes ARE the format arm's rendering. A regression that
        // re-inlines the per-role `.to_string()` at `label()` (drifting
        // from the `label_static` composition) still passes the
        // per-variant byte-equality assertions above but fails this
        // composition pin.
        use OptionalParamMalformedReason as R;
        // Static arms — `label()` bytes route through `label_static`.
        for (variant, static_bytes) in [
            (R::EmptyList, R::EMPTY_LIST_LABEL),
            (R::MissingDefault, R::MISSING_DEFAULT_LABEL),
            (R::NonSymbolName, R::NON_SYMBOL_NAME_LABEL),
        ] {
            assert_eq!(variant.label_static(), Some(static_bytes));
            assert_eq!(variant.label(), static_bytes.to_string());
        }
        // Dynamic arm — `label_static()` is None; `label()` falls
        // through to the `ExtraElements` format arm.
        let extra = R::ExtraElements { length: 5 };
        assert_eq!(extra.label_static(), None);
        assert_eq!(
            extra.label(),
            format!("5 elements (need {})", R::OPTIONAL_PARAM_SPEC_ARITY)
        );
    }

    #[test]
    fn optional_param_malformed_reason_extra_elements_descriptor_pins_canonical_noun_bytes() {
        // Pin the per-role `pub const EXTRA_ELEMENTS_DESCRIPTOR` bytes
        // byte-for-byte. The `"elements"` noun IS the shared format
        // template's `{descriptor}` slot binding for the ExtraElements
        // arm — a regression that renames the noun (e.g. to `"items"`
        // for a hypothetical general-list-shape evaluator) surfaces
        // here rather than at silent operator-facing diagnostic drift.
        assert_eq!(
            OptionalParamMalformedReason::EXTRA_ELEMENTS_DESCRIPTOR,
            "elements"
        );
    }

    #[test]
    fn optional_param_malformed_reason_dynamic_descriptors_forced_arity_pins_1_of_4_carving() {
        // Pin `DYNAMIC_DESCRIPTORS.len() == 1` — the DYNAMIC subset of
        // the four-arm closed set carves exactly ONE arm
        // (`ExtraElements`). The peer STATIC subset carves THREE arms
        // (`EmptyList`, `MissingDefault`, `NonSymbolName`). The
        // partition sums to four: 3 + 1 == 4 == R::ALL analogue count.
        assert_eq!(OptionalParamMalformedReason::DYNAMIC_DESCRIPTORS.len(), 1);
        // Element-wise: the single dynamic descriptor equals the per-
        // role const byte-for-byte. Reordering the array against the
        // per-role const fails here.
        assert_eq!(
            OptionalParamMalformedReason::DYNAMIC_DESCRIPTORS,
            [OptionalParamMalformedReason::EXTRA_ELEMENTS_DESCRIPTOR]
        );
    }

    #[test]
    fn descriptor_dynamic_projects_dynamic_subset_to_typed_option() {
        // The typed DYNAMIC-subset projection carves the 4-arm closed
        // set along the same 1-of-4 axis DYNAMIC_DESCRIPTORS
        // enumerates — one arm whose diagnostic bytes format through
        // the shared `"{length} {descriptor} (need {})"` template
        // (`Some(descriptor)`) and three arms whose full bytes bind at
        // a `&'static str` on the STATIC axis (`None`).
        use OptionalParamMalformedReason as R;
        assert_eq!(
            R::ExtraElements { length: 3 }.descriptor_dynamic(),
            Some(R::EXTRA_ELEMENTS_DESCRIPTOR)
        );
        // ExtraElements descriptor is payload-invariant — same
        // descriptor regardless of the `length` payload.
        assert_eq!(
            R::ExtraElements { length: 0 }.descriptor_dynamic(),
            Some(R::EXTRA_ELEMENTS_DESCRIPTOR)
        );
        assert_eq!(
            R::ExtraElements { length: 42 }.descriptor_dynamic(),
            Some(R::EXTRA_ELEMENTS_DESCRIPTOR)
        );
        // STATIC arms return None on the descriptor axis.
        assert_eq!(R::EmptyList.descriptor_dynamic(), None);
        assert_eq!(R::MissingDefault.descriptor_dynamic(), None);
        assert_eq!(R::NonSymbolName.descriptor_dynamic(), None);
    }

    #[test]
    fn descriptor_dynamic_matches_dynamic_descriptors_array_in_declaration_order() {
        // The single `Some(&'static str)` result, taken in the closed
        // set's DYNAMIC declaration order (ExtraElements — same order
        // as DYNAMIC_DESCRIPTORS), equals DYNAMIC_DESCRIPTORS byte-for-
        // byte. Pins the carving axis: the `descriptor_dynamic`
        // projection and the `DYNAMIC_DESCRIPTORS` array carve the
        // same 1-of-4 subset in the same order.
        use OptionalParamMalformedReason as R;
        let projected = [R::ExtraElements { length: 5 }.descriptor_dynamic().unwrap()];
        assert_eq!(projected, R::DYNAMIC_DESCRIPTORS);
    }

    #[test]
    fn label_static_and_descriptor_dynamic_partition_the_closed_set() {
        // Truth-table pin of the STATIC ⊕ DYNAMIC partition contract:
        // for every legal variant, EXACTLY ONE of `label_static(self)`
        // and `descriptor_dynamic(self)` returns `Some`. The two
        // projections carve the four-arm closed set into disjoint
        // covering halves without overlap.
        use OptionalParamMalformedReason as R;
        for reason in [
            R::EmptyList,
            R::MissingDefault,
            R::NonSymbolName,
            R::ExtraElements { length: 3 },
            R::ExtraElements { length: 0 },
            R::ExtraElements { length: 99 },
        ] {
            let static_hit = reason.label_static().is_some();
            let dynamic_hit = reason.descriptor_dynamic().is_some();
            assert!(
                static_hit ^ dynamic_hit,
                "STATIC ⊕ DYNAMIC partition violated for {reason:?}: \
                 label_static={static_hit}, descriptor_dynamic={dynamic_hit}",
            );
        }
    }

    #[test]
    fn label_dynamic_composes_descriptor_arity_and_payload_through_shared_template() {
        // `label_dynamic()` returns `Some(String)` for the DYNAMIC arm
        // formatted through the shared `"{length} {descriptor} (need
        // {})"` template — the descriptor binds to
        // EXTRA_ELEMENTS_DESCRIPTOR, the arity suffix binds to
        // OPTIONAL_PARAM_SPEC_ARITY, and the length binds to the
        // enum's dynamic payload. The three STATIC arms return None.
        use OptionalParamMalformedReason as R;
        assert_eq!(R::EmptyList.label_dynamic(), None);
        assert_eq!(R::MissingDefault.label_dynamic(), None);
        assert_eq!(R::NonSymbolName.label_dynamic(), None);
        // Payload-varying: the `length` slot binds each variant's
        // payload verbatim.
        assert_eq!(
            R::ExtraElements { length: 3 }.label_dynamic(),
            Some("3 elements (need 2)".to_string())
        );
        assert_eq!(
            R::ExtraElements { length: 7 }.label_dynamic(),
            Some("7 elements (need 2)".to_string())
        );
        assert_eq!(
            R::ExtraElements { length: 0 }.label_dynamic(),
            Some("0 elements (need 2)".to_string())
        );
        // Cross-check: the composition threads OPTIONAL_PARAM_SPEC_ARITY
        // rather than a bare `2` literal — a rename of the arity const
        // propagates through this projection in lockstep.
        assert_eq!(
            R::ExtraElements { length: 4 }.label_dynamic().unwrap(),
            format!(
                "4 {} (need {})",
                R::EXTRA_ELEMENTS_DESCRIPTOR,
                R::OPTIONAL_PARAM_SPEC_ARITY
            )
        );
    }

    #[test]
    fn label_composes_static_and_dynamic_projections_over_the_full_partition() {
        // Post-lift `label()` composes `label_static().map(str::to_string)
        // .or_else(|| label_dynamic()).expect(...)` — the STATIC ⊕
        // DYNAMIC partition contract guarantees exactly ONE projection
        // returns `Some` per variant, so the expect arm is
        // structurally unreachable. Pin that every variant's `label()`
        // bytes equal exactly what the composed projection yields.
        use OptionalParamMalformedReason as R;
        for (reason, expected) in [
            (R::EmptyList, R::EMPTY_LIST_LABEL.to_string()),
            (R::MissingDefault, R::MISSING_DEFAULT_LABEL.to_string()),
            (R::NonSymbolName, R::NON_SYMBOL_NAME_LABEL.to_string()),
            (
                R::ExtraElements { length: 3 },
                "3 elements (need 2)".to_string(),
            ),
            (
                R::ExtraElements { length: 42 },
                "42 elements (need 2)".to_string(),
            ),
        ] {
            assert_eq!(reason.label(), expected);
            // Composition pin: `label()` bytes equal whichever
            // projection returned Some.
            let composed = reason
                .label_static()
                .map(str::to_string)
                .or_else(|| reason.label_dynamic())
                .unwrap();
            assert_eq!(reason.label(), composed);
        }
    }

    #[test]
    fn paren_suffix_owns_the_bare_parenthetical_skeleton() {
        // The lowest layer of the suffix-wrapping algebra: one leading space,
        // open paren, body, close paren. A regression that drops the leading
        // space, doubles it, or moves a paren fails here.
        assert_eq!(paren_suffix("got 5"), " (got 5)");
        assert_eq!(paren_suffix(""), " ()");
    }

    #[test]
    fn every_suffix_helper_wraps_through_one_paren_primitive() {
        // All seven `*_suffix` helpers delegate their bare ` (…)` wrapping to
        // `paren_suffix`; only their body-construction stays helper-specific.
        // Pinning that each helper's output EQUALS `paren_suffix` applied with
        // that helper's body means a re-inlined divergent skeleton in ANY of
        // them (e.g. a dropped leading space, a moved paren) fails-loudly.
        // Covers both arms of the multi-arm helpers.

        // unknown_among_suffix — the `did you mean …?; …` join layer.
        assert_eq!(
            unknown_among_suffix(Some(":t"), "allowed: :name"),
            paren_suffix("did you mean :t?; allowed: :name")
        );
        assert_eq!(
            unknown_among_suffix(None, "allowed: :name"),
            paren_suffix("allowed: :name")
        );

        // rest_param_missing_name_suffix — the `rest marker at position …` body.
        assert_eq!(
            rest_param_missing_name_suffix(1, Some("5")),
            paren_suffix("rest marker at position 1, got 5")
        );
        assert_eq!(
            rest_param_missing_name_suffix(1, None),
            paren_suffix("rest marker at position 1, none provided")
        );

        // rest_param_trailing_tokens_suffix — the `… trailing after name` body.
        assert_eq!(
            rest_param_trailing_tokens_suffix(1, 2, "extra"),
            paren_suffix("rest marker at position 1, 2 trailing after name, first: extra")
        );

        // missing_head_symbol_suffix — the `got …` / `empty list` body.
        assert_eq!(missing_head_symbol_suffix(Some("5")), paren_suffix("got 5"));
        assert_eq!(missing_head_symbol_suffix(None), paren_suffix("empty list"));

        // optional_marker_repeated_suffix — the two-marker-position body.
        assert_eq!(
            optional_marker_repeated_suffix(1, 3),
            paren_suffix("first &optional at position 1, second at position 3")
        );

        // optional_param_malformed_suffix — the position+reason-label body.
        // Both `&'static` (the three string-only arms) and formatted
        // (the `ExtraElements{length}` arm) cases route through the same
        // `paren_suffix` wrapping.
        assert_eq!(
            optional_param_malformed_suffix(1, OptionalParamMalformedReason::EmptyList),
            paren_suffix("position 1, empty list")
        );
        assert_eq!(
            optional_param_malformed_suffix(
                2,
                OptionalParamMalformedReason::ExtraElements { length: 3 }
            ),
            paren_suffix("position 2, 3 elements (need 2)")
        );
    }

    #[test]
    fn unknown_kwarg_and_domain_suffixes_share_one_wrapping_primitive() {
        // Both gates delegate their parenthetical wrapping to
        // `unknown_among_suffix`; only the hint-formatting (`:foo` vs
        // `(foo ...)`) and the body-construction (`allowed:` vs `registered:`
        // / `no domains registered`) stay gate-specific. Pinning that each
        // gate's output EQUALS the primitive applied with that gate's
        // formatted hint + body means a re-inlined divergent skeleton in
        // either gate fails-loudly. Covers all four arms: kwarg-with-hint,
        // kwarg-without-hint, domain-with-hint, domain-empty-registry.
        let allowed = vec!["name".to_string(), "threshold".to_string()];
        assert_eq!(
            unknown_kwarg_suffix(Some("threshold"), &allowed),
            unknown_among_suffix(Some(":threshold"), "allowed: :name, :threshold")
        );
        assert_eq!(
            unknown_kwarg_suffix(None, &allowed),
            unknown_among_suffix(None, "allowed: :name, :threshold")
        );

        let registered = vec!["defmonitor".to_string(), "defnotify".to_string()];
        assert_eq!(
            unknown_domain_keyword_suffix(Some("defmonitor"), &registered),
            unknown_among_suffix(
                Some("(defmonitor ...)"),
                "registered: defmonitor, defnotify"
            )
        );
        assert_eq!(
            unknown_domain_keyword_suffix(None, &[]),
            unknown_among_suffix(None, "no domains registered")
        );
    }

    #[test]
    fn non_symbol_unquote_target_display_renders_canonical_type_mismatch_shape() {
        // `,(list 1 2)` — the inner is a list, not a symbol. The variant
        // names the syntactic marker (`,`), the expected shape (`symbol` —
        // the only form a no-evaluator template can substitute), and the
        // offending literal (`(list 1 2)`) as first-class fields. Authoring
        // tools that pattern-match on the variant gain structural binding;
        // tools that substring-match on the rendered diagnostic see a
        // stable shape parallel to the existing `TypeMismatch` variant.
        let err = LispError::NonSymbolUnquoteTarget {
            prefix: UnquoteForm::Unquote,
            got: SexpWitness::new(SexpShape::List, "(list 1 2)"),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in ,: expected symbol, got (list 1 2)"
        );
    }

    #[test]
    fn non_symbol_unquote_target_display_preserves_splice_prefix() {
        // Splice marker rides through the `prefix` field; the rendered
        // diagnostic is `,@`, not `,`. The operator never has to translate
        // `,` ↔ `,@` mentally — same posture as `UnboundTemplateVar`.
        let err = LispError::NonSymbolUnquoteTarget {
            prefix: UnquoteForm::Splice,
            got: SexpWitness::new(SexpShape::Int, "5"),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in ,@: expected symbol, got 5"
        );
    }

    #[test]
    fn non_symbol_unquote_target_display_carries_keyword_atom_unchanged() {
        // `,:foo` — the inner is a keyword atom. The `:foo` form
        // round-trips through `SexpWitness::Display` (writing the
        // `display` field verbatim) into the variant's `got` slot
        // unchanged, so the operator sees what they wrote. The typed
        // `got.shape` slot independently carries `SexpShape::Keyword`
        // so tooling that wants the structural identity binds without
        // re-parsing.
        let err = LispError::NonSymbolUnquoteTarget {
            prefix: UnquoteForm::Unquote,
            got: SexpWitness::new(SexpShape::Keyword, ":foo"),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in ,: expected symbol, got :foo"
        );
    }

    #[test]
    fn splice_outside_list_display_renders_legacy_substring_with_offending_form() {
        // `,@xs` at the body's top level — there is no containing list to
        // splice into. The variant names the offending inner (`xs`) as a
        // first-class typed witness so authoring tools (REPL, LSP,
        // `tatara-check`) gain structural binding to BOTH `got.shape`
        // (typed `SexpShape::Symbol` here) AND `got.display` (the literal
        // `"xs"`); tools that substring-match on the rendered diagnostic
        // still see the legacy `"\`,@\` may only appear inside a list"`
        // substring verbatim because `SexpWitness::Display` writes only
        // the `display` field.
        let err = LispError::SpliceOutsideList {
            got: SexpWitness::new(SexpShape::Symbol, "xs"),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in ,@: `,@` may only appear inside a list (got ,@xs)"
        );
    }

    #[test]
    fn splice_outside_list_display_carries_list_literal_unchanged() {
        // The offending inner is a list literal — `,@(list 1 2)` — so the
        // operator sees the literal value they wrote in the parenthetical,
        // not just a type-name. The typed `SexpShape::List` rides the
        // variant slot alongside the `Sexp::Display` projection; tools
        // can now pattern-match on `got.shape == SexpShape::List`
        // without re-parsing the rendered diagnostic.
        let err = LispError::SpliceOutsideList {
            got: SexpWitness::new(SexpShape::List, "(list 1 2)"),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in ,@: `,@` may only appear inside a list (got ,@(list 1 2))"
        );
    }

    #[test]
    fn splice_outside_list_display_carries_kebab_case_symbol_unchanged() {
        // `,@notify-ref` — kebab-cased symbol round-trips through the
        // variant's `got.display` slot unchanged. Pinning this contract
        // means a regression that camelCases or lowercases the offending
        // form fails-loudly here.
        let err = LispError::SpliceOutsideList {
            got: SexpWitness::new(SexpShape::Symbol, "notify-ref"),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in ,@: `,@` may only appear inside a list (got ,@notify-ref)"
        );
    }

    #[test]
    fn splice_outside_list_display_preserves_legacy_substring_for_message_grep() {
        // Pin the legacy substring as a separate assertion so a regression
        // that drifts the wording (e.g., to "outside a list" or "without a
        // containing list") fails-loudly here even if the parenthetical
        // changes shape. The substring is what consumers downstream
        // (tatara-check, the REPL) substring-match on today.
        let err = LispError::SpliceOutsideList {
            got: SexpWitness::new(SexpShape::Symbol, "xs"),
        };
        let msg = format!("{err}");
        assert!(
            msg.contains("`,@` may only appear inside a list"),
            "expected legacy substring in message, got: {msg}"
        );
        assert!(
            msg.contains("(got ,@xs)"),
            "expected offending-form parenthetical in message, got: {msg}"
        );
    }

    // ── SexpWitness: typed joint-identity lift for offending-Sexp slots ──
    //
    // The `SexpWitness { shape: SexpShape, display: String }` typed
    // primitive lands as the first promotion of a `got: String`
    // Sexp::Display-projection slot to a typed joint identity. Pins:
    // (a) `SexpWitness::Display` writes only the `display` field
    // (byte-for-byte legacy rendering preserved); (b) the struct's
    // `shape` field is pattern-matchable for tooling that wants
    // structural binding without re-parsing the literal; (c) the
    // `SpliceOutsideList.got` slot's typed shape is now load-bearing
    // — a regression that re-collapses `got` to a free-form `String`
    // loses the rustc-enforced typed-shape guarantee.

    #[test]
    fn sexp_witness_display_writes_only_the_display_field() {
        // Pin the byte-for-byte rendering contract: `SexpWitness`'s
        // `Display` impl writes ONLY the `display` field, NOT the
        // shape label. This is the load-bearing posture for the
        // `#[error("...(got ,@{got})")]` annotation on
        // `SpliceOutsideList` — the parenthetical reads `(got ,@xs)`
        // verbatim, not `(got ,@symbol xs)`. A regression that adds
        // a shape prefix to Display fails-loudly here AND at every
        // legacy-rendering test downstream.
        let w = SexpWitness::new(SexpShape::Symbol, "xs");
        assert_eq!(format!("{w}"), "xs");
        let w = SexpWitness::new(SexpShape::List, "(list 1 2)");
        assert_eq!(format!("{w}"), "(list 1 2)");
        let w = SexpWitness::new(SexpShape::Int, "5");
        assert_eq!(format!("{w}"), "5");
        let w = SexpWitness::new(SexpShape::Keyword, ":foo");
        assert_eq!(format!("{w}"), ":foo");
    }

    #[test]
    fn sexp_witness_carries_both_shape_and_display_jointly() {
        // Pin the joint-identity contract: `SexpWitness` carries BOTH
        // halves of the offending-value identity (typed `SexpShape`
        // AND literal `Sexp::Display` projection) in ONE owned value.
        // Tools that pattern-match on `witness.shape` bind to the
        // structural identity; tools that render via `{witness}` get
        // the literal value. Neither half is recoverable from the
        // other (a `Sexp::Display` projection of `"5"` could be Int
        // or Symbol — substring parsing can't recover the structural
        // identity reliably), so the typed witness is the canonical
        // source for both.
        let w = SexpWitness::new(SexpShape::Int, "5");
        assert_eq!(w.shape, SexpShape::Int);
        assert_eq!(w.display, "5");
        // The literal `"5"` would substring-grep the same as a hand-
        // written symbol named `5`, but the typed shape distinguishes
        // them structurally — a regression that drops the shape slot
        // would collapse this distinction.
        let w_sym = SexpWitness::new(SexpShape::Symbol, "5");
        assert_eq!(w_sym.shape, SexpShape::Symbol);
        assert_eq!(w_sym.display, "5");
        assert_ne!(
            w, w_sym,
            "Witnesses with same display but different shape must NOT be equal — typed shape is load-bearing data",
        );
    }

    #[test]
    fn splice_outside_list_got_carries_typed_witness_through_variant_slot() {
        // Pin the structural binding on `LispError::SpliceOutsideList.got`
        // — a regression that re-introduces a `String`-shaped got slot
        // (collapsing the typed witness back into a free-form literal)
        // fails-loudly here. After this lift the variant's typed slot
        // is the joint `SexpWitness` identity; the Display projection
        // through `SexpWitness::Display` writes only the `display`
        // field so the rendered `(got ,@<display>)` parenthetical is
        // byte-for-byte identical to the legacy `got: String` shape.
        let err = LispError::SpliceOutsideList {
            got: SexpWitness::new(SexpShape::List, "(list 1 2)"),
        };
        match &err {
            LispError::SpliceOutsideList { got } => {
                assert_eq!(got.shape, SexpShape::List);
                assert_eq!(got.display, "(list 1 2)");
            }
            other => panic!("expected SpliceOutsideList, got {other:?}"),
        }
        assert_eq!(
            format!("{err}"),
            "compile error in ,@: `,@` may only appear inside a list (got ,@(list 1 2))"
        );
    }

    #[test]
    fn splice_outside_list_got_distinguishes_symbol_from_list_at_variant_slot() {
        // Pin the typed-shape bifurcation at the variant slot: a
        // `,@xs` (symbol unquote-splice outside list) and a `,@(list 1 2)`
        // (list-literal unquote-splice outside list) BOTH route to
        // `SpliceOutsideList`, but the typed `got.shape` slot
        // distinguishes them structurally — `SexpShape::Symbol` vs.
        // `SexpShape::List`. A regression that erases the typed
        // shape (e.g., reverts to `got: String`) would lose this
        // distinction — tooling that wants to surface "you wrote a
        // symbol `,@xs` outside a list; bind `xs` to a list first"
        // vs. "you wrote a list literal `,@(list 1 2)` outside a
        // list; nest it inside `(outer ,@(...))`" would have to
        // substring-grep the `display` field, brittle.
        let err_sym = LispError::SpliceOutsideList {
            got: SexpWitness::new(SexpShape::Symbol, "xs"),
        };
        let err_list = LispError::SpliceOutsideList {
            got: SexpWitness::new(SexpShape::List, "(list 1 2)"),
        };
        let (sym_shape, list_shape) = (
            match &err_sym {
                LispError::SpliceOutsideList { got } => got.shape,
                _ => unreachable!(),
            },
            match &err_list {
                LispError::SpliceOutsideList { got } => got.shape,
                _ => unreachable!(),
            },
        );
        assert_ne!(
            sym_shape, list_shape,
            "Symbol and List witnesses must remain structurally distinct at the variant slot",
        );
        assert_eq!(sym_shape, SexpShape::Symbol);
        assert_eq!(list_shape, SexpShape::List);
    }

    #[test]
    fn non_symbol_unquote_target_got_carries_typed_witness_through_variant_slot() {
        // Sibling pin to
        // `splice_outside_list_got_carries_typed_witness_through_variant_slot`
        // for the template-gate's OTHER `,X/,@X` rejection variant.
        // After this lift `LispError::NonSymbolUnquoteTarget.got` is
        // the typed joint `SexpWitness` identity — the same
        // primitive `SpliceOutsideList.got` already carries. The two
        // template-gate `,X/,@X` rejection variants now share ONE
        // typed witness identity at their `got` slot; authoring tools
        // bind on `got.shape` AND `got.display` jointly across both
        // sites rather than substring-grepping a free-form String on
        // each. A regression that re-collapses `got` to `String` loses
        // the rustc-enforced closed-set guarantee on shape identity
        // here.
        let err = LispError::NonSymbolUnquoteTarget {
            prefix: UnquoteForm::Unquote,
            got: SexpWitness::new(SexpShape::List, "(list 1 2)"),
        };
        match &err {
            LispError::NonSymbolUnquoteTarget { prefix, got } => {
                assert_eq!(*prefix, UnquoteForm::Unquote);
                assert_eq!(got.shape, SexpShape::List);
                assert_eq!(got.display, "(list 1 2)");
            }
            other => panic!("expected NonSymbolUnquoteTarget, got {other:?}"),
        }
        assert_eq!(
            format!("{err}"),
            "compile error in ,: expected symbol, got (list 1 2)"
        );
    }

    #[test]
    fn non_symbol_unquote_target_got_distinguishes_int_from_keyword_at_variant_slot() {
        // Pin the typed-shape bifurcation at the variant slot — `,5`
        // (int atom in unquote slot) and `,:foo` (keyword atom in
        // unquote slot) BOTH route to `NonSymbolUnquoteTarget`, but
        // the typed `got.shape` slot distinguishes them structurally
        // — `SexpShape::Int` vs. `SexpShape::Keyword`. Sibling pin
        // for the same structural-shape-bifurcation property
        // `splice_outside_list_got_distinguishes_symbol_from_list_at_variant_slot`
        // pins on `SpliceOutsideList`. A regression that erases the
        // typed shape (e.g., reverts to `got: String`) would lose
        // this distinction — tooling that wants to surface "you wrote
        // an int `,5` where a symbol was expected; only symbols are
        // substitutable in templates" vs. "you wrote a keyword `,:foo`
        // where a symbol was expected; keywords aren't substitutable
        // (did you mean `,foo`?)" would have to substring-grep the
        // `display` field, brittle.
        let err_int = LispError::NonSymbolUnquoteTarget {
            prefix: UnquoteForm::Unquote,
            got: SexpWitness::new(SexpShape::Int, "5"),
        };
        let err_kw = LispError::NonSymbolUnquoteTarget {
            prefix: UnquoteForm::Unquote,
            got: SexpWitness::new(SexpShape::Keyword, ":foo"),
        };
        let (int_shape, kw_shape) = (
            match &err_int {
                LispError::NonSymbolUnquoteTarget { got, .. } => got.shape,
                _ => unreachable!(),
            },
            match &err_kw {
                LispError::NonSymbolUnquoteTarget { got, .. } => got.shape,
                _ => unreachable!(),
            },
        );
        assert_ne!(
            int_shape, kw_shape,
            "Int and Keyword witnesses must remain structurally distinct at the variant slot",
        );
        assert_eq!(int_shape, SexpShape::Int);
        assert_eq!(kw_shape, SexpShape::Keyword);
    }

    #[test]
    fn non_symbol_unquote_target_and_splice_outside_list_share_one_witness_primitive() {
        // Pin that BOTH template-gate `,X/,@X` rejection variants
        // (`NonSymbolUnquoteTarget` AND `SpliceOutsideList`) carry
        // the SAME typed `SexpWitness` primitive at their `got` slot
        // — the closed set of "offending inner Sexp" identities is
        // bound by ONE typed primitive across both rejection
        // surfaces. A regression that diverges the slot type on one
        // variant (e.g., re-collapses NonSymbolUnquoteTarget.got to
        // String while leaving SpliceOutsideList.got as
        // SexpWitness) fails-loudly here because the assignment
        // round-trips the witness across both slot types.
        let same_witness = SexpWitness::new(SexpShape::List, "(list 1 2)");
        let non_symbol_target = LispError::NonSymbolUnquoteTarget {
            prefix: UnquoteForm::Splice,
            got: same_witness.clone(),
        };
        let splice_outside = LispError::SpliceOutsideList {
            got: same_witness.clone(),
        };
        match (&non_symbol_target, &splice_outside) {
            (
                LispError::NonSymbolUnquoteTarget { got: lhs_got, .. },
                LispError::SpliceOutsideList { got: rhs_got },
            ) => {
                assert_eq!(lhs_got.shape, rhs_got.shape);
                assert_eq!(lhs_got.display, rhs_got.display);
                assert_eq!(*lhs_got, same_witness);
                assert_eq!(*rhs_got, same_witness);
            }
            _ => unreachable!(),
        }
    }

    #[test]
    fn non_symbol_param_got_carries_typed_witness_through_variant_slot() {
        // Pin the structural binding AND the Display projection on
        // `LispError::NonSymbolParam.got`. After this lift the variant's
        // typed slot is the joint `SexpWitness` identity — the same
        // primitive `SpliceOutsideList.got` and
        // `NonSymbolUnquoteTarget.got` already carry. A regression that
        // re-collapses `got` to `String` (losing the rustc-enforced
        // closed-set guarantee on shape identity) fails-loudly here.
        // The Display projection through `SexpWitness::Display` writes
        // only the `display` field so the rendered `at position X, got
        // <display>` clause is byte-for-byte identical to the legacy
        // `got: String` shape; downstream substring-grep consumers
        // (`tatara-check`, REPL) see no drift.
        let err = LispError::NonSymbolParam {
            position: 1,
            got: SexpWitness::new(SexpShape::Int, "5"),
        };
        match &err {
            LispError::NonSymbolParam { position, got } => {
                assert_eq!(*position, 1);
                assert_eq!(got.shape, SexpShape::Int);
                assert_eq!(got.display, "5");
            }
            other => panic!("expected NonSymbolParam, got {other:?}"),
        }
        assert_eq!(
            format!("{err}"),
            "compile error in defmacro params: expected symbol at \
             position 1, got 5"
        );
    }

    #[test]
    fn non_symbol_param_got_distinguishes_int_from_keyword_at_variant_slot() {
        // Pin the typed-shape bifurcation at the variant slot — `5`
        // (int atom at a param-list position) and `:foo` (keyword atom
        // at a param-list position) BOTH route to `NonSymbolParam`, but
        // the typed `got.shape` slot distinguishes them structurally —
        // `SexpShape::Int` vs. `SexpShape::Keyword`. Sibling pin for
        // the same structural-shape-bifurcation property
        // `non_symbol_unquote_target_got_distinguishes_int_from_keyword_at_variant_slot`
        // pins on `NonSymbolUnquoteTarget`. A regression that erases
        // the typed shape (e.g., reverts to `got: String`) would lose
        // this distinction — tooling that wants to surface "you wrote
        // an int `5` where a symbol was expected at param-list position
        // 0" vs. "you wrote a keyword `:foo` where a symbol was expected
        // at param-list position 0 (did you mean `foo`?)" would have to
        // substring-grep the `display` field, brittle.
        let err_int = LispError::NonSymbolParam {
            position: 0,
            got: SexpWitness::new(SexpShape::Int, "5"),
        };
        let err_kw = LispError::NonSymbolParam {
            position: 0,
            got: SexpWitness::new(SexpShape::Keyword, ":foo"),
        };
        let (int_shape, kw_shape) = (
            match &err_int {
                LispError::NonSymbolParam { got, .. } => got.shape,
                _ => unreachable!(),
            },
            match &err_kw {
                LispError::NonSymbolParam { got, .. } => got.shape,
                _ => unreachable!(),
            },
        );
        assert_ne!(
            int_shape, kw_shape,
            "Int and Keyword witnesses must remain structurally distinct at the variant slot",
        );
        assert_eq!(int_shape, SexpShape::Int);
        assert_eq!(kw_shape, SexpShape::Keyword);
    }

    #[test]
    fn non_symbol_param_and_template_gate_share_one_witness_primitive() {
        // Pin that ALL THREE Sexp-display-source `got` slots in the
        // substrate (`NonSymbolParam`, `NonSymbolUnquoteTarget`,
        // `SpliceOutsideList`) carry the SAME typed `SexpWitness`
        // primitive — the closed set of "offending inner Sexp"
        // identities is bound by ONE typed primitive across the three
        // rejection surfaces (the defmacro-syntax-gate's `parse_params`
        // walker AND the template-gate's `,X/,@X` pair). A regression
        // that diverges the slot type on any one variant (e.g.,
        // re-collapses `NonSymbolParam.got` to `String` while leaving
        // the template-gate variants typed) fails-loudly here because
        // the assignment round-trips the witness across all three slot
        // types. Sibling pin to
        // `non_symbol_unquote_target_and_splice_outside_list_share_one_witness_primitive`
        // — extending the typed-identity unification contract from
        // two slots to three.
        let same_witness = SexpWitness::new(SexpShape::List, "(nested)");
        let non_symbol_param = LispError::NonSymbolParam {
            position: 0,
            got: same_witness.clone(),
        };
        let non_symbol_target = LispError::NonSymbolUnquoteTarget {
            prefix: UnquoteForm::Unquote,
            got: same_witness.clone(),
        };
        let splice_outside = LispError::SpliceOutsideList {
            got: same_witness.clone(),
        };
        match (&non_symbol_param, &non_symbol_target, &splice_outside) {
            (
                LispError::NonSymbolParam { got: a, .. },
                LispError::NonSymbolUnquoteTarget { got: b, .. },
                LispError::SpliceOutsideList { got: c },
            ) => {
                assert_eq!(a.shape, b.shape);
                assert_eq!(b.shape, c.shape);
                assert_eq!(a.display, b.display);
                assert_eq!(b.display, c.display);
                assert_eq!(*a, same_witness);
                assert_eq!(*b, same_witness);
                assert_eq!(*c, same_witness);
            }
            _ => unreachable!(),
        }
    }

    #[test]
    fn defmacro_non_symbol_name_got_carries_typed_witness_through_variant_slot() {
        // Pin the structural binding AND the Display projection on
        // `LispError::DefmacroNonSymbolName.got`. After this lift the
        // variant's typed slot is the joint `SexpWitness` identity —
        // the same primitive `SpliceOutsideList.got`,
        // `NonSymbolUnquoteTarget.got`, and `NonSymbolParam.got`
        // already carry. A regression that re-collapses `got` to
        // `String` (losing the rustc-enforced closed-set guarantee on
        // shape identity at the defmacro-syntax-gate's name-slot
        // rejection variant) fails-loudly here. The Display projection
        // through `SexpWitness::Display` writes only the `display`
        // field so the rendered `compile error in {head}: expected
        // name symbol, got <display>` clause is byte-for-byte
        // identical to the legacy `got: String` shape; downstream
        // substring-grep consumers (`tatara-check`, REPL) see no
        // drift.
        let err = LispError::DefmacroNonSymbolName {
            head: MacroDefHead::Defmacro,
            got: SexpWitness::new(SexpShape::Int, "5"),
        };
        match &err {
            LispError::DefmacroNonSymbolName { head, got } => {
                assert_eq!(*head, MacroDefHead::Defmacro);
                assert_eq!(got.shape, SexpShape::Int);
                assert_eq!(got.display, "5");
            }
            other => panic!("expected DefmacroNonSymbolName, got {other:?}"),
        }
        assert_eq!(
            format!("{err}"),
            "compile error in defmacro: expected name symbol, got 5"
        );
    }

    #[test]
    fn defmacro_non_symbol_name_got_distinguishes_int_from_keyword_at_variant_slot() {
        // Pin the typed-shape bifurcation at the variant slot — `5`
        // (int atom at the defmacro name slot) and `:foo` (keyword
        // atom at the defmacro name slot) BOTH route to
        // `DefmacroNonSymbolName`, but the typed `got.shape` slot
        // distinguishes them structurally — `SexpShape::Int`
        // vs. `SexpShape::Keyword`. Sibling pin for the same
        // structural-shape-bifurcation property
        // `non_symbol_param_got_distinguishes_int_from_keyword_at_variant_slot`
        // pins on `NonSymbolParam` and
        // `non_symbol_unquote_target_got_distinguishes_int_from_keyword_at_variant_slot`
        // pins on `NonSymbolUnquoteTarget`. A regression that erases
        // the typed shape (e.g., reverts to `got: String`) would lose
        // this distinction — tooling that wants to surface "you wrote
        // an int `5` where a name symbol was expected" vs. "you wrote
        // a keyword `:foo` where a name symbol was expected (did you
        // mean `foo`?)" would have to substring-grep the `display`
        // field, brittle.
        let err_int = LispError::DefmacroNonSymbolName {
            head: MacroDefHead::Defmacro,
            got: SexpWitness::new(SexpShape::Int, "5"),
        };
        let err_kw = LispError::DefmacroNonSymbolName {
            head: MacroDefHead::Defmacro,
            got: SexpWitness::new(SexpShape::Keyword, ":foo"),
        };
        let (int_shape, kw_shape) = (
            match &err_int {
                LispError::DefmacroNonSymbolName { got, .. } => got.shape,
                _ => unreachable!(),
            },
            match &err_kw {
                LispError::DefmacroNonSymbolName { got, .. } => got.shape,
                _ => unreachable!(),
            },
        );
        assert_ne!(
            int_shape, kw_shape,
            "Int and Keyword witnesses must remain structurally distinct at the variant slot",
        );
        assert_eq!(int_shape, SexpShape::Int);
        assert_eq!(kw_shape, SexpShape::Keyword);
    }

    #[test]
    fn defmacro_non_symbol_name_and_param_gate_share_one_witness_primitive() {
        // Pin that ALL FOUR Sexp-display-source `got` slots in the
        // substrate (`SpliceOutsideList`, `NonSymbolUnquoteTarget`,
        // `NonSymbolParam`, `DefmacroNonSymbolName`) carry the SAME
        // typed `SexpWitness` primitive — the closed set of
        // "offending inner Sexp" identities is bound by ONE typed
        // primitive across FOUR rejection surfaces: the
        // template-gate's `,X/,@X` pair, the defmacro-syntax-gate's
        // `parse_params` walker, AND the defmacro-syntax-gate's
        // outer name-slot rejection. A regression that diverges the
        // slot type on any one variant (e.g., re-collapses
        // `DefmacroNonSymbolName.got` to `String` while leaving the
        // others typed) fails-loudly here because the assignment
        // round-trips the witness across all four slot types. Sibling
        // pin to `non_symbol_param_and_template_gate_share_one_witness_primitive`
        // — extending the typed-identity unification contract from
        // three slots to four.
        let same_witness = SexpWitness::new(SexpShape::List, "(nested)");
        let defmacro_non_symbol_name = LispError::DefmacroNonSymbolName {
            head: MacroDefHead::Defmacro,
            got: same_witness.clone(),
        };
        let non_symbol_param = LispError::NonSymbolParam {
            position: 0,
            got: same_witness.clone(),
        };
        let non_symbol_target = LispError::NonSymbolUnquoteTarget {
            prefix: UnquoteForm::Unquote,
            got: same_witness.clone(),
        };
        let splice_outside = LispError::SpliceOutsideList {
            got: same_witness.clone(),
        };
        match (
            &defmacro_non_symbol_name,
            &non_symbol_param,
            &non_symbol_target,
            &splice_outside,
        ) {
            (
                LispError::DefmacroNonSymbolName { got: a, .. },
                LispError::NonSymbolParam { got: b, .. },
                LispError::NonSymbolUnquoteTarget { got: c, .. },
                LispError::SpliceOutsideList { got: d },
            ) => {
                assert_eq!(a.shape, b.shape);
                assert_eq!(b.shape, c.shape);
                assert_eq!(c.shape, d.shape);
                assert_eq!(a.display, b.display);
                assert_eq!(b.display, c.display);
                assert_eq!(c.display, d.display);
                assert_eq!(*a, same_witness);
                assert_eq!(*b, same_witness);
                assert_eq!(*c, same_witness);
                assert_eq!(*d, same_witness);
            }
            _ => unreachable!(),
        }
    }

    #[test]
    fn defmacro_non_list_params_got_carries_typed_witness_through_variant_slot() {
        // Pin the structural binding AND the Display projection on
        // `LispError::DefmacroNonListParams.got`. After this lift the
        // variant's typed slot is the joint `SexpWitness` identity —
        // the same primitive `SpliceOutsideList.got`,
        // `NonSymbolUnquoteTarget.got`, `NonSymbolParam.got`, and
        // `DefmacroNonSymbolName.got` already carry. A regression that
        // re-collapses `got` to `String` (losing the rustc-enforced
        // closed-set guarantee on shape identity at the defmacro-
        // syntax-gate's param-list-slot rejection variant) fails-loudly
        // here. The Display projection through `SexpWitness::Display`
        // writes only the `display` field so the rendered `compile
        // error in {head}: expected param list, got <display>` clause
        // is byte-for-byte identical to the legacy `got: String`
        // shape; downstream substring-grep consumers (`tatara-check`,
        // REPL) see no drift.
        let err = LispError::DefmacroNonListParams {
            head: MacroDefHead::Defmacro,
            got: SexpWitness::new(SexpShape::Symbol, "x"),
        };
        match &err {
            LispError::DefmacroNonListParams { head, got } => {
                assert_eq!(*head, MacroDefHead::Defmacro);
                assert_eq!(got.shape, SexpShape::Symbol);
                assert_eq!(got.display, "x");
            }
            other => panic!("expected DefmacroNonListParams, got {other:?}"),
        }
        assert_eq!(
            format!("{err}"),
            "compile error in defmacro: expected param list, got x"
        );
    }

    #[test]
    fn defmacro_non_list_params_got_distinguishes_symbol_from_int_at_variant_slot() {
        // Pin the typed-shape bifurcation at the variant slot — `x`
        // (symbol atom at the defmacro param-list slot) and `5`
        // (int atom at the defmacro param-list slot) BOTH route to
        // `DefmacroNonListParams`, but the typed `got.shape` slot
        // distinguishes them structurally — `SexpShape::Symbol`
        // vs. `SexpShape::Int`. Sibling pin for the same
        // structural-shape-bifurcation property
        // `defmacro_non_symbol_name_got_distinguishes_int_from_keyword_at_variant_slot`
        // pins on `DefmacroNonSymbolName` and
        // `non_symbol_param_got_distinguishes_int_from_keyword_at_variant_slot`
        // pins on `NonSymbolParam`. A regression that erases the typed
        // shape (e.g., reverts to `got: String`) would lose this
        // distinction — tooling that wants to surface "you wrote a
        // symbol `x` where a param list was expected (did you mean
        // `(x)`?)" vs. "you wrote an int `5` where a param list was
        // expected" would have to substring-grep the `display` field,
        // brittle. The symbol-vs-int bifurcation matters at THIS slot
        // (not the int-vs-keyword bifurcation pinned at the
        // name-slot variant) because the most common authoring
        // mistake at the param-list slot is to forget the wrapping
        // parens — `(defmacro f x body)` instead of `(defmacro f (x)
        // body)` — so the symbol shape is the natural sibling to
        // distinguish from numeric typos.
        let err_sym = LispError::DefmacroNonListParams {
            head: MacroDefHead::Defmacro,
            got: SexpWitness::new(SexpShape::Symbol, "x"),
        };
        let err_int = LispError::DefmacroNonListParams {
            head: MacroDefHead::Defmacro,
            got: SexpWitness::new(SexpShape::Int, "5"),
        };
        let (sym_shape, int_shape) = (
            match &err_sym {
                LispError::DefmacroNonListParams { got, .. } => got.shape,
                _ => unreachable!(),
            },
            match &err_int {
                LispError::DefmacroNonListParams { got, .. } => got.shape,
                _ => unreachable!(),
            },
        );
        assert_ne!(
            sym_shape, int_shape,
            "Symbol and Int witnesses must remain structurally distinct at the variant slot",
        );
        assert_eq!(sym_shape, SexpShape::Symbol);
        assert_eq!(int_shape, SexpShape::Int);
    }

    #[test]
    fn defmacro_non_list_params_and_name_gate_share_one_witness_primitive() {
        // Pin that ALL FIVE Sexp-display-source `got` slots in the
        // substrate (`SpliceOutsideList`, `NonSymbolUnquoteTarget`,
        // `NonSymbolParam`, `DefmacroNonSymbolName`,
        // `DefmacroNonListParams`) carry the SAME typed `SexpWitness`
        // primitive — the closed set of "offending inner Sexp"
        // identities is bound by ONE typed primitive across FIVE
        // rejection surfaces: the template-gate's `,X/,@X` pair, the
        // defmacro-syntax-gate's `parse_params` walker, AND BOTH of
        // the defmacro-syntax-gate's outer `macro_def_from` rejection
        // points (name-symbol AND param-list — the second and third of
        // the three `macro_def_from` gates). A regression that
        // diverges the slot type on any one variant (e.g., re-collapses
        // `DefmacroNonListParams.got` to `String` while leaving the
        // others typed) fails-loudly here because the assignment
        // round-trips the witness across all five slot types. Sibling
        // pin to `defmacro_non_symbol_name_and_param_gate_share_one_witness_primitive`
        // — extending the typed-identity unification contract from
        // four slots to five, completing structural unification of the
        // entire `macro_def_from` rejection chain at the
        // `Sexp::Display`-source `got` slot (every offending inner
        // Sexp value that `macro_def_from` rejects now carries the
        // SAME typed witness, regardless of which of the three gates
        // — arity, name-symbol, param-list — fired).
        let same_witness = SexpWitness::new(SexpShape::List, "(nested)");
        let defmacro_non_list_params = LispError::DefmacroNonListParams {
            head: MacroDefHead::Defmacro,
            got: same_witness.clone(),
        };
        let defmacro_non_symbol_name = LispError::DefmacroNonSymbolName {
            head: MacroDefHead::Defmacro,
            got: same_witness.clone(),
        };
        let non_symbol_param = LispError::NonSymbolParam {
            position: 0,
            got: same_witness.clone(),
        };
        let non_symbol_target = LispError::NonSymbolUnquoteTarget {
            prefix: UnquoteForm::Unquote,
            got: same_witness.clone(),
        };
        let splice_outside = LispError::SpliceOutsideList {
            got: same_witness.clone(),
        };
        match (
            &defmacro_non_list_params,
            &defmacro_non_symbol_name,
            &non_symbol_param,
            &non_symbol_target,
            &splice_outside,
        ) {
            (
                LispError::DefmacroNonListParams { got: a, .. },
                LispError::DefmacroNonSymbolName { got: b, .. },
                LispError::NonSymbolParam { got: c, .. },
                LispError::NonSymbolUnquoteTarget { got: d, .. },
                LispError::SpliceOutsideList { got: e },
            ) => {
                assert_eq!(a.shape, b.shape);
                assert_eq!(b.shape, c.shape);
                assert_eq!(c.shape, d.shape);
                assert_eq!(d.shape, e.shape);
                assert_eq!(a.display, b.display);
                assert_eq!(b.display, c.display);
                assert_eq!(c.display, d.display);
                assert_eq!(d.display, e.display);
                assert_eq!(*a, same_witness);
                assert_eq!(*b, same_witness);
                assert_eq!(*c, same_witness);
                assert_eq!(*d, same_witness);
                assert_eq!(*e, same_witness);
            }
            _ => unreachable!(),
        }
    }

    #[test]
    fn rest_param_missing_name_got_carries_typed_witness_through_variant_slot() {
        // Pin the structural binding AND the Display projection on
        // `LispError::RestParamMissingName.got`. After this lift the
        // variant's typed slot is `Option<SexpWitness>` — the joint
        // `SexpWitness` identity (the same primitive `SpliceOutsideList.got`,
        // `NonSymbolUnquoteTarget.got`, `NonSymbolParam.got`,
        // `DefmacroNonSymbolName.got`, and `DefmacroNonListParams.got`
        // already carry) wrapped in `Option` because the post-`&rest`
        // follower slot bifurcates structurally between "missing
        // entirely" (`None`) and "present but malformed"
        // (`Some(SexpWitness)`). The typed witness lands on the `Some`
        // arm only. A regression that re-collapses to a free-form
        // `Option<String>` got slot (losing the rustc-enforced
        // closed-set guarantee on shape identity at the
        // `parse_params` walker's `&rest`-follower rejection variant)
        // fails-loudly here. The Display projection through
        // `SexpWitness::Display` writes only the `display` field so
        // the rendered `(rest marker at position {rest_position}, got
        // <display>)` clause is byte-for-byte identical to the
        // pre-lift `Option<String>` shape; downstream substring-grep
        // consumers (`tatara-check`, REPL) see no drift.
        let err = LispError::RestParamMissingName {
            rest_position: 1,
            got: Some(SexpWitness::new(SexpShape::Int, "5")),
        };
        match &err {
            LispError::RestParamMissingName { rest_position, got } => {
                assert_eq!(*rest_position, 1);
                let witness = got.as_ref().expect("got must be Some");
                assert_eq!(witness.shape, SexpShape::Int);
                assert_eq!(witness.display, "5");
            }
            other => panic!("expected RestParamMissingName, got {other:?}"),
        }
        assert_eq!(
            format!("{err}"),
            "compile error in defmacro params: &rest needs a name \
             (rest marker at position 1, got 5)"
        );
    }

    #[test]
    fn rest_param_missing_name_got_distinguishes_int_from_keyword_at_variant_slot() {
        // Pin the typed-shape bifurcation at the variant slot — `5`
        // (int atom at the post-`&rest` follower slot) and `:foo`
        // (keyword atom at the post-`&rest` follower slot) BOTH route
        // to `RestParamMissingName` on the `Some` arm, but the typed
        // `got.shape` slot distinguishes them structurally —
        // `SexpShape::Int` vs. `SexpShape::Keyword`. Sibling pin for
        // the same structural-shape-bifurcation property
        // `non_symbol_param_got_distinguishes_int_from_keyword_at_variant_slot`
        // pins on `NonSymbolParam` and
        // `defmacro_non_symbol_name_got_distinguishes_int_from_keyword_at_variant_slot`
        // pins on `DefmacroNonSymbolName`. A regression that erases
        // the typed shape (e.g., reverts to `got: Option<String>`)
        // would lose this distinction — tooling that wants to surface
        // "you wrote an int `5` where a rest-name was expected" vs.
        // "you wrote a keyword `:foo` where a rest-name was expected
        // (did you mean `foo`?)" would have to substring-grep the
        // `display` field, brittle.
        let err_int = LispError::RestParamMissingName {
            rest_position: 0,
            got: Some(SexpWitness::new(SexpShape::Int, "5")),
        };
        let err_kw = LispError::RestParamMissingName {
            rest_position: 0,
            got: Some(SexpWitness::new(SexpShape::Keyword, ":foo")),
        };
        let (int_shape, kw_shape) = (
            match &err_int {
                LispError::RestParamMissingName { got: Some(w), .. } => w.shape,
                _ => unreachable!(),
            },
            match &err_kw {
                LispError::RestParamMissingName { got: Some(w), .. } => w.shape,
                _ => unreachable!(),
            },
        );
        assert_ne!(
            int_shape, kw_shape,
            "Int and Keyword witnesses must remain structurally distinct at the variant slot",
        );
        assert_eq!(int_shape, SexpShape::Int);
        assert_eq!(kw_shape, SexpShape::Keyword);
    }

    #[test]
    fn rest_param_missing_name_and_macro_def_gate_share_one_witness_primitive() {
        // Pin that ALL SIX Sexp-display-source `got` slots in the
        // substrate (`SpliceOutsideList`, `NonSymbolUnquoteTarget`,
        // `NonSymbolParam`, `DefmacroNonSymbolName`,
        // `DefmacroNonListParams`, `RestParamMissingName`) carry the
        // SAME typed `SexpWitness` primitive — the closed set of
        // "offending inner Sexp" identities is bound by ONE typed
        // primitive across SIX rejection surfaces: the template-gate's
        // `,X/,@X` pair, the defmacro-syntax-gate's `parse_params`
        // walker (BOTH non-symbol-param AND post-`&rest`-non-symbol-
        // follower rejection points), AND BOTH of the
        // defmacro-syntax-gate's outer `macro_def_from` rejection
        // points (name-symbol AND param-list). The `Option`-wrap on
        // `RestParamMissingName.got` is the bifurcation between
        // "missing entirely" and "present but malformed"; the typed
        // witness rides on the `Some` arm and is structurally identical
        // to the other five variants' got slots. A regression that
        // diverges the slot type on any one variant (e.g., re-collapses
        // `RestParamMissingName.got` to `Option<String>` while leaving
        // the others typed) fails-loudly here because the assignment
        // round-trips the witness across all six slot types. Sibling
        // pin to
        // `defmacro_non_list_params_and_name_gate_share_one_witness_primitive`
        // — extending the typed-identity unification contract from
        // five slots to six.
        let same_witness = SexpWitness::new(SexpShape::List, "(nested)");
        let rest_param_missing_name = LispError::RestParamMissingName {
            rest_position: 0,
            got: Some(same_witness.clone()),
        };
        let defmacro_non_list_params = LispError::DefmacroNonListParams {
            head: MacroDefHead::Defmacro,
            got: same_witness.clone(),
        };
        let defmacro_non_symbol_name = LispError::DefmacroNonSymbolName {
            head: MacroDefHead::Defmacro,
            got: same_witness.clone(),
        };
        let non_symbol_param = LispError::NonSymbolParam {
            position: 0,
            got: same_witness.clone(),
        };
        let non_symbol_target = LispError::NonSymbolUnquoteTarget {
            prefix: UnquoteForm::Unquote,
            got: same_witness.clone(),
        };
        let splice_outside = LispError::SpliceOutsideList {
            got: same_witness.clone(),
        };
        match (
            &rest_param_missing_name,
            &defmacro_non_list_params,
            &defmacro_non_symbol_name,
            &non_symbol_param,
            &non_symbol_target,
            &splice_outside,
        ) {
            (
                LispError::RestParamMissingName { got: Some(a), .. },
                LispError::DefmacroNonListParams { got: b, .. },
                LispError::DefmacroNonSymbolName { got: c, .. },
                LispError::NonSymbolParam { got: d, .. },
                LispError::NonSymbolUnquoteTarget { got: e, .. },
                LispError::SpliceOutsideList { got: f },
            ) => {
                assert_eq!(a.shape, b.shape);
                assert_eq!(b.shape, c.shape);
                assert_eq!(c.shape, d.shape);
                assert_eq!(d.shape, e.shape);
                assert_eq!(e.shape, f.shape);
                assert_eq!(a.display, b.display);
                assert_eq!(b.display, c.display);
                assert_eq!(c.display, d.display);
                assert_eq!(d.display, e.display);
                assert_eq!(e.display, f.display);
                assert_eq!(*a, same_witness);
                assert_eq!(*b, same_witness);
                assert_eq!(*c, same_witness);
                assert_eq!(*d, same_witness);
                assert_eq!(*e, same_witness);
                assert_eq!(*f, same_witness);
            }
            _ => unreachable!(),
        }
    }

    #[test]
    fn missing_macro_arg_display_matches_legacy_compile_shape() {
        // The variant renders byte-for-byte the same string the legacy
        // `Compile { form: format!("call to {macro_name}"), message:
        // format!("missing required arg: {param}") }` shape produced, so
        // authoring tools (REPL, LSP, `tatara-check`) that substring-match
        // on the rendered diagnostic see no drift; tools that pattern-match
        // on the variant gain structural binding to `macro_name` and
        // `param`.
        let err = LispError::MissingMacroArg {
            macro_name: "wrap".into(),
            param: "b".into(),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in call to wrap: missing required arg: b"
        );
    }

    #[test]
    fn missing_macro_arg_display_carries_kebab_case_names_unchanged() {
        // Both `macro_name` and `param` round-trip through the variant's
        // Display unchanged. Pinning this contract means a regression that
        // camelCases or lowercases either side fails-loudly here.
        let err = LispError::MissingMacroArg {
            macro_name: "wrap-twice".into(),
            param: "notify-ref".into(),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in call to wrap-twice: \
             missing required arg: notify-ref"
        );
    }

    #[test]
    fn missing_macro_arg_display_preserves_legacy_substring_for_message_grep() {
        // Pin the legacy substring as a separate assertion so a regression
        // that drifts the wording (e.g., to "missing arg" or "no arg
        // provided") fails-loudly here even if the head clause changes
        // shape. The substring is what consumers downstream
        // (tatara-check, the REPL) substring-match on today.
        let err = LispError::MissingMacroArg {
            macro_name: "f".into(),
            param: "x".into(),
        };
        let msg = format!("{err}");
        assert!(
            msg.contains("missing required arg: x"),
            "expected legacy substring in message, got: {msg}"
        );
        assert!(
            msg.contains("call to f"),
            "expected call-to clause in message, got: {msg}"
        );
    }

    #[test]
    fn non_symbol_param_display_carries_position_and_got() {
        // The variant renders both the failing position (0-based index
        // within the param list) AND the offending element via
        // `Sexp::Display` — both fields are first-class structural data,
        // not embedded substrings of `message`. A regression that drops
        // either field from the rendered diagnostic fails-loudly here.
        let err = LispError::NonSymbolParam {
            position: 1,
            got: SexpWitness::new(SexpShape::Int, "5"),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defmacro params: \
             expected symbol at position 1, got 5"
        );
    }

    #[test]
    fn non_symbol_param_display_preserves_legacy_substring_for_message_grep() {
        // Pin the legacy substrings — `"defmacro params"` and `"expected
        // symbol"` — as separate assertions so a regression that drifts
        // either fragment fails-loudly here even if the appended position
        // / got clause changes shape. The substrings are what consumers
        // downstream substring-match on today; the prefix matches the
        // legacy `Compile { form: "defmacro params", message: "expected
        // symbol" }` byte-for-byte.
        let err = LispError::NonSymbolParam {
            position: 0,
            got: SexpWitness::new(SexpShape::List, "(nested)"),
        };
        let msg = format!("{err}");
        assert!(
            msg.contains("defmacro params"),
            "expected legacy form label in message, got: {msg}"
        );
        assert!(
            msg.contains("expected symbol"),
            "expected legacy substring in message, got: {msg}"
        );
    }

    #[test]
    fn non_symbol_param_display_carries_keyword_got_unchanged() {
        // `Sexp::Display` for `Atom::Keyword(s)` writes `:s`; pin that
        // the variant's Display passes the keyword form through
        // unchanged so an LSP that surfaces "you wrote `:k` where a
        // symbol was expected" gains the literal value as data, no
        // re-parsing required.
        let err = LispError::NonSymbolParam {
            position: 2,
            got: SexpWitness::new(SexpShape::Keyword, ":k"),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defmacro params: \
             expected symbol at position 2, got :k"
        );
    }

    #[test]
    fn rest_param_missing_name_display_with_got_renders_marker_position_and_got() {
        // `(defmacro f (a &rest 5) …)` — `&rest` at param-list position 1,
        // followed by `5` at position 2. The variant renders both the
        // marker's position AND the offending follower via `Sexp::Display`
        // — both are first-class structural data, not embedded substrings
        // of `message`. A regression that drops either field from the
        // rendered diagnostic fails-loudly here.
        let err = LispError::RestParamMissingName {
            rest_position: 1,
            got: Some(SexpWitness::new(SexpShape::Int, "5")),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defmacro params: &rest needs a name \
             (rest marker at position 1, got 5)"
        );
    }

    #[test]
    fn rest_param_missing_name_display_without_got_renders_marker_position_only() {
        // `(defmacro f (a &rest))` — `&rest` at param-list position 1, no
        // follower at all. The variant renders the marker position and
        // names the absence structurally (`none provided`) instead of a
        // misleading empty / partial parenthetical. Sibling of how
        // `UnknownDomainKeyword` renders `(no domains registered)` for
        // the empty-registry case — the structural reason is named.
        let err = LispError::RestParamMissingName {
            rest_position: 1,
            got: None,
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defmacro params: &rest needs a name \
             (rest marker at position 1, none provided)"
        );
    }

    #[test]
    fn rest_param_missing_name_display_preserves_legacy_substring_for_message_grep() {
        // Pin the legacy substrings — `"defmacro params"` and `"&rest
        // needs a name"` — as separate assertions so a regression that
        // drifts either fragment fails-loudly here even if the appended
        // marker / got clause changes shape. The substrings are what
        // consumers downstream substring-match on today; the prefix
        // matches the legacy `Compile { form: "defmacro params",
        // message: "&rest needs a name" }` byte-for-byte.
        let err = LispError::RestParamMissingName {
            rest_position: 0,
            got: None,
        };
        let msg = format!("{err}");
        assert!(
            msg.contains("defmacro params"),
            "expected legacy form label in message, got: {msg}"
        );
        assert!(
            msg.contains("&rest needs a name"),
            "expected legacy substring in message, got: {msg}"
        );
    }

    #[test]
    fn rest_param_missing_name_display_carries_keyword_got_unchanged() {
        // `Sexp::Display` for `Atom::Keyword(s)` writes `:s`; pin that the
        // variant's Display passes the keyword form through unchanged so
        // an LSP that surfaces "you wrote `:foo` where a rest-name was
        // expected" gains the literal keyword value as data, no
        // re-parsing required.
        let err = LispError::RestParamMissingName {
            rest_position: 2,
            got: Some(SexpWitness::new(SexpShape::Keyword, ":foo")),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defmacro params: &rest needs a name \
             (rest marker at position 2, got :foo)"
        );
    }

    #[test]
    fn defmacro_arity_display_with_defmacro_head_renders_arity_and_legacy_template() {
        // The variant renders both the head keyword AND the actual
        // arity — both fields are first-class structural data, not
        // embedded substrings of `message`. The example template
        // `(defmacro name (params) body)` stays the literal `defmacro`
        // (not the head) — matching the legacy form's behavior so
        // authoring tools that substring-grep on the rendered
        // diagnostic see no drift. A regression that drops either
        // field from the rendered diagnostic fails-loudly here.
        let err = LispError::DefmacroArity {
            head: MacroDefHead::Defmacro,
            arity: 1,
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defmacro: (defmacro name (params) body) required \
             (got 1 elements, need 4)"
        );
    }

    #[test]
    fn defmacro_arity_display_carries_defpoint_template_head_unchanged() {
        // Pin that the head slot accepts every literal the call-site
        // matches! gate admits — `defpoint-template` is the second
        // head keyword `macro_def_from` recognizes. The example
        // template literal stays `(defmacro name (params) body)` even
        // for non-defmacro heads (matching the legacy behavior); the
        // prefix `compile error in defpoint-template:` carries the
        // actual head so an LSP that wants to point at "your
        // defpoint-template form is missing elements" gains the head
        // as data.
        let err = LispError::DefmacroArity {
            head: MacroDefHead::DefpointTemplate,
            arity: 2,
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defpoint-template: \
             (defmacro name (params) body) required \
             (got 2 elements, need 4)"
        );
    }

    #[test]
    fn defmacro_arity_display_carries_defcheck_head_unchanged() {
        // Sibling for the `defcheck` head; rounds out the three-head-
        // keyword coverage so the variant renders identically across
        // `defmacro` / `defpoint-template` / `defcheck` (modulo the
        // head literal in the prefix).
        let err = LispError::DefmacroArity {
            head: MacroDefHead::Defcheck,
            arity: 3,
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defcheck: (defmacro name (params) body) required \
             (got 3 elements, need 4)"
        );
    }

    #[test]
    fn defmacro_arity_display_preserves_legacy_substring_for_message_grep() {
        // Pin the legacy substring — `"(defmacro name (params) body)
        // required"` — as a separate assertion so a regression that
        // drifts the example template fails-loudly here even if the
        // appended `got X elements, need 4` clause changes shape. The
        // substring is what consumers downstream substring-match on
        // today; the prefix matches the legacy `Compile { form:
        // head.to_string(), message: "(defmacro name (params) body)
        // required" }` byte-for-byte.
        let err = LispError::DefmacroArity {
            head: MacroDefHead::Defmacro,
            arity: 0,
        };
        let msg = format!("{err}");
        assert!(
            msg.contains("(defmacro name (params) body) required"),
            "expected legacy template substring in message, got: {msg}"
        );
        assert!(
            msg.contains("compile error in defmacro:"),
            "expected legacy form-label prefix in message, got: {msg}"
        );
    }

    #[test]
    fn defmacro_non_symbol_name_display_with_int_got_renders_legacy_prefix_and_got() {
        // `(defmacro 5 () body)` — list[1] is `5`, not a symbol. The
        // variant renders both the head keyword AND the offending
        // `Sexp::Display` projection — both fields are first-class
        // structural data, not embedded substrings of `message`. The
        // prefix `compile error in defmacro: expected name symbol`
        // matches the legacy `Compile { form: "defmacro", message:
        // "expected name symbol" }` byte-for-byte; the structural
        // detail (`, got 5`) is appended. A regression that drops
        // either field from the rendered diagnostic fails-loudly here.
        let err = LispError::DefmacroNonSymbolName {
            head: MacroDefHead::Defmacro,
            got: SexpWitness::new(SexpShape::Int, "5"),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defmacro: expected name symbol, got 5"
        );
    }

    #[test]
    fn defmacro_non_symbol_name_display_carries_defpoint_template_head_unchanged() {
        // Pin that the head slot accepts every literal the call-site
        // matches! gate admits — `defpoint-template` is the second
        // head keyword `macro_def_from` recognizes. The prefix
        // `compile error in defpoint-template:` carries the actual
        // head so an LSP that wants to point at "your defpoint-
        // template form's name slot isn't a symbol" gains the head
        // as data.
        let err = LispError::DefmacroNonSymbolName {
            head: MacroDefHead::DefpointTemplate,
            got: SexpWitness::new(SexpShape::Keyword, ":foo"),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defpoint-template: expected name symbol, got :foo"
        );
    }

    #[test]
    fn defmacro_non_symbol_name_display_carries_defcheck_head_unchanged() {
        // Sibling for the `defcheck` head; rounds out the three-head-
        // keyword coverage so the variant renders identically across
        // `defmacro` / `defpoint-template` / `defcheck` (modulo the
        // head literal in the prefix).
        let err = LispError::DefmacroNonSymbolName {
            head: MacroDefHead::Defcheck,
            got: SexpWitness::new(SexpShape::List, "(nested)"),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defcheck: expected name symbol, got (nested)"
        );
    }

    #[test]
    fn defmacro_non_symbol_name_display_carries_string_got_unchanged() {
        // `Sexp::Display` for `Atom::String(s)` writes `"s"` (with
        // quotes); pin that the variant's Display passes the string
        // form through unchanged so an LSP that surfaces "you wrote
        // `\"name\"` where a name symbol was expected" gains the
        // literal value as data, no re-parsing required.
        let err = LispError::DefmacroNonSymbolName {
            head: MacroDefHead::Defmacro,
            got: SexpWitness::new(SexpShape::String, "\"name\""),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defmacro: expected name symbol, got \"name\""
        );
    }

    #[test]
    fn defmacro_non_symbol_name_display_preserves_legacy_substring_for_message_grep() {
        // Pin the legacy substring — `"expected name symbol"` — as a
        // separate assertion so a regression that drifts the wording
        // (e.g., to "expected symbol" or "name must be a symbol")
        // fails-loudly here even if the appended `, got X` clause
        // changes shape. The substring is what consumers downstream
        // (tatara-check, the REPL) substring-match on today; the
        // prefix matches the legacy `Compile { form: head.to_string(),
        // message: "expected name symbol" }` byte-for-byte.
        let err = LispError::DefmacroNonSymbolName {
            head: MacroDefHead::Defmacro,
            got: SexpWitness::new(SexpShape::Int, "5"),
        };
        let msg = format!("{err}");
        assert!(
            msg.contains("expected name symbol"),
            "expected legacy substring in message, got: {msg}"
        );
        assert!(
            msg.contains("compile error in defmacro:"),
            "expected legacy form-label prefix in message, got: {msg}"
        );
    }

    #[test]
    fn defmacro_non_list_params_display_with_symbol_got_renders_legacy_prefix_and_got() {
        // `(defmacro f x body)` — list[2] is the symbol `x`, not a
        // list. The variant renders both the head keyword AND the
        // offending `Sexp::Display` projection — both fields are
        // first-class structural data, not embedded substrings of
        // `message`. The prefix `compile error in defmacro: expected
        // param list` matches the legacy `Compile { form: "defmacro",
        // message: "expected param list" }` byte-for-byte; the
        // structural detail (`, got x`) is appended. A regression that
        // drops either field from the rendered diagnostic fails-loudly
        // here.
        let err = LispError::DefmacroNonListParams {
            head: MacroDefHead::Defmacro,
            got: SexpWitness::new(SexpShape::Symbol, "x"),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defmacro: expected param list, got x"
        );
    }

    #[test]
    fn defmacro_non_list_params_display_carries_defpoint_template_head_unchanged() {
        // Pin that the head slot accepts every literal the call-site
        // matches! gate admits — `defpoint-template` is the second
        // head keyword `macro_def_from` recognizes. The prefix
        // `compile error in defpoint-template:` carries the actual
        // head so an LSP that wants to point at "your defpoint-
        // template form's param-list slot isn't a list" gains the
        // head as data.
        let err = LispError::DefmacroNonListParams {
            head: MacroDefHead::DefpointTemplate,
            got: SexpWitness::new(SexpShape::Int, "5"),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defpoint-template: expected param list, got 5"
        );
    }

    #[test]
    fn defmacro_non_list_params_display_carries_defcheck_head_unchanged() {
        // Sibling for the `defcheck` head; rounds out the three-head-
        // keyword coverage so the variant renders identically across
        // `defmacro` / `defpoint-template` / `defcheck` (modulo the
        // head literal in the prefix).
        let err = LispError::DefmacroNonListParams {
            head: MacroDefHead::Defcheck,
            got: SexpWitness::new(SexpShape::Keyword, ":k"),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defcheck: expected param list, got :k"
        );
    }

    #[test]
    fn defmacro_non_list_params_display_carries_string_got_unchanged() {
        // `Sexp::Display` for `Atom::String(s)` writes `"s"` (with
        // quotes); pin that the variant's Display passes the string
        // form through unchanged so an LSP that surfaces "you wrote
        // `\"params\"` where a param list was expected" gains the
        // literal value as data, no re-parsing required.
        let err = LispError::DefmacroNonListParams {
            head: MacroDefHead::Defmacro,
            got: SexpWitness::new(SexpShape::String, "\"params\""),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defmacro: expected param list, got \"params\""
        );
    }

    #[test]
    fn defmacro_non_list_params_display_preserves_legacy_substring_for_message_grep() {
        // Pin the legacy substring — `"expected param list"` — as a
        // separate assertion so a regression that drifts the wording
        // (e.g., to "expected list" or "params must be a list")
        // fails-loudly here even if the appended `, got X` clause
        // changes shape. The substring is what consumers downstream
        // (tatara-check, the REPL) substring-match on today; the
        // prefix matches the legacy `Compile { form: head.to_string(),
        // message: "expected param list" }` byte-for-byte.
        let err = LispError::DefmacroNonListParams {
            head: MacroDefHead::Defmacro,
            got: SexpWitness::new(SexpShape::Symbol, "x"),
        };
        let msg = format!("{err}");
        assert!(
            msg.contains("expected param list"),
            "expected legacy substring in message, got: {msg}"
        );
        assert!(
            msg.contains("compile error in defmacro:"),
            "expected legacy form-label prefix in message, got: {msg}"
        );
    }

    #[test]
    fn unbound_template_var_display_preserves_splice_prefix_in_hint() {
        // Splice marker rides through both the form and the suggestion; the
        // operator never has to translate `,` ↔ `,@` mentally.
        let err = LispError::UnboundTemplateVar {
            prefix: UnquoteForm::Splice,
            name: "rsts".into(),
            hint: Some("rest".into()),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in ,@rsts: unbound; did you mean ,@rest?"
        );
    }

    #[test]
    fn named_form_missing_name_display_renders_legacy_compile_shape() {
        // `(defpoint)` — list.len() == 1 (just the keyword, no NAME). The
        // variant renders byte-for-byte the same string the legacy
        // `Compile { form: "defpoint", message: "expected (defpoint NAME …)"
        // }` shape produced, so authoring tools (REPL, LSP, `tatara-check`)
        // that substring-match on the rendered diagnostic see no drift;
        // tools that pattern-match on the variant gain structural binding
        // to `keyword`.
        let err = LispError::NamedFormMissingName {
            keyword: "defpoint",
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defpoint: expected (defpoint NAME …)"
        );
    }

    #[test]
    fn named_form_missing_name_display_carries_defalertpolicy_keyword_unchanged() {
        // Pin path-uniformity across distinct keywords — every
        // `compile_named` caller funnels through `NamedFormMissingName`
        // with its own `T::KEYWORD`, so the variant's `keyword` slot
        // must round-trip every literal the derive macro accepts. A
        // regression that drops or rewrites the keyword (e.g.,
        // lowercasing, stripping the `def` prefix) fails-loudly here.
        let err = LispError::NamedFormMissingName {
            keyword: "defalertpolicy",
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defalertpolicy: expected (defalertpolicy NAME …)"
        );
    }

    #[test]
    fn named_form_missing_name_display_carries_kebab_case_keyword_unchanged() {
        // Kebab-cased domain keywords (`defprocess-spec`, `defalert-policy`)
        // round-trip through both occurrences of the keyword in the rendered
        // diagnostic — the prefix `compile error in {keyword}:` AND the
        // example template `(... NAME …)`. Pinning this contract means a
        // regression that camelCases either occurrence fails-loudly here.
        let err = LispError::NamedFormMissingName {
            keyword: "defprocess-spec",
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defprocess-spec: expected (defprocess-spec NAME …)"
        );
    }

    #[test]
    fn named_form_missing_name_display_preserves_unicode_ellipsis_byte_for_byte() {
        // The legacy `format!("expected ({} NAME …)", T::KEYWORD)` shape used
        // the Unicode horizontal-ellipsis character (U+2026), not the ASCII
        // three-dot sequence `...`. Pin the codepoint exactly so a regression
        // that replaces `…` with `...` fails-loudly here — consumers
        // downstream that substring-match on `"…"` would silently miss every
        // future occurrence otherwise.
        let err = LispError::NamedFormMissingName {
            keyword: "defmonitor",
        };
        let msg = format!("{err}");
        assert!(
            msg.contains('\u{2026}'),
            "expected Unicode horizontal-ellipsis (U+2026) in message, got: {msg}"
        );
        assert!(
            !msg.contains("..."),
            "expected no ASCII three-dot sequence in message, got: {msg}"
        );
    }

    #[test]
    fn named_form_missing_name_display_preserves_legacy_substring_for_message_grep() {
        // Pin the legacy substring — `"expected ({keyword} NAME …)"` — as a
        // separate assertion so a regression that drifts the wording (e.g.,
        // to "expected NAME after keyword" or "missing positional name")
        // fails-loudly here. The substring is what consumers downstream
        // (`tatara-check`, the REPL) substring-match on today; the prefix
        // matches the legacy `Compile { form: T::KEYWORD.to_string(),
        // message: format!("expected ({} NAME …)", T::KEYWORD) }`
        // byte-for-byte.
        let err = LispError::NamedFormMissingName {
            keyword: "defmonitor",
        };
        let msg = format!("{err}");
        assert!(
            msg.contains("expected (defmonitor NAME"),
            "expected legacy form-label prefix in message, got: {msg}"
        );
        assert!(
            msg.contains("compile error in defmonitor:"),
            "expected legacy form-label prefix in message, got: {msg}"
        );
    }

    #[test]
    fn named_form_non_symbol_name_display_renders_legacy_prefix_with_int_got() {
        // `(defpoint 5 …)` — list[1] is the int `5`. The variant renders
        // the legacy prefix `compile error in {keyword}: positional NAME
        // must be a symbol or string` byte-for-byte AND appends the
        // structural detail `(got int)` parenthetically — same posture as
        // how `MissingHeadSymbol` appends `(got 5)` and how
        // `RestParamMissingName` appends `(rest marker at position N,
        // got X)`. The `got` slot is the typed `SexpShape` enum sourced
        // from `sexp_shape`; pin the Int-arm rendering (via
        // `SexpShape::Display` to the canonical `"int"` literal) as the
        // canonical example.
        let err = LispError::NamedFormNonSymbolName {
            keyword: "defpoint",
            got: SexpShape::Int,
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defpoint: positional NAME must be a symbol or string (got int)"
        );
    }

    #[test]
    fn named_form_non_symbol_name_display_carries_keyword_got_unchanged() {
        // `(defpoint :foo …)` — list[1] is a `:foo` keyword. Pin
        // path-uniformity across distinct `SexpShape` variants: the
        // `got` slot is `SexpShape::Keyword` (the typed projection from
        // `sexp_shape(Sexp::Atom(Atom::Keyword(_)))`), threaded into
        // the parenthetical via `SexpShape::Display` -> "keyword".
        let err = LispError::NamedFormNonSymbolName {
            keyword: "defpoint",
            got: SexpShape::Keyword,
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defpoint: positional NAME must be a symbol or string (got keyword)"
        );
    }

    #[test]
    fn named_form_non_symbol_name_display_carries_list_got_unchanged() {
        // `(defpoint (nested) …)` — list[1] is a nested list. Pin the
        // `SexpShape::List` variant round-trips into the variant's
        // `got` slot unchanged so an LSP that surfaces "you wrote a
        // nested list where a NAME symbol was expected" gains the
        // structural shape as data, no re-parsing required.
        let err = LispError::NamedFormNonSymbolName {
            keyword: "defalertpolicy",
            got: SexpShape::List,
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defalertpolicy: positional NAME must be a symbol or string (got list)"
        );
    }

    #[test]
    fn named_form_non_symbol_name_display_carries_kebab_case_keyword_unchanged() {
        // Kebab-cased domain keywords (`defprocess-spec`, `defalert-policy`)
        // round-trip through the rendered diagnostic's `compile error in
        // {keyword}:` prefix unchanged. A regression that camelCases the
        // keyword fails-loudly here.
        let err = LispError::NamedFormNonSymbolName {
            keyword: "defprocess-spec",
            got: SexpShape::Int,
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defprocess-spec: positional NAME must be a symbol or string (got int)"
        );
    }

    #[test]
    fn named_form_non_symbol_name_display_preserves_legacy_substring_for_message_grep() {
        // Pin the legacy substring — `"positional NAME must be a symbol
        // or string"` — as a separate assertion so a regression that
        // drifts the wording (e.g., to "NAME must be a symbol", "NAME
        // slot wrong-typed") fails-loudly here even if the appended
        // parenthetical changes shape. The substring is what consumers
        // downstream (`tatara-check`, the REPL) substring-match on
        // today; the prefix matches the legacy `Compile { form:
        // T::KEYWORD.to_string(), message: "positional NAME must be a
        // symbol or string" }` byte-for-byte.
        let err = LispError::NamedFormNonSymbolName {
            keyword: "defmonitor",
            got: SexpShape::Int,
        };
        let msg = format!("{err}");
        assert!(
            msg.contains("positional NAME must be a symbol or string"),
            "expected legacy substring in message, got: {msg}"
        );
        assert!(
            msg.contains("compile error in defmonitor:"),
            "expected legacy form-label prefix in message, got: {msg}"
        );
    }

    // ── RewriterNonList: typed-exit structural-variant lift ─────────
    //
    // `rewriter_non_list_err::<T>` (the typed-exit gate of
    // `rewrite_typed::<T>`'s round-trip) was promoted from the
    // `LispError::Compile`-shaped triple to the structural
    // `LispError::RewriterNonList { keyword, got }` variant. The
    // tests below pin: (a) Display matches the legacy `"compile error
    // in {keyword}: rewriter must return a list; got {got}"` shape
    // byte-for-byte across representative `got` renderings (int,
    // symbol, nil rendered as "()", quoted form); (b) the legacy
    // substring `"rewriter must return a list; got "` and the legacy
    // prefix `"compile error in {keyword}:"` both survive the lift
    // unchanged for substring-grep consumers; (c) kebab-case keywords
    // thread unchanged; (d) `position()` is `None` today (lands as
    // one branch when source spans arrive).

    #[test]
    fn rewriter_non_list_display_renders_legacy_shape_with_int_got() {
        // `Sexp::int(42)` projects to `Sexp::Display = "42"`. The variant
        // renders the legacy `"compile error in {keyword}: rewriter must
        // return a list; got {got}"` shape byte-for-byte — same wording
        // as the pre-lift `Compile`-shaped triple.
        let err = LispError::RewriterNonList {
            keyword: "defmonitor",
            got: SexpWitness::new(SexpShape::Int, "42"),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defmonitor: rewriter must return a list; got 42"
        );
    }

    #[test]
    fn rewriter_non_list_display_carries_symbol_got_unchanged() {
        // `Sexp::symbol("not-a-list")` projects to `"not-a-list"`. Pin
        // path-uniformity across distinct `Sexp::Display` outputs: the
        // typed `got` slot threads the value-rendering into the
        // diagnostic unchanged via `SexpWitness::Display` (which writes
        // only the `display` field).
        let err = LispError::RewriterNonList {
            keyword: "defmonitor",
            got: SexpWitness::new(SexpShape::Symbol, "not-a-list"),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defmonitor: rewriter must return a list; got not-a-list"
        );
    }

    #[test]
    fn rewriter_non_list_display_carries_nil_got_as_paren_paren() {
        // `Sexp::Nil` projects to `"()"` per the `Sexp::Display`
        // contract — NOT `"nil"`. Pin the contract so a regression
        // that drifts `Sexp::Nil`'s Display fails-loudly here even
        // before reaching the rewriter end-to-end test.
        let err = LispError::RewriterNonList {
            keyword: "defmonitor",
            got: SexpWitness::new(SexpShape::Nil, "()"),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defmonitor: rewriter must return a list; got ()"
        );
    }

    #[test]
    fn rewriter_non_list_display_carries_kebab_case_keyword_unchanged() {
        // Kebab-cased domain keywords (`defprocess-spec`,
        // `defalert-policy`) round-trip through the rendered
        // diagnostic's `compile error in {keyword}:` prefix unchanged.
        // A regression that camelCases the keyword fails-loudly here.
        let err = LispError::RewriterNonList {
            keyword: "defprocess-spec",
            got: SexpWitness::new(SexpShape::Int, "7"),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defprocess-spec: rewriter must return a list; got 7"
        );
    }

    #[test]
    fn rewriter_non_list_display_preserves_legacy_substring_for_message_grep() {
        // Pin the legacy substring — `"rewriter must return a list;
        // got "` — as a separate assertion so a regression that drifts
        // the wording (e.g., to "rewriter returned non-list", "expected
        // list output") fails-loudly here. The substring is what
        // consumers downstream (`tatara-check`, the REPL) substring-
        // match on; the prefix matches the legacy `Compile { form:
        // T::KEYWORD.to_string(), message: format!("rewriter must
        // return a list; got {other}") }` byte-for-byte.
        let err = LispError::RewriterNonList {
            keyword: "defmonitor",
            got: SexpWitness::new(SexpShape::Int, "42"),
        };
        let msg = format!("{err}");
        assert!(
            msg.contains("rewriter must return a list; got "),
            "expected legacy substring in message, got: {msg}"
        );
        assert!(
            msg.contains("compile error in defmonitor:"),
            "expected legacy form-label prefix in message, got: {msg}"
        );
    }

    #[test]
    fn rewriter_non_list_position_is_none_today() {
        // Until `Sexp` carries source positions, the variant's
        // `position()` returns `None`. Pin the contract: a future run
        // that adds `pos: Option<usize>` lands inside `SexpWitness` in
        // ONE place and `rewrite_typed`'s rewriter-output rejection
        // picks up the span automatically because it routes through
        // one helper (`rewriter_non_list_err`).
        let err = LispError::RewriterNonList {
            keyword: "defmonitor",
            got: SexpWitness::new(SexpShape::Int, "42"),
        };
        assert_eq!(err.position(), None);
    }

    #[test]
    fn rewriter_non_list_got_carries_typed_witness_through_variant_slot() {
        // Pin the structural binding on `LispError::RewriterNonList.got`
        // — a regression that re-introduces a `String`-shaped got slot
        // (collapsing the typed witness back into a free-form literal at
        // the typed-EXIT boundary) fails-loudly here. After this lift the
        // variant's typed slot is the joint `SexpWitness` identity — the
        // SAME primitive the SEVEN typed-ENTRY-side `got` slots already
        // carry (`SpliceOutsideList`, `NonSymbolUnquoteTarget`,
        // `NonSymbolParam`, `DefmacroNonSymbolName`,
        // `DefmacroNonListParams`, `RestParamMissingName`,
        // `MissingHeadSymbol`). This is the EIGHTH consumer and the FIRST
        // on the typed-EXIT boundary; the typed-identity unification
        // contract is now closed across BOTH boundaries of the typed-IR
        // algebra. The Display projection through `SexpWitness::Display`
        // writes only the `display` field so the rendered `got {display}`
        // suffix is byte-for-byte identical to the legacy `got: String`
        // shape.
        let err = LispError::RewriterNonList {
            keyword: "defmonitor",
            got: SexpWitness::new(SexpShape::Int, "42"),
        };
        match &err {
            LispError::RewriterNonList { keyword, got } => {
                assert_eq!(*keyword, "defmonitor");
                assert_eq!(got.shape, SexpShape::Int);
                assert_eq!(got.display, "42");
            }
            other => panic!("expected RewriterNonList, got {other:?}"),
        }
        assert_eq!(
            format!("{err}"),
            "compile error in defmonitor: rewriter must return a list; got 42"
        );
    }

    #[test]
    fn rewriter_non_list_got_distinguishes_int_from_keyword_at_variant_slot() {
        // Pin the typed-shape bifurcation at the variant slot's `got`
        // slot — `42` (int) and `:foo` (keyword) BOTH route to
        // `RewriterNonList` (the rewriter returned a non-list typed-exit
        // rejection), but the typed `got.shape` slot distinguishes them
        // structurally as `SexpShape::Int` vs. `SexpShape::Keyword`.
        // Sibling pin for the same structural-shape-bifurcation property
        // `splice_outside_list_got_distinguishes_symbol_from_list_at_variant_slot`
        // pins on the typed-ENTRY-side `SpliceOutsideList` variant — the
        // same posture applied to the typed-EXIT-side rejection variant.
        // A regression that erases the typed shape (e.g., reverts to
        // `got: String`) would lose this distinction — tooling that
        // wants to surface "your rewriter returned the int `42` where a
        // kwargs list was expected" vs. "your rewriter returned the
        // keyword `:foo` where a kwargs list was expected" would have to
        // substring-grep the `display` field, brittle.
        let err_int = LispError::RewriterNonList {
            keyword: "defmonitor",
            got: SexpWitness::new(SexpShape::Int, "42"),
        };
        let err_kw = LispError::RewriterNonList {
            keyword: "defmonitor",
            got: SexpWitness::new(SexpShape::Keyword, ":foo"),
        };
        let (int_shape, kw_shape) = (
            match &err_int {
                LispError::RewriterNonList { got, .. } => got.shape,
                _ => unreachable!(),
            },
            match &err_kw {
                LispError::RewriterNonList { got, .. } => got.shape,
                _ => unreachable!(),
            },
        );
        assert_ne!(
            int_shape, kw_shape,
            "Int and Keyword witnesses must remain structurally distinct at the variant slot",
        );
        assert_eq!(int_shape, SexpShape::Int);
        assert_eq!(kw_shape, SexpShape::Keyword);
    }

    #[test]
    fn rewriter_non_list_and_typed_entry_gates_share_one_witness_primitive() {
        // Pin that ALL EIGHT Sexp-display-source `got` slots in the
        // substrate carry the SAME typed `SexpWitness` primitive — the
        // closed set of "offending inner Sexp" identities is bound by
        // ONE typed primitive across EIGHT rejection surfaces spanning
        // BOTH boundaries of the typed-IR algebra: the typed-ENTRY side
        // (seven slots — the template-gate's `,X/,@X` pair, the
        // defmacro-syntax-gate's `parse_params` walker (BOTH
        // non-symbol-param AND post-`&rest`-non-symbol-follower rejection
        // points), BOTH of the defmacro-syntax-gate's outer
        // `macro_def_from` rejection points (name-symbol AND
        // param-list), AND the outer `compile_from_sexp` typed-entry
        // gate's non-symbol-head rejection point) AND the typed-EXIT
        // side (ONE slot — `rewrite_typed`'s `Sexp::List`-contract gate
        // for the rewriter's output). With this lift EVERY
        // `Sexp::Display`-source `got` slot in the substrate is
        // structurally unified end-to-end across BOTH typed boundaries.
        // The `Option`-wrap on `MissingHeadSymbol.got` and
        // `RestParamMissingName.got` is the bifurcation between "missing
        // entirely" and "present but malformed"; the typed witness
        // rides on the `Some` arm and is structurally identical to the
        // other six variants' got slots. A regression that diverges the
        // slot type on any one variant (e.g., re-collapses
        // `RewriterNonList.got` to `String` while leaving the others
        // typed) fails-loudly here because the assignment round-trips
        // the witness across all eight slot types. Sibling pin to
        // `missing_head_symbol_and_rest_param_gate_share_one_witness_primitive`
        // — extending the typed-identity unification contract from
        // seven slots (typed-ENTRY only) to eight slots (typed-ENTRY +
        // typed-EXIT), CLOSING the contract across BOTH boundaries of
        // the typed-IR algebra (THEORY.md §II.1 invariant 1 +
        // invariant 3).
        let same_witness = SexpWitness::new(SexpShape::Int, "42");
        let rewriter_non_list = LispError::RewriterNonList {
            keyword: "defmonitor",
            got: same_witness.clone(),
        };
        let missing_head = LispError::MissingHeadSymbol {
            keyword: "defmonitor",
            got: Some(same_witness.clone()),
        };
        let rest_param_missing_name = LispError::RestParamMissingName {
            rest_position: 0,
            got: Some(same_witness.clone()),
        };
        let defmacro_non_list_params = LispError::DefmacroNonListParams {
            head: MacroDefHead::Defmacro,
            got: same_witness.clone(),
        };
        let defmacro_non_symbol_name = LispError::DefmacroNonSymbolName {
            head: MacroDefHead::Defmacro,
            got: same_witness.clone(),
        };
        let non_symbol_param = LispError::NonSymbolParam {
            position: 0,
            got: same_witness.clone(),
        };
        let non_symbol_target = LispError::NonSymbolUnquoteTarget {
            prefix: UnquoteForm::Unquote,
            got: same_witness.clone(),
        };
        let splice_outside = LispError::SpliceOutsideList {
            got: same_witness.clone(),
        };
        match (
            &rewriter_non_list,
            &missing_head,
            &rest_param_missing_name,
            &defmacro_non_list_params,
            &defmacro_non_symbol_name,
            &non_symbol_param,
            &non_symbol_target,
            &splice_outside,
        ) {
            (
                LispError::RewriterNonList { got: a, .. },
                LispError::MissingHeadSymbol { got: Some(b), .. },
                LispError::RestParamMissingName { got: Some(c), .. },
                LispError::DefmacroNonListParams { got: d, .. },
                LispError::DefmacroNonSymbolName { got: e, .. },
                LispError::NonSymbolParam { got: f, .. },
                LispError::NonSymbolUnquoteTarget { got: g, .. },
                LispError::SpliceOutsideList { got: h },
            ) => {
                assert_eq!(a.shape, b.shape);
                assert_eq!(b.shape, c.shape);
                assert_eq!(c.shape, d.shape);
                assert_eq!(d.shape, e.shape);
                assert_eq!(e.shape, f.shape);
                assert_eq!(f.shape, g.shape);
                assert_eq!(g.shape, h.shape);
                assert_eq!(a.display, b.display);
                assert_eq!(b.display, c.display);
                assert_eq!(c.display, d.display);
                assert_eq!(d.display, e.display);
                assert_eq!(e.display, f.display);
                assert_eq!(f.display, g.display);
                assert_eq!(g.display, h.display);
                assert_eq!(*a, same_witness);
                assert_eq!(*b, same_witness);
                assert_eq!(*c, same_witness);
                assert_eq!(*d, same_witness);
                assert_eq!(*e, same_witness);
                assert_eq!(*f, same_witness);
                assert_eq!(*g, same_witness);
                assert_eq!(*h, same_witness);
            }
            _ => unreachable!(),
        }
    }

    // ── DomainSerialize: typed-exit `to_value` structural-variant lift ──
    //
    // `serialize_to_json_err::<T>` (the `to_value`-side gate shared
    // between `register::<T>`'s registry-dispatch closure and
    // `rewrite_typed::<T>`'s round-trip prelude) was promoted from the
    // `LispError::Compile`-shaped triple to the structural
    // `LispError::DomainSerialize { keyword, message }` variant. The
    // tests below pin: (a) Display matches the legacy `"compile error
    // in {keyword}: serialize: {message}"` shape byte-for-byte across
    // representative `message` renderings (serde_json's stock
    // diagnostic, hand-crafted message); (b) the legacy substring
    // `"serialize: "` and the legacy prefix `"compile error in
    // {keyword}:"` both survive the lift unchanged for substring-grep
    // consumers; (c) kebab-case keywords thread through unchanged.
    // The `position()` floor is pinned in the main
    // `position_is_none_for_non_positional_variants` block above.

    #[test]
    fn domain_serialize_display_renders_legacy_shape_with_short_message() {
        // Hand-crafted `message` slot — the variant renders the legacy
        // `"compile error in {keyword}: serialize: {message}"` shape
        // byte-for-byte. Same wording as the pre-lift `Compile`-shaped
        // triple in `serialize_to_json_err`.
        let err = LispError::DomainSerialize {
            keyword: "defmonitor",
            message: "key must be a string".into(),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defmonitor: serialize: key must be a string"
        );
    }

    #[test]
    fn domain_serialize_display_carries_serde_json_diagnostic_unchanged() {
        // Use a real `serde_json::Error` so the test exercises a
        // representative `{e}` shape (`"expected value at line L column
        // C"`) and pins that the variant's Display rendering threads
        // the underlying diagnostic through unchanged.
        let raw = serde_json::from_str::<i32>("not-a-number")
            .expect_err("parse must fail")
            .to_string();
        let err = LispError::DomainSerialize {
            keyword: "defmonitor",
            message: raw.clone(),
        };
        assert_eq!(
            format!("{err}"),
            format!("compile error in defmonitor: serialize: {raw}")
        );
    }

    #[test]
    fn domain_serialize_display_carries_kebab_case_keyword_unchanged() {
        // Kebab-cased domain keywords (`defprocess-spec`,
        // `defalert-policy`) round-trip through the rendered
        // diagnostic's `compile error in {keyword}:` prefix unchanged.
        // A regression that camelCases the keyword fails-loudly here.
        let err = LispError::DomainSerialize {
            keyword: "defalert-policy",
            message: "expected struct".into(),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defalert-policy: serialize: expected struct"
        );
    }

    #[test]
    fn domain_serialize_display_preserves_legacy_substring_for_message_grep() {
        // Pin the legacy substring — `"serialize: "` — as a separate
        // assertion so a regression that drifts the wording (e.g., to
        // "to_json failed", "json encode error") fails-loudly here.
        // The substring is what consumers downstream (`tatara-check`,
        // the REPL) substring-match on; the prefix matches the legacy
        // `Compile { form: T::KEYWORD.to_string(), message:
        // format!("serialize: {e}") }` byte-for-byte.
        let err = LispError::DomainSerialize {
            keyword: "defmonitor",
            message: "boom".into(),
        };
        let msg = format!("{err}");
        assert!(
            msg.contains("serialize: "),
            "expected legacy substring in message, got: {msg}"
        );
        assert!(
            msg.contains("compile error in defmonitor:"),
            "expected legacy form-label prefix in message, got: {msg}"
        );
    }

    #[test]
    fn domain_serialize_display_empty_message_renders_bare_prefix() {
        // Edge case: an empty `message` slot renders as `"compile
        // error in {keyword}: serialize: "` — pin the trailing space
        // after the `serialize:` marker stays put. A regression that
        // strips trailing whitespace (e.g., via `.trim_end()`) or
        // drops the marker entirely fails-loudly here.
        let err = LispError::DomainSerialize {
            keyword: "defmonitor",
            message: String::new(),
        };
        assert_eq!(format!("{err}"), "compile error in defmonitor: serialize: ");
    }

    // ── KwargDeserialize: typed-entry `from_value` structural-variant lift ──
    //
    // `deserialize_err(key, err)` and `deserialize_item_err(key, idx,
    // err)` (the `from_value`-side gate shared between
    // `extract_via_serde`, `extract_optional_via_serde`, and
    // `extract_vec_via_serde`) were promoted from the
    // `LispError::Compile`-shaped triple to the structural
    // `LispError::KwargDeserialize { path: KwargPath, message }`
    // variant — the `(key: String, idx: Option<usize>)` bifurcation
    // collapsed into the typed `KwargPath` enum's `Named` vs. `Item`
    // variant identity. The tests below pin: (a) Display matches the
    // legacy `"compile error in :{key}: deserialize: {message}"` shape
    // byte-for-byte for the scalar path (`path: KwargPath::Named`); (b)
    // Display matches the indexed `"compile error in :{key}[{idx}]:
    // deserialize: {message}"` shape byte-for-byte for the per-item
    // path (`path: KwargPath::Item`); (c) the legacy substring
    // `"deserialize: "` and the legacy prefix `"compile error in :"`
    // both survive the lift unchanged for substring-grep consumers;
    // (d) kebab-case keys thread through unchanged; (e) the typed
    // `path` slot carries `KwargPath` data DIRECTLY (not as a projection
    // through a helper), structurally bound via pattern-match on the
    // typed enum's variant identity. The `position()` floor is pinned
    // in the main `position_is_none_for_non_positional_variants` block
    // above.

    #[test]
    fn kwarg_deserialize_display_scalar_path_renders_legacy_shape() {
        // `path: KwargPath::Named(_)` — scalar / `Option<T>` path. The
        // variant renders the legacy `"compile error in :{key}:
        // deserialize: {message}"` shape byte-for-byte. Same wording as
        // the pre-lift `Compile`-shaped triple in `deserialize_err`.
        let err = LispError::KwargDeserialize {
            path: KwargPath::named("level"),
            message: "unknown variant `NotASeverity`".into(),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in :level: deserialize: unknown variant `NotASeverity`"
        );
    }

    #[test]
    fn kwarg_deserialize_display_per_item_path_renders_indexed_shape() {
        // `path: KwargPath::Item { .. }` — per-item path. The variant
        // renders the legacy `"compile error in :{key}[{idx}]:
        // deserialize: {message}"` shape byte-for-byte. Same wording as
        // the pre-lift `Compile`-shaped triple in `deserialize_item_err`.
        let err = LispError::KwargDeserialize {
            path: KwargPath::item("steps", 1),
            message: "invalid type: integer `7`, expected a string".into(),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in :steps[1]: deserialize: invalid type: integer `7`, expected a string"
        );
    }

    #[test]
    fn kwarg_deserialize_display_carries_serde_json_diagnostic_unchanged() {
        // Use a real `serde_json::Error` so the test exercises a
        // representative `{e}` shape (`"expected value at line L
        // column C"`) and pins that the variant's Display rendering
        // threads the underlying diagnostic through unchanged.
        let raw = serde_json::from_str::<i32>("not-a-number")
            .expect_err("parse must fail")
            .to_string();
        let err = LispError::KwargDeserialize {
            path: KwargPath::named("count"),
            message: raw.clone(),
        };
        assert_eq!(
            format!("{err}"),
            format!("compile error in :count: deserialize: {raw}")
        );
    }

    #[test]
    fn kwarg_deserialize_display_carries_kebab_case_key_unchanged() {
        // Kebab-cased kwarg names (`notify-ref`, `wait-minutes`,
        // `window-seconds`) round-trip through the rendered diagnostic's
        // `compile error in :{key}:` prefix unchanged. A regression that
        // camelCases the key fails-loudly here.
        let err = LispError::KwargDeserialize {
            path: KwargPath::named("notify-ref"),
            message: "missing field `notify-ref`".into(),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in :notify-ref: deserialize: missing field `notify-ref`"
        );
    }

    #[test]
    fn kwarg_deserialize_display_carries_kebab_case_key_with_index_unchanged() {
        // Kebab-cased keys round-trip through the indexed path too —
        // `:notify-refs[2]` not `:notifyRefs[2]`. Pinning both paths
        // means a regression in either site (scalar or per-item) fails-
        // loudly here.
        let err = LispError::KwargDeserialize {
            path: KwargPath::item("wait-minutes", 2),
            message: "expected u64".into(),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in :wait-minutes[2]: deserialize: expected u64"
        );
    }

    #[test]
    fn kwarg_deserialize_display_preserves_legacy_substring_for_message_grep() {
        // Pin the legacy substring — `"deserialize: "` — as a separate
        // assertion so a regression that drifts the wording (e.g., to
        // "from_json failed", "json decode error") fails-loudly here.
        // The substring is what consumers downstream (`tatara-check`,
        // the REPL) substring-match on; the prefix matches the legacy
        // `Compile { form: kwarg_form(key), message: format!("deserialize:
        // {e}") }` byte-for-byte. Both sub-modes (`KwargPath::Named`
        // AND `KwargPath::Item`) preserve the substring.
        let scalar = LispError::KwargDeserialize {
            path: KwargPath::named("level"),
            message: "boom".into(),
        };
        let scalar_msg = format!("{scalar}");
        assert!(
            scalar_msg.contains("deserialize: "),
            "expected legacy substring in scalar message, got: {scalar_msg}"
        );
        assert!(
            scalar_msg.contains("compile error in :level:"),
            "expected legacy form-label prefix in scalar message, got: {scalar_msg}"
        );

        let item = LispError::KwargDeserialize {
            path: KwargPath::item("steps", 3),
            message: "boom".into(),
        };
        let item_msg = format!("{item}");
        assert!(
            item_msg.contains("deserialize: "),
            "expected legacy substring in item message, got: {item_msg}"
        );
        assert!(
            item_msg.contains("compile error in :steps[3]:"),
            "expected indexed form-label prefix in item message, got: {item_msg}"
        );
    }

    #[test]
    fn kwarg_deserialize_display_zero_index_is_first_class() {
        // Edge case: `path: KwargPath::Item { idx: 0, .. }` must render
        // as `:steps[0]`, not `:steps` (which would collide with the
        // scalar path's `KwargPath::Named` rendering). Pin that the
        // bifurcation is by `KwargPath` variant identity, not by
        // `idx > 0`.
        let err = LispError::KwargDeserialize {
            path: KwargPath::item("steps", 0),
            message: "bad".into(),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in :steps[0]: deserialize: bad"
        );
    }

    #[test]
    fn kwarg_deserialize_path_named_threads_typed_kwarg_path_through_variant_slot() {
        // Structural pin: the scalar / `Option<T>` path's
        // `LispError::KwargDeserialize` carries the typed
        // `KwargPath::Named(key)` value DIRECTLY in its `path` slot,
        // not a `(key: String, idx: None)` pair. Authoring tools (REPL,
        // LSP, `tatara-check`) bind on the typed enum's variant
        // identity (`KwargPath::Named(_)`) rather than substring-
        // matching the rendered `form:` prefix, parallel to how
        // `TypeMismatch.form` is bound. A regression that re-bifurcates
        // the variant into a `(key, idx: Option<usize>)` pair fails the
        // structural assertion here (the slot would no longer be a
        // typed `KwargPath`).
        let err = LispError::KwargDeserialize {
            path: KwargPath::named("level"),
            message: "boom".into(),
        };
        let LispError::KwargDeserialize {
            ref path,
            ref message,
        } = err
        else {
            panic!("expected KwargDeserialize, got {err:?}");
        };
        assert_eq!(*path, KwargPath::Named("level".into()));
        assert_eq!(message, "boom");
        assert_eq!(
            format!("{err}"),
            "compile error in :level: deserialize: boom"
        );
    }

    #[test]
    fn kwarg_deserialize_path_item_threads_typed_kwarg_path_through_variant_slot() {
        // Sibling structural pin to `…_path_named_…`: the per-item path
        // carries `KwargPath::Item { key, idx }` directly in its `path`
        // slot. The `(key, idx)` bifurcation lives inside the typed
        // enum's variant identity (`KwargPath::Named` vs.
        // `KwargPath::Item`), so the invalid sibling slot combination
        // `(key: "", idx: Some(_))` for a scalar / Optional path is
        // structurally unrepresentable in the variant's data shape.
        let err = LispError::KwargDeserialize {
            path: KwargPath::item("steps", 1),
            message: "bad".into(),
        };
        let LispError::KwargDeserialize {
            ref path,
            ref message,
        } = err
        else {
            panic!("expected KwargDeserialize, got {err:?}");
        };
        assert_eq!(
            *path,
            KwargPath::Item {
                key: "steps".into(),
                idx: 1
            }
        );
        assert_eq!(message, "bad");
        assert_eq!(
            format!("{err}"),
            "compile error in :steps[1]: deserialize: bad"
        );
    }

    #[test]
    fn kwarg_deserialize_display_prefix_matches_kwarg_path_display() {
        // End-to-end pin: the `LispError::KwargDeserialize` variant's
        // Display rendering threads its typed `path: KwargPath` slot
        // through `KwargPath`'s `Display` impl directly (via the
        // `#[error("compile error in {path}: ...")]` annotation, no
        // intermediate helper). The full rendered diagnostic MUST be
        // anchored on the canonical `KwargPath`-projected prefix
        // across BOTH variants of `KwargPath` — a regression that
        // drifts either projection (e.g., re-introducing an inline
        // `format!` literal in a `#[error(..., fmt_fn(path))]` annotation
        // that diverges from `KwargPath`'s Display arm) fails-loudly
        // here.
        let scalar = LispError::KwargDeserialize {
            path: KwargPath::named("level"),
            message: "boom".into(),
        };
        assert_eq!(
            format!("{scalar}"),
            format!(
                "compile error in {}: deserialize: boom",
                KwargPath::named("level")
            )
        );

        let item = LispError::KwargDeserialize {
            path: KwargPath::item("steps", 3),
            message: "boom".into(),
        };
        assert_eq!(
            format!("{item}"),
            format!(
                "compile error in {}: deserialize: boom",
                KwargPath::item("steps", 3)
            )
        );
    }

    // ── CompilerSpecIo: disk-persistence structural-variant lift ────
    //
    // `compiler_spec_io_err` (the helper shared by all four
    // `realize_to_disk` / `load_from_disk` call sites in
    // `compiler_spec.rs`) was promoted from the `LispError::Compile`-
    // shaped triple to the structural `LispError::CompilerSpecIo {
    // stage, message }` variant — closing the LAST
    // `LispError::Compile { ... }` construction site in
    // `tatara-lisp/src/compiler_spec.rs`. The `stage` slot is the
    // typed closed-set `CompilerSpecIoStage` enum, so the
    // (operation, stage) pair is structurally constrained — only the
    // four reachable pairs (`realize_to_disk` × {serialize, write}
    // ⊎ `load_from_disk` × {read, deserialize}) are representable
    // in the variant.
    //
    // The tests below pin: (a) Display matches the legacy `"compile
    // error in {operation}: {stage}: {message}"` shape byte-for-byte
    // across all four stages; (b) the closed-set `operation()` /
    // `label()` projections; (c) the `CompilerSpecIoStage` enum is
    // Copy + Eq + Debug (matches the `MacroDefHead` posture); (d) the
    // legacy substring `"realize_to_disk"`, `"load_from_disk"`,
    // `"serialize: "`, `"write: "`, `"read: "`, `"deserialize: "`
    // survive the lift unchanged for substring-grep consumers. The
    // `position()` floor for both representative stages is pinned in
    // the main `position_is_none_for_non_positional_variants` block
    // above.

    #[test]
    fn compiler_spec_io_stage_operation_projects_realize_for_serialize_and_write() {
        // Both `realize_to_disk` stages share the same `operation()`
        // projection. Pin the closed-set posture: the operation slot
        // of the legacy `Compile`-shaped triple is now a TYPED
        // projection from `CompilerSpecIoStage`, not an
        // independently-passed `&'static str` that could drift.
        assert_eq!(
            super::CompilerSpecIoStage::RealizeToDiskSerialize.operation(),
            "realize_to_disk"
        );
        assert_eq!(
            super::CompilerSpecIoStage::RealizeToDiskWrite.operation(),
            "realize_to_disk"
        );
    }

    #[test]
    fn compiler_spec_io_stage_operation_projects_load_for_read_and_deserialize() {
        // Both `load_from_disk` stages share the same `operation()`
        // projection. Sibling to the realize-side assertion: pins the
        // bifurcation of the closed set by `operation()` is exhaustive
        // and exactly 2-way (`realize_to_disk` ⊎ `load_from_disk`).
        assert_eq!(
            super::CompilerSpecIoStage::LoadFromDiskRead.operation(),
            "load_from_disk"
        );
        assert_eq!(
            super::CompilerSpecIoStage::LoadFromDiskDeserialize.operation(),
            "load_from_disk"
        );
    }

    #[test]
    fn compiler_spec_io_stage_label_projects_canonical_stage_strings() {
        // Each `CompilerSpecIoStage` projects to its canonical
        // `label()` — the `{stage}` slot of the legacy `"{stage}:
        // {error}"` message. Pin all four projections so a regression
        // that drifts ANY label (e.g., to "ser", "load", "decode",
        // "json-out") fails-loudly here. The four labels are the
        // surface that `tatara-check`'s diagnostic capture and the
        // REPL substring-grep on today.
        assert_eq!(
            super::CompilerSpecIoStage::RealizeToDiskSerialize.label(),
            "serialize"
        );
        assert_eq!(
            super::CompilerSpecIoStage::RealizeToDiskWrite.label(),
            "write"
        );
        assert_eq!(super::CompilerSpecIoStage::LoadFromDiskRead.label(), "read");
        assert_eq!(
            super::CompilerSpecIoStage::LoadFromDiskDeserialize.label(),
            "deserialize"
        );
    }

    #[test]
    fn compiler_spec_io_stage_label_method_routes_through_typed_constants() {
        // PATH-UNIFORMITY: the inherent `Self::label(self)` method
        // MUST return the per-role `pub const` byte-for-byte for
        // each reachable variant. A regression that reverts ONE arm
        // to an inline `"serialize"` string literal (e.g. a merge-
        // conflict resolution that picked the pre-lift form)
        // silently reintroduces the ≥2 PRIME-DIRECTIVE trigger the
        // lift resolved — this test catches that by pinning the
        // arm's return value to the constant, so the two paths
        // (inline vs. typed constant) cannot both hold. Sibling
        // posture to
        // `kwarg_path_kind_label_method_routes_through_typed_constants`
        // on the `KwargPathKind` category-label algebra.
        assert_eq!(
            super::CompilerSpecIoStage::RealizeToDiskSerialize.label(),
            super::CompilerSpecIoStage::REALIZE_TO_DISK_SERIALIZE_LABEL,
            "CompilerSpecIoStage::RealizeToDiskSerialize.label() \
             drifted from CompilerSpecIoStage::\
             REALIZE_TO_DISK_SERIALIZE_LABEL — the match arm reverted \
             to an inline literal"
        );
        assert_eq!(
            super::CompilerSpecIoStage::RealizeToDiskWrite.label(),
            super::CompilerSpecIoStage::REALIZE_TO_DISK_WRITE_LABEL,
            "CompilerSpecIoStage::RealizeToDiskWrite.label() drifted \
             from CompilerSpecIoStage::REALIZE_TO_DISK_WRITE_LABEL — \
             the match arm reverted to an inline literal"
        );
        assert_eq!(
            super::CompilerSpecIoStage::LoadFromDiskRead.label(),
            super::CompilerSpecIoStage::LOAD_FROM_DISK_READ_LABEL,
            "CompilerSpecIoStage::LoadFromDiskRead.label() drifted \
             from CompilerSpecIoStage::LOAD_FROM_DISK_READ_LABEL — \
             the match arm reverted to an inline literal"
        );
        assert_eq!(
            super::CompilerSpecIoStage::LoadFromDiskDeserialize.label(),
            super::CompilerSpecIoStage::LOAD_FROM_DISK_DESERIALIZE_LABEL,
            "CompilerSpecIoStage::LoadFromDiskDeserialize.label() \
             drifted from CompilerSpecIoStage::\
             LOAD_FROM_DISK_DESERIALIZE_LABEL — the match arm reverted \
             to an inline literal"
        );
    }

    #[test]
    fn compiler_spec_io_stage_labels_has_expected_cardinality() {
        // Cardinality contract: `Self::LABELS.len() == 4` — pinned
        // at the declaration site by rustc's forced-arity check on
        // `[&'static str; 4]`. This test surfaces the arity as a
        // fail-loud runtime pin so a future refactor that switches
        // the array type to `&[&'static str]` (dropping the
        // compile-time arity forcing) doesn't silently loosen the
        // closed-set discipline the family relies on. Sibling
        // posture to `kwarg_path_kind_labels_has_expected_cardinality`
        // on the `KwargPathKind::LABELS` family.
        assert_eq!(
            super::CompilerSpecIoStage::LABELS.len(),
            4,
            "CompilerSpecIoStage::LABELS cardinality drifted from 4 \
             — the disk-persistence stage-label closed set gained or \
             lost a variant without the ALL / LABELS pair being \
             updated in tandem"
        );
    }

    #[test]
    fn compiler_spec_io_stage_labels_align_with_all_by_index() {
        // ALIGNMENT CONTRACT: `Self::LABELS[i] ==
        // Self::ALL[i].label()` element-wise. The two ALL arrays
        // (typed variants, canonical `&'static str` labels) share
        // ONE canonical declaration order — a regression that
        // reorders ONE array without reordering the other silently
        // misaligns every `zip(Self::ALL, Self::LABELS)` consumer
        // (LSP completion providers, metric-label emitters, coverage
        // reporters). Pinning by-index alignment here catches the
        // reorder at test time. Sibling posture to
        // `kwarg_path_kind_labels_align_with_all_by_index` on the
        // `KwargPathKind::LABELS` family.
        assert_eq!(
            super::CompilerSpecIoStage::LABELS.len(),
            super::CompilerSpecIoStage::ALL.len(),
            "CompilerSpecIoStage::LABELS and CompilerSpecIoStage::ALL \
             diverged in cardinality — the per-role constants and \
             enum variants must stay in lockstep"
        );
        for (i, stage) in super::CompilerSpecIoStage::ALL.iter().enumerate() {
            assert_eq!(
                super::CompilerSpecIoStage::LABELS[i],
                stage.label(),
                "CompilerSpecIoStage::LABELS[{i}] `{lb}` drifted from \
                 CompilerSpecIoStage::ALL[{i}].label() `{via_variant}` \
                 — the canonical declaration order of the two ALL \
                 arrays must match element-wise",
                lb = super::CompilerSpecIoStage::LABELS[i],
                via_variant = stage.label(),
            );
        }
    }

    #[test]
    fn compiler_spec_io_stage_labels_pairwise_distinct() {
        // PAIRWISE DISJOINTNESS: the four `&'static str` labels on
        // the disk-persistence stage-label algebra MUST differ so
        // any consumer that keys a hashmap / dispatch table on the
        // label bytes (`match label { "serialize" => ...,
        // "deserialize" => ..., ... }`) cannot route two variants
        // through the same arm. Family-wide sweep over LABELS ×
        // LABELS — supersedes any single per-pair assertion and
        // picks up new variants mechanically when the array grows.
        // Sibling posture to `kwarg_path_kind_labels_pairwise_distinct`
        // on the `KwargPathKind::LABELS` family.
        //
        // Note: unlike `KwargPathKind` / `ExpectedKwargShape`, the
        // parent enum keys `FromStr` on the compound
        // `"{operation}: {label}"` key rather than on `label` alone
        // (see `CompilerSpecIoStage::from_str`), so pairwise-distinct
        // labels are not a hard load-bearing invariant for the
        // FromStr sweep. But they ARE the load-bearing invariant for
        // every downstream consumer that keys on the label alone
        // (metric-label tables, LSP completion, `tatara-check` grep
        // budgets on the `{stage}:` prefix), and pinning the
        // property here catches a regression that collides two
        // variants on their singular label projection before those
        // consumer sites drift.
        for (i, a) in super::CompilerSpecIoStage::LABELS.iter().enumerate() {
            for (j, b) in super::CompilerSpecIoStage::LABELS.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "CompilerSpecIoStage::LABELS[{i}] `{a}` collides \
                     with CompilerSpecIoStage::LABELS[{j}] `{b}` — \
                     the singular label projection is no longer a \
                     bijection with ALL, breaking every consumer that \
                     keys on the label alone"
                );
            }
        }
    }

    #[test]
    fn compiler_spec_io_stage_operation_method_routes_through_typed_constants() {
        // PATH-UNIFORMITY: the inherent `Self::operation(self)` method
        // MUST return the per-role `pub const` byte-for-byte for
        // each reachable variant. A regression that reverts ONE arm
        // to an inline `"realize_to_disk"` string literal (e.g. a
        // merge-conflict resolution that picked the pre-lift form)
        // silently reintroduces the ≥2 PRIME-DIRECTIVE trigger the
        // lift resolved — this test catches that by pinning each
        // arm's return value to the constant, so the two paths
        // (inline vs. typed constant) cannot both hold. Sibling
        // posture to
        // `compiler_spec_io_stage_label_method_routes_through_typed_constants`
        // on the paired stage-label algebra.
        assert_eq!(
            super::CompilerSpecIoStage::RealizeToDiskSerialize.operation(),
            super::CompilerSpecIoStage::REALIZE_TO_DISK_OPERATION,
            "CompilerSpecIoStage::RealizeToDiskSerialize.operation() \
             drifted from CompilerSpecIoStage::\
             REALIZE_TO_DISK_OPERATION — the match arm reverted to an \
             inline literal"
        );
        assert_eq!(
            super::CompilerSpecIoStage::RealizeToDiskWrite.operation(),
            super::CompilerSpecIoStage::REALIZE_TO_DISK_OPERATION,
            "CompilerSpecIoStage::RealizeToDiskWrite.operation() \
             drifted from CompilerSpecIoStage::\
             REALIZE_TO_DISK_OPERATION — the match arm reverted to an \
             inline literal"
        );
        assert_eq!(
            super::CompilerSpecIoStage::LoadFromDiskRead.operation(),
            super::CompilerSpecIoStage::LOAD_FROM_DISK_OPERATION,
            "CompilerSpecIoStage::LoadFromDiskRead.operation() drifted \
             from CompilerSpecIoStage::LOAD_FROM_DISK_OPERATION — the \
             match arm reverted to an inline literal"
        );
        assert_eq!(
            super::CompilerSpecIoStage::LoadFromDiskDeserialize.operation(),
            super::CompilerSpecIoStage::LOAD_FROM_DISK_OPERATION,
            "CompilerSpecIoStage::LoadFromDiskDeserialize.operation() \
             drifted from CompilerSpecIoStage::LOAD_FROM_DISK_OPERATION \
             — the match arm reverted to an inline literal"
        );
    }

    #[test]
    fn compiler_spec_io_stage_operations_has_expected_cardinality() {
        // Cardinality contract: `Self::OPERATIONS.len() == 4` —
        // pinned at the declaration site by rustc's forced-arity
        // check on `[&'static str; 4]`. This test surfaces the arity
        // as a fail-loud runtime pin so a future refactor that
        // switches the array type to `&[&'static str]` (dropping the
        // compile-time arity forcing) doesn't silently loosen the
        // closed-set discipline the family relies on. Sibling posture
        // to `compiler_spec_io_stage_labels_has_expected_cardinality`
        // on the paired stage-label algebra.
        assert_eq!(
            super::CompilerSpecIoStage::OPERATIONS.len(),
            4,
            "CompilerSpecIoStage::OPERATIONS cardinality drifted from \
             4 — the disk-persistence operation-label closed set \
             gained or lost a variant without the ALL / OPERATIONS \
             pair being updated in tandem"
        );
    }

    #[test]
    fn compiler_spec_io_stage_operations_align_with_all_by_index() {
        // ALIGNMENT CONTRACT: `Self::OPERATIONS[i] ==
        // Self::ALL[i].operation()` element-wise. The two ALL arrays
        // (typed variants, canonical `&'static str` operation labels)
        // share ONE canonical declaration order — a regression that
        // reorders ONE array without reordering the other silently
        // misaligns every `zip(Self::ALL, Self::OPERATIONS)` consumer
        // (LSP completion providers keyed on the operation slot,
        // metric-label emitters, coverage reporters that walk the
        // operation × stage compound-key surface). Pinning by-index
        // alignment here catches the reorder at test time. Sibling
        // posture to `compiler_spec_io_stage_labels_align_with_all_by_index`
        // on the paired stage-label algebra.
        assert_eq!(
            super::CompilerSpecIoStage::OPERATIONS.len(),
            super::CompilerSpecIoStage::ALL.len(),
            "CompilerSpecIoStage::OPERATIONS and \
             CompilerSpecIoStage::ALL diverged in cardinality — the \
             per-role constants and enum variants must stay in \
             lockstep"
        );
        for (i, stage) in super::CompilerSpecIoStage::ALL.iter().enumerate() {
            assert_eq!(
                super::CompilerSpecIoStage::OPERATIONS[i],
                stage.operation(),
                "CompilerSpecIoStage::OPERATIONS[{i}] `{op}` drifted \
                 from CompilerSpecIoStage::ALL[{i}].operation() \
                 `{via_variant}` — the canonical declaration order \
                 of the two ALL arrays must match element-wise",
                op = super::CompilerSpecIoStage::OPERATIONS[i],
                via_variant = stage.operation(),
            );
        }
    }

    #[test]
    fn compiler_spec_io_stage_operations_partition_all_two_ways() {
        // TWO-WAY PARTITION CONTRACT: unlike `Self::LABELS` — whose
        // four elements are pairwise distinct because each `label()`
        // projection is bijective with its variant — `Self::OPERATIONS`
        // contains DUPLICATES by construction. The operation
        // projection bifurcates the closed set into exactly two
        // disjoint groups of two: `{RealizeToDiskSerialize,
        // RealizeToDiskWrite}` share `"realize_to_disk"` and
        // `{LoadFromDiskRead, LoadFromDiskDeserialize}` share
        // `"load_from_disk"`. The 2-of-2-to-2 shape is load-bearing
        // for the compound-key `"{operation}: {label}"` surface —
        // if the operation projection ever grew bijective with
        // `ALL` the compound key would collapse to `label`-only and
        // the parse boundary would silently accept unreachable
        // cross-product pairs. Pin the exact multiplicities here so
        // a future refactor that (a) adds a distinct per-variant
        // operation, or (b) collapses the two operations into one
        // shared string, fails-loudly. Sibling posture to
        // `compiler_spec_io_stage_labels_pairwise_distinct` on the
        // paired stage-label algebra — where LABELS pins
        // distinctness, OPERATIONS pins the exact two-way partition
        // multiplicity.
        let realize_count = super::CompilerSpecIoStage::OPERATIONS
            .iter()
            .filter(|&&op| op == super::CompilerSpecIoStage::REALIZE_TO_DISK_OPERATION)
            .count();
        let load_count = super::CompilerSpecIoStage::OPERATIONS
            .iter()
            .filter(|&&op| op == super::CompilerSpecIoStage::LOAD_FROM_DISK_OPERATION)
            .count();
        assert_eq!(
            realize_count, 2,
            "CompilerSpecIoStage::OPERATIONS multiplicity of \
             REALIZE_TO_DISK_OPERATION drifted from 2 — the \
             realize-side bifurcation over {{serialize, write}} is \
             load-bearing for the compound-key surface"
        );
        assert_eq!(
            load_count, 2,
            "CompilerSpecIoStage::OPERATIONS multiplicity of \
             LOAD_FROM_DISK_OPERATION drifted from 2 — the load-side \
             bifurcation over {{read, deserialize}} is load-bearing \
             for the compound-key surface"
        );
        assert_eq!(
            realize_count + load_count,
            super::CompilerSpecIoStage::OPERATIONS.len(),
            "CompilerSpecIoStage::OPERATIONS gained an operation label \
             outside the two-way partition — the closed-set operation \
             axis is no longer a clean {{realize_to_disk ⊎ load_from_disk}} \
             bifurcation"
        );
        assert_ne!(
            super::CompilerSpecIoStage::REALIZE_TO_DISK_OPERATION,
            super::CompilerSpecIoStage::LOAD_FROM_DISK_OPERATION,
            "CompilerSpecIoStage::REALIZE_TO_DISK_OPERATION collided \
             with CompilerSpecIoStage::LOAD_FROM_DISK_OPERATION — the \
             two-way partition collapsed to one group, breaking every \
             compound-key `{{operation}}: {{label}}` round-trip"
        );
    }

    #[test]
    fn compiler_spec_io_display_renders_legacy_shape_for_realize_serialize() {
        // `RealizeToDiskSerialize` — the `serde_json::to_string_pretty`
        // failure inside `realize_to_disk`. The variant renders the
        // legacy `"compile error in realize_to_disk: serialize:
        // {message}"` shape byte-for-byte — same wording as the
        // pre-lift `Compile { form: "realize_to_disk", message:
        // "serialize: {e}" }` triple.
        let err = LispError::CompilerSpecIo {
            stage: super::CompilerSpecIoStage::RealizeToDiskSerialize,
            message: "expected struct CompilerSpec".into(),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in realize_to_disk: serialize: expected struct CompilerSpec"
        );
    }

    #[test]
    fn compiler_spec_io_display_renders_legacy_shape_for_realize_write() {
        // `RealizeToDiskWrite` — the `std::fs::write` failure inside
        // `realize_to_disk`. Pin path-uniformity across the second
        // stage of the realize-side operation: same operation prefix,
        // distinct stage label (`write` vs `serialize`).
        let err = LispError::CompilerSpecIo {
            stage: super::CompilerSpecIoStage::RealizeToDiskWrite,
            message: "No such file or directory (os error 2)".into(),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in realize_to_disk: write: No such file or directory (os error 2)"
        );
    }

    #[test]
    fn compiler_spec_io_display_renders_legacy_shape_for_load_read() {
        // `LoadFromDiskRead` — the `std::fs::read_to_string` failure
        // inside `load_from_disk`. Pin path-uniformity across the
        // operation slot: `load_from_disk` vs `realize_to_disk` are
        // structurally distinct via the typed enum, both round-trip
        // through Display unchanged.
        let err = LispError::CompilerSpecIo {
            stage: super::CompilerSpecIoStage::LoadFromDiskRead,
            message: "No such file or directory (os error 2)".into(),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in load_from_disk: read: No such file or directory (os error 2)"
        );
    }

    #[test]
    fn compiler_spec_io_display_renders_legacy_shape_for_load_deserialize() {
        // `LoadFromDiskDeserialize` — the `serde_json::from_str`
        // failure inside `load_from_disk`. Pin path-uniformity across
        // the fourth and final reachable stage. Together with the
        // three sibling tests, this closes the structural-completeness
        // floor of the closed-set `CompilerSpecIoStage` × Display
        // matrix — all four reachable pairs are pinned.
        let err = LispError::CompilerSpecIo {
            stage: super::CompilerSpecIoStage::LoadFromDiskDeserialize,
            message: "expected value at line 1 column 1".into(),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in load_from_disk: deserialize: expected value at line 1 column 1"
        );
    }

    #[test]
    fn compiler_spec_io_display_carries_serde_json_diagnostic_unchanged() {
        // Use a real `serde_json::Error` so the test exercises a
        // representative `{e}` shape and pins that the variant's
        // Display rendering threads the underlying diagnostic through
        // unchanged. Same posture as `domain_serialize_display_carries_
        // serde_json_diagnostic_unchanged` and
        // `kwarg_deserialize_display_carries_serde_json_diagnostic_
        // unchanged`.
        let raw = serde_json::from_str::<i32>("not-a-number")
            .expect_err("parse must fail")
            .to_string();
        let err = LispError::CompilerSpecIo {
            stage: super::CompilerSpecIoStage::LoadFromDiskDeserialize,
            message: raw.clone(),
        };
        assert_eq!(
            format!("{err}"),
            format!("compile error in load_from_disk: deserialize: {raw}")
        );
    }

    #[test]
    fn compiler_spec_io_display_preserves_legacy_substring_for_message_grep() {
        // Pin the legacy substring set — `"realize_to_disk"`,
        // `"load_from_disk"`, `"serialize: "`, `"write: "`,
        // `"read: "`, `"deserialize: "` — as a separate assertion so a
        // regression that drifts ANY of the six surface words (e.g.,
        // to "save", "load", "json-out", "json-in") fails-loudly here.
        // The substrings are what consumers downstream (`tatara-check`,
        // the REPL) substring-match on today; the prefix matches the
        // legacy `Compile { form: "{operation}", message: "{stage}:
        // {e}" }` byte-for-byte across all four reachable pairs.
        let realize_serialize = LispError::CompilerSpecIo {
            stage: super::CompilerSpecIoStage::RealizeToDiskSerialize,
            message: "boom".into(),
        };
        let msg = format!("{realize_serialize}");
        assert!(
            msg.contains("realize_to_disk"),
            "expected realize-side operation in message, got: {msg}"
        );
        assert!(
            msg.contains("serialize: "),
            "expected serialize-stage substring in message, got: {msg}"
        );

        let realize_write = LispError::CompilerSpecIo {
            stage: super::CompilerSpecIoStage::RealizeToDiskWrite,
            message: "boom".into(),
        };
        let msg = format!("{realize_write}");
        assert!(
            msg.contains("write: "),
            "expected write-stage substring in message, got: {msg}"
        );

        let load_read = LispError::CompilerSpecIo {
            stage: super::CompilerSpecIoStage::LoadFromDiskRead,
            message: "boom".into(),
        };
        let msg = format!("{load_read}");
        assert!(
            msg.contains("load_from_disk"),
            "expected load-side operation in message, got: {msg}"
        );
        assert!(
            msg.contains("read: "),
            "expected read-stage substring in message, got: {msg}"
        );

        let load_deserialize = LispError::CompilerSpecIo {
            stage: super::CompilerSpecIoStage::LoadFromDiskDeserialize,
            message: "boom".into(),
        };
        let msg = format!("{load_deserialize}");
        assert!(
            msg.contains("deserialize: "),
            "expected deserialize-stage substring in message, got: {msg}"
        );
    }

    #[test]
    fn compiler_spec_io_display_empty_message_renders_bare_stage_marker() {
        // Edge case: an empty `message` slot renders as `"compile
        // error in {operation}: {stage}: "` — pin the trailing space
        // after the stage marker stays put across all four pairs. A
        // regression that strips trailing whitespace (e.g., via
        // `.trim_end()`) or drops the marker entirely fails-loudly here.
        // Sibling of `domain_serialize_display_empty_message_renders_
        // bare_prefix`.
        let err = LispError::CompilerSpecIo {
            stage: super::CompilerSpecIoStage::RealizeToDiskWrite,
            message: String::new(),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in realize_to_disk: write: "
        );
    }

    #[test]
    fn compiler_spec_io_stage_is_copy_and_partial_eq() {
        // Pin the closed-set posture: `CompilerSpecIoStage` derives
        // Copy + PartialEq + Eq + Debug so it composes ergonomically
        // in tests and in consumer pattern-matches (no clone-and-
        // own dance). Same posture as `MacroDefHead`. A regression
        // that drops Copy fails-loudly here (the let-binding would
        // move out instead of copy).
        let stage = super::CompilerSpecIoStage::LoadFromDiskRead;
        let copied = stage;
        assert_eq!(stage, copied);
        assert_eq!(stage, super::CompilerSpecIoStage::LoadFromDiskRead);
        assert_ne!(stage, super::CompilerSpecIoStage::RealizeToDiskWrite);
    }

    #[test]
    fn compiler_spec_io_stage_all_is_unique_and_complete() {
        // Closed-set posture: `ALL` enumerates every reachable variant
        // EXACTLY ONCE — no duplicates, no omissions. The `[Self; 4]`
        // array literal in the declaration forces the arity at compile
        // time; this test catches the orthogonal failure modes — a
        // future variant added at the type without being added to ALL
        // (silently dropped from every consumer's sweep), or a typo
        // that duplicates an entry (silently double-counted). Same
        // truth-table pinning every sibling closed-set lift in the
        // workspace uses (ExpectedKwargShape::ALL, SexpShape::ALL,
        // MacroDefHead::ALL, UnquoteForm::ALL, …).
        //
        // The asserted compound keys are the canonical (operation,
        // label) pairs the disk-persistence surface emits — the four
        // entries are the reachable cells of the `operation × label`
        // cross-product, and the four-out-of-eight partiality is the
        // load-bearing thing: `realize_to_disk × {read, deserialize}`
        // and `load_from_disk × {serialize, write}` are conceivable
        // but unreachable, and `FromStr` enforces that asymmetry at
        // the parse boundary.
        assert_eq!(super::CompilerSpecIoStage::ALL.len(), 4);
        let mut sorted: Vec<String> = super::CompilerSpecIoStage::ALL
            .iter()
            .map(std::string::ToString::to_string)
            .collect();
        sorted.sort_unstable();
        let mut deduped = sorted.clone();
        deduped.dedup();
        assert_eq!(
            sorted, deduped,
            "CompilerSpecIoStage::ALL must not contain duplicates"
        );
        assert_eq!(
            sorted,
            vec![
                "load_from_disk: deserialize".to_string(),
                "load_from_disk: read".to_string(),
                "realize_to_disk: serialize".to_string(),
                "realize_to_disk: write".to_string(),
            ],
            "CompilerSpecIoStage::ALL must cover every reachable (operation, label) pair"
        );
    }

    #[test]
    fn compiler_spec_io_stage_display_matches_diagnostic_prefix() {
        // Pin standalone Display to the canonical compound key — the
        // exact substring that lands between `"compile error in "` and
        // `": {message}"` inside the LispError::CompilerSpecIo
        // rendering. Consumers that extract the (operation, label)
        // prefix from a rendered diagnostic (LSP code-actions, REPL
        // replay) round-trip the captured substring through `FromStr`
        // back into the typed variant exactly. A regression that
        // drifts either side (Display's separator, the LispError's
        // `#[error(...)]` annotation, the projection methods) fails
        // loudly here because both renderings must agree.
        for stage in super::CompilerSpecIoStage::ALL {
            let standalone = stage.to_string();
            let full = format!(
                "{}",
                LispError::CompilerSpecIo {
                    stage,
                    message: "MSG".into()
                }
            );
            let prefix = full
                .strip_prefix("compile error in ")
                .expect("legacy rendering prefix must hold");
            let extracted = prefix
                .strip_suffix(": MSG")
                .expect("legacy rendering suffix must hold");
            assert_eq!(
                extracted, standalone,
                "extracted prefix `{extracted}` must equal standalone Display `{standalone}`"
            );
        }
    }

    #[test]
    fn compiler_spec_io_stage_compound_key_round_trips_through_from_str() {
        // Bidirectional `Display` ↔ `FromStr` contract: for every
        // variant in ALL, `stage.to_string().parse() == Ok(stage)`. A
        // regression that drifts the (variant, compound-key) pairing
        // at the `Display` impl (typo, missing separator, swapped
        // projection order) OR at the `FromStr` decode body (off-by-
        // one, missing variant in the sweep) fails-loudly here. The
        // canonical-key site is singular (`Display` projects through
        // `operation()` and `label()`) so the round-trip is the only
        // way the typed surface and the rendered diagnostic literal
        // can drift apart — pinning it here means they cannot. Mirror
        // of `expected_kwarg_shape_label_round_trips_through_from_str`
        // and every sibling closed-set round-trip in the workspace —
        // the difference is the compound-key shape rather than a
        // single label.
        for stage in super::CompilerSpecIoStage::ALL {
            let key = stage.to_string();
            let parsed: super::CompilerSpecIoStage = key
                .parse()
                .expect("every ALL variant's compound key must round-trip through FromStr");
            assert_eq!(
                parsed, stage,
                "FromStr({key}) must round-trip to the same variant"
            );
        }
    }

    #[test]
    fn compiler_spec_io_stage_from_str_rejects_partial_and_unreachable_keys() {
        // The compound-key shape is load-bearing: `FromStr` rejects
        // partial keys (one of the two projection slots alone),
        // separator-less inputs, AND the four conceivable-but-
        // unreachable cross-product pairs that the disk-persistence
        // surface does NOT emit. The partial-rejection turns the
        // call-site invariant ("only the four call sites in
        // `compiler_spec.rs` construct stages, each pairs the correct
        // operation with the correct stage") into a parse-boundary
        // invariant ("the four reachable pairs are structurally
        // distinct from the four unreachable ones").
        //
        // Without this guard a future LSP that captures the prefix
        // `"load_from_disk: write"` from a hand-crafted (corrupted)
        // log and replays it through `FromStr` would silently round-
        // trip an unreachable identity into the typed enum.
        for partial in [
            "serialize",
            "write",
            "read",
            "deserialize",
            "realize_to_disk",
            "load_from_disk",
            "",
        ] {
            partial.parse::<super::CompilerSpecIoStage>().expect_err(
                "partial key (one projection slot alone, or empty) must NOT decode to a variant",
            );
        }
        for unreachable in [
            "realize_to_disk: read",
            "realize_to_disk: deserialize",
            "load_from_disk: serialize",
            "load_from_disk: write",
        ] {
            unreachable
                .parse::<super::CompilerSpecIoStage>()
                .expect_err(
                "conceivable-but-unreachable (operation, label) pair must NOT decode to a variant",
            );
        }
        // Sanity: each reachable pair still decodes.
        assert_eq!(
            "realize_to_disk: serialize"
                .parse::<super::CompilerSpecIoStage>()
                .unwrap(),
            super::CompilerSpecIoStage::RealizeToDiskSerialize
        );
        assert_eq!(
            "load_from_disk: deserialize"
                .parse::<super::CompilerSpecIoStage>()
                .unwrap(),
            super::CompilerSpecIoStage::LoadFromDiskDeserialize
        );
    }

    #[test]
    fn unknown_compiler_spec_io_stage_carries_offending_input_verbatim() {
        // Operator-facing diagnostic contract: the offending input
        // lands in the typed error verbatim — no normalization, no
        // case-folding, no truncation. Pin the exact `#[error(...)]`
        // rendering AND the typed `.0` field projection so a future
        // refactor that normalizes (e.g. `.to_lowercase()`) before
        // building the error or that drops the input fails-loudly
        // here. Symmetric to every sibling `Unknown*` carrier in the
        // workspace (`UnknownExpectedKwargShape`, `UnknownSexpShape`,
        // `UnknownMacroDefHead`, …).
        let err: super::UnknownCompilerSpecIoStage = "Realize_to_disk: serialize"
            .parse::<super::CompilerSpecIoStage>()
            .expect_err("capitalized operation must NOT decode — keys are byte-equal");
        assert_eq!(err.0, "Realize_to_disk: serialize");
        assert_eq!(
            format!("{err}"),
            "unknown compiler spec io stage: Realize_to_disk: serialize"
        );

        let err: super::UnknownCompilerSpecIoStage = "load_from_disk: write"
            .parse::<super::CompilerSpecIoStage>()
            .expect_err("unreachable cross-product pair must NOT decode");
        assert_eq!(err.0, "load_from_disk: write");
        assert_eq!(
            format!("{err}"),
            "unknown compiler spec io stage: load_from_disk: write"
        );

        let err: super::UnknownCompilerSpecIoStage = ""
            .parse::<super::CompilerSpecIoStage>()
            .expect_err("empty input must NOT decode to a CompilerSpecIoStage");
        assert_eq!(err.0, "");
        assert_eq!(format!("{err}"), "unknown compiler spec io stage: ");
    }

    #[test]
    fn compiler_spec_io_stage_compound_key_separator_is_colon_space() {
        // Pin the canonical `": "` compound-key separator bytes
        // byte-for-byte on the typed algebra. A regression that
        // silently drops the ASCII space (`":"`), doubles it (`":  "`),
        // or swaps to a different punctuation family (`" - "`, `" | "`)
        // fails-loudly here — every consumer that binds against the
        // constant picks up the drift at compile time, not at a
        // customer's rendered diagnostic. The exact byte sequence
        // matters: LSP substring extractors that key on `rsplit_once(":
        // ")` (matching the pre-lift inline literal) and the pre-lift
        // `Display` format string `"{}: {}"` both threaded the SAME
        // three bytes; post-lift they thread the SAME `pub const`.
        assert_eq!(
            super::CompilerSpecIoStage::COMPOUND_KEY_SEPARATOR,
            ": ",
            "compound-key separator must be ASCII colon-space byte-for-byte",
        );
        assert_eq!(
            super::CompilerSpecIoStage::COMPOUND_KEY_SEPARATOR.len(),
            2,
            "compound-key separator is exactly two bytes — no invisible whitespace drift",
        );
        assert_eq!(
            super::CompilerSpecIoStage::COMPOUND_KEY_SEPARATOR.as_bytes(),
            b": ",
            "compound-key separator bytes are `:` then ` ` — pinned byte-array shape",
        );
    }

    #[test]
    fn compiler_spec_io_stage_display_composes_operation_separator_label_verbatim() {
        // For every variant, the `Display` rendering equals the
        // triple-concatenation `operation() ++ COMPOUND_KEY_SEPARATOR
        // ++ label()` byte-for-byte. A regression that reintroduces
        // the pre-lift inline `": "` literal at the `write!` format
        // string, or swaps the projection order, or inserts extra
        // padding, fails loudly here — the composed reference walks
        // the SAME three typed source-of-truth axes the impl body
        // does. Sibling posture to
        // `compiler_spec_io_stage_operation_method_routes_through_typed_constants`
        // and `compiler_spec_io_stage_label_method_routes_through_typed_constants`
        // on the operation and label projection axes: the SAME
        // through-the-typed-constants routing contract now covers the
        // COMPOSITION axis too.
        for stage in super::CompilerSpecIoStage::ALL {
            let rendered = stage.to_string();
            let expected = {
                let mut out = String::with_capacity(
                    stage.operation().len()
                        + super::CompilerSpecIoStage::COMPOUND_KEY_SEPARATOR.len()
                        + stage.label().len(),
                );
                out.push_str(stage.operation());
                out.push_str(super::CompilerSpecIoStage::COMPOUND_KEY_SEPARATOR);
                out.push_str(stage.label());
                out
            };
            assert_eq!(
                rendered, expected,
                "Display for {stage:?} must compose `operation` ++ COMPOUND_KEY_SEPARATOR ++ `label` verbatim",
            );
        }
    }

    #[test]
    fn compiler_spec_io_stage_from_str_uses_typed_separator_bytes() {
        // Pin the parse boundary to the typed separator bytes: an
        // input that swaps the separator (colon-alone `":"`, space-
        // alone `" "`, wrong punctuation `" | "`) fails-loudly even
        // if the operation + label slot bytes are otherwise correct.
        // A regression that drops the ASCII space from the
        // `split_once` argument after a clippy `single_char_pattern`
        // suggestion would silently accept `"realize_to_disk:serialize"`
        // as a variant — this test rejects it at the parse boundary.
        for wrong_separator in [":", "  ", " : ", " ", "|", " - ", "\t"] {
            let key = {
                let mut out = String::new();
                out.push_str(super::CompilerSpecIoStage::RealizeToDiskSerialize.operation());
                out.push_str(wrong_separator);
                out.push_str(super::CompilerSpecIoStage::RealizeToDiskSerialize.label());
                out
            };
            key.parse::<super::CompilerSpecIoStage>().expect_err(
                "compound key with wrong-separator bytes must NOT decode — the parse boundary keys on COMPOUND_KEY_SEPARATOR verbatim",
            );
        }
        // Sanity: constructing the input through the typed constant
        // still succeeds — the constant is the source of truth on
        // both the Display and the FromStr sides.
        let key = {
            let mut out = String::new();
            out.push_str(super::CompilerSpecIoStage::LoadFromDiskRead.operation());
            out.push_str(super::CompilerSpecIoStage::COMPOUND_KEY_SEPARATOR);
            out.push_str(super::CompilerSpecIoStage::LoadFromDiskRead.label());
            out
        };
        assert_eq!(
            key.parse::<super::CompilerSpecIoStage>()
                .expect("compound key composed through COMPOUND_KEY_SEPARATOR must decode"),
            super::CompilerSpecIoStage::LoadFromDiskRead,
        );
    }

    #[test]
    fn compiler_spec_io_stage_display_middle_bytes_equal_typed_separator() {
        // Extract the middle bytes of every variant's `Display`
        // rendering — the substring between the operation prefix and
        // the label suffix — and pin them to
        // `COMPOUND_KEY_SEPARATOR`. This closes the loop from the
        // OTHER direction: the two projection-axis tests
        // (`operation_method_routes_through_typed_constants`,
        // `label_method_routes_through_typed_constants`) pin what
        // the operation and label slots ARE at rendering time; this
        // test pins what everything BETWEEN them is. Together the
        // three tests span every byte of every variant's rendered
        // compound key by threading each byte through some typed
        // source-of-truth constant on `CompilerSpecIoStage` —
        // matching the same span posture `Self::OPERATIONS +
        // Self::LABELS` establishes at the (variant → slot bytes)
        // aggregate-array level.
        for stage in super::CompilerSpecIoStage::ALL {
            let rendered = stage.to_string();
            let after_op = rendered
                .strip_prefix(stage.operation())
                .expect("Display must start with operation bytes");
            let middle = after_op
                .strip_suffix(stage.label())
                .expect("Display must end with label bytes");
            assert_eq!(
                middle,
                super::CompilerSpecIoStage::COMPOUND_KEY_SEPARATOR,
                "the substring between operation and label in Display for {stage:?} must be COMPOUND_KEY_SEPARATOR verbatim",
            );
        }
    }

    // ── TemplateInvariantKind + TemplateInvariant variant ───────────
    //
    // Closed-set posture for the bytecode-runtime invariant surface in
    // `macro_expand.rs::apply_compiled`. The index payload of the Subst /
    // Splice gates lives INSIDE the variants (`SubstBadIndex(usize)` /
    // `SpliceBadIndex(usize)`), so the invalid combination "stack-gate
    // kind with an op-index" (e.g. `EndListEmptyStack` carrying a
    // `usize`) is structurally unrepresentable. Display matches the
    // legacy `Compile`-shaped diagnostic byte-for-byte through the
    // `TemplateInvariantKind::message()` projection so authoring-tool
    // substring greps see no drift across the lift.

    #[test]
    fn template_invariant_kind_message_for_subst_bad_idx() {
        // `SubstBadIndex(idx)` projects to the canonical
        // `"compiled template referenced bad param index {idx}"`
        // shape — byte-for-byte equivalent to the pre-lift inline
        // `format!()` at the Subst gate.
        assert_eq!(
            super::TemplateInvariantKind::SubstBadIndex(99).message(),
            "compiled template referenced bad param index 99"
        );
        assert_eq!(
            super::TemplateInvariantKind::SubstBadIndex(0).message(),
            "compiled template referenced bad param index 0"
        );
    }

    #[test]
    fn template_invariant_kind_message_for_splice_bad_idx() {
        // `SpliceBadIndex(idx)` projects to the canonical
        // `"compiled template referenced bad splice index {idx}"`
        // shape — byte-for-byte equivalent to the pre-lift inline
        // `format!()` at the Splice gate. Distinct word (`splice` vs
        // `param`) keeps the two gates legible in diagnostic output.
        assert_eq!(
            super::TemplateInvariantKind::SpliceBadIndex(42).message(),
            "compiled template referenced bad splice index 42"
        );
    }

    #[test]
    fn template_invariant_kind_message_for_endlist_empty_stack() {
        // `EndListEmptyStack` projects to the canonical static-string
        // shape — no dynamic payload, no `format!()` overhead. The
        // pre-lift inline `&'static str` literal at the EndList gate
        // is preserved verbatim.
        assert_eq!(
            super::TemplateInvariantKind::EndListEmptyStack.message(),
            "compiled template: EndList with empty stack"
        );
    }

    #[test]
    fn template_invariant_kind_message_for_final_no_value() {
        // `FinalNoValue` projects to the canonical static-string
        // shape for the post-loop final-pop gate. Preserves the
        // pre-lift inline `&'static str` literal verbatim.
        assert_eq!(
            super::TemplateInvariantKind::FinalNoValue.message(),
            "compiled template produced no value"
        );
    }

    #[test]
    fn template_invariant_kind_static_message_constants_pin_canonical_bytes() {
        // Pin each per-role `pub const *_MESSAGE: &'static str` at its
        // exact canonical byte string — the source-of-truth constants
        // the `message` projection routes the STATIC 2-of-4 subset
        // arms through. A rename here (say, if a future extension
        // ports the byte prefix from `"compiled template"` to
        // `"compiled macro template"`) must land at ONE `pub const`
        // per role rather than at TWO sites (the per-role const AND
        // an inline arm literal). Sibling posture to
        // `macro_def_head_keyword_constants_pin_canonical_bytes` /
        // `unquote_form_label_constants_pin_canonical_bytes` /
        // `expected_kwarg_shape_label_constants_pin_canonical_bytes`
        // on the peer closed-set surfaces.
        assert_eq!(
            super::TemplateInvariantKind::END_LIST_EMPTY_STACK_MESSAGE,
            "compiled template: EndList with empty stack",
            "END_LIST_EMPTY_STACK_MESSAGE must pin the exact mid-loop stack-gate diagnostic bytes",
        );
        assert_eq!(
            super::TemplateInvariantKind::FINAL_NO_VALUE_MESSAGE,
            "compiled template produced no value",
            "FINAL_NO_VALUE_MESSAGE must pin the exact post-loop final-pop diagnostic bytes",
        );
    }

    #[test]
    fn template_invariant_kind_static_messages_pin_two_arm_forced_arity_array() {
        // Pin `STATIC_MESSAGES: [&'static str; 2]` as the family-wide
        // forced-arity ALL array over the STATIC 2-of-4 subset
        // carving. The array literal's arity IS the closed-set-size
        // proof — rustc's `[&'static str; 2]` check on the const's
        // type fails compilation if a future refactor adds a third
        // static arm without extending the array's length in
        // lockstep. Cardinality pin at the runtime layer is a
        // fail-loud belt-and-braces peer to the compile-time
        // `[_; 2]` check: a hypothetical port to `&[&'static str]`
        // (a slice, losing the arity discipline) fails here rather
        // than silently loosening the closed-set discipline.
        assert_eq!(
            super::TemplateInvariantKind::STATIC_MESSAGES.len(),
            2,
            "STATIC_MESSAGES must have exactly two entries — the 2-of-4 static subset carving",
        );
        assert_eq!(
            super::TemplateInvariantKind::STATIC_MESSAGES,
            [
                super::TemplateInvariantKind::END_LIST_EMPTY_STACK_MESSAGE,
                super::TemplateInvariantKind::FINAL_NO_VALUE_MESSAGE,
            ],
            "STATIC_MESSAGES must compose from the two per-role message constants in declaration order",
        );
    }

    #[test]
    fn template_invariant_kind_message_static_projects_static_subset_to_typed_option() {
        // Pin `message_static(self) -> Option<&'static str>`'s per-arm
        // truth table: the two STATIC arms project to `Some(bytes)`
        // routed through the per-role `pub const`s; the two dynamic
        // arms (regardless of payload) project to `None`. Payload
        // invariance on the dynamic arms is load-bearing: a
        // regression that surfaces the payload's `usize` bytes on
        // the `Option<&'static str>` axis (say, by lifting the
        // format prefix to a per-role static-str) would silently
        // widen the static subset — this test pins the current
        // 2-of-4 carving.
        assert_eq!(
            super::TemplateInvariantKind::EndListEmptyStack.message_static(),
            Some(super::TemplateInvariantKind::END_LIST_EMPTY_STACK_MESSAGE),
        );
        assert_eq!(
            super::TemplateInvariantKind::FinalNoValue.message_static(),
            Some(super::TemplateInvariantKind::FINAL_NO_VALUE_MESSAGE),
        );
        // Dynamic arms project to None regardless of payload value —
        // the `usize` bytes format into `message()`'s dynamic
        // fallthrough closure and cannot bind to a `&'static str`
        // on this axis.
        for idx in [0_usize, 1, 42, 99, usize::MAX] {
            assert_eq!(
                super::TemplateInvariantKind::SubstBadIndex(idx).message_static(),
                None,
                "SubstBadIndex({idx}) must project to None — the `usize` payload cannot bind to a &'static str",
            );
            assert_eq!(
                super::TemplateInvariantKind::SpliceBadIndex(idx).message_static(),
                None,
                "SpliceBadIndex({idx}) must project to None — the `usize` payload cannot bind to a &'static str",
            );
        }
    }

    #[test]
    fn template_invariant_kind_static_messages_align_with_message_static_by_index() {
        // Pin the ALIGNMENT contract:
        // `Self::STATIC_MESSAGES[0] == Self::EndListEmptyStack.message_static().unwrap()`
        // and
        // `Self::STATIC_MESSAGES[1] == Self::FinalNoValue.message_static().unwrap()`
        // element-wise. A regression that swaps the array's ordering
        // against the projection method's arm order (say, a future
        // refactor that reorders the enum variants without
        // reordering the array) fails loudly here. Sibling posture
        // to `kwarg_path_kind_labels_align_with_all_by_index`,
        // `expected_kwarg_shape_labels_align_with_all_by_index`,
        // `macro_def_head_keywords_align_with_all_by_index` on the
        // peer closed-set surfaces.
        assert_eq!(
            super::TemplateInvariantKind::STATIC_MESSAGES[0],
            super::TemplateInvariantKind::EndListEmptyStack
                .message_static()
                .unwrap(),
        );
        assert_eq!(
            super::TemplateInvariantKind::STATIC_MESSAGES[1],
            super::TemplateInvariantKind::FinalNoValue
                .message_static()
                .unwrap(),
        );
    }

    #[test]
    fn template_invariant_kind_message_delegates_static_arms_through_message_static() {
        // Pin the `message()` composition contract: for every arm on
        // the STATIC 2-of-4 subset,
        // `variant.message() == variant.message_static().unwrap().to_string()`
        // — the projection method routes the STATIC arms through
        // `message_static()`, and any regression that re-inlines the
        // per-role `.into()` at `message()` (undoing the composition)
        // still passes the per-variant byte pins but fails THIS
        // composition assertion. Sibling posture to a hypothetical
        // `OptionalParamMalformedReason::label_delegates_static_arms_through_label_static`
        // on the peer 3-of-4 static carving of the sibling optional-
        // section-malformed four-arm closed set.
        for (variant, static_bytes) in [
            (
                super::TemplateInvariantKind::EndListEmptyStack,
                super::TemplateInvariantKind::END_LIST_EMPTY_STACK_MESSAGE,
            ),
            (
                super::TemplateInvariantKind::FinalNoValue,
                super::TemplateInvariantKind::FINAL_NO_VALUE_MESSAGE,
            ),
        ] {
            assert_eq!(
                variant.message(),
                static_bytes,
                "message() for {variant:?} must equal its message_static() bytes — routed through the typed subset projection",
            );
        }
        // Dynamic arms retain the format!() behavior — the composition
        // routes them through the fallthrough closure. Pin that the
        // outer `map_or_else` did not accidentally swallow the
        // payload's `usize` bytes.
        assert_eq!(
            super::TemplateInvariantKind::SubstBadIndex(7).message(),
            "compiled template referenced bad param index 7",
        );
        assert_eq!(
            super::TemplateInvariantKind::SpliceBadIndex(11).message(),
            "compiled template referenced bad splice index 11",
        );
    }

    #[test]
    fn template_invariant_kind_dynamic_descriptor_constants_pin_canonical_bytes() {
        // Per-role `pub const &'static str` truth pins on the DYNAMIC
        // 2-of-4 subset carving of the four-arm closed set. Pins the
        // canonical descriptor bytes byte-for-byte so a regression on
        // any per-role const (a typo like `"parms"` for
        // `SUBST_BAD_INDEX_DESCRIPTOR`, a widening drift like
        // `"splice-target"` for `SPLICE_BAD_INDEX_DESCRIPTOR`) fails
        // loudly here rather than silently drifting the rendered
        // diagnostic bytes downstream (through `message()` /
        // `LispError::Display`). Peer to the STATIC 2-of-4 subset's
        // `template_invariant_kind_static_message_constants_pin_canonical_bytes`.
        assert_eq!(
            super::TemplateInvariantKind::SUBST_BAD_INDEX_DESCRIPTOR,
            "param",
        );
        assert_eq!(
            super::TemplateInvariantKind::SPLICE_BAD_INDEX_DESCRIPTOR,
            "splice",
        );
    }

    #[test]
    fn template_invariant_kind_dynamic_descriptors_pin_two_arm_forced_arity_array() {
        // Pin the ARITY + COMPOSITION contract of the DYNAMIC 2-of-4
        // subset ALL array. A regression that grows the array
        // without adding a per-role const + `descriptor_dynamic` arm
        // fails compilation (forced-arity `[&'static str; 2]`); a
        // regression that reorders the array against the projection
        // method's arm order fails
        // `template_invariant_kind_dynamic_descriptors_align_with_descriptor_dynamic_by_index`
        // in lockstep. Cardinality pin here is a fail-loud belt-and-
        // braces peer to the compile-time `[_; 2]` check.
        assert_eq!(
            super::TemplateInvariantKind::DYNAMIC_DESCRIPTORS.len(),
            2,
            "DYNAMIC_DESCRIPTORS must have exactly two entries — the 2-of-4 dynamic subset carving",
        );
        assert_eq!(
            super::TemplateInvariantKind::DYNAMIC_DESCRIPTORS,
            [
                super::TemplateInvariantKind::SUBST_BAD_INDEX_DESCRIPTOR,
                super::TemplateInvariantKind::SPLICE_BAD_INDEX_DESCRIPTOR,
            ],
            "DYNAMIC_DESCRIPTORS must compose from the two per-role descriptor constants in declaration order",
        );
    }

    #[test]
    fn template_invariant_kind_descriptor_dynamic_projects_dynamic_subset_to_typed_option() {
        // Pin `descriptor_dynamic(self) -> Option<&'static str>`'s
        // per-arm truth table: the two DYNAMIC arms project to
        // `Some(descriptor)` routed through the per-role `pub const`s
        // regardless of `usize` payload value; the two STATIC arms
        // project to `None`. Payload invariance on the DYNAMIC arms is
        // load-bearing: a regression that surfaces the payload's
        // `usize` bytes on the descriptor axis (say, by folding the
        // idx into a Format-typed descriptor slot) would silently
        // widen the DYNAMIC descriptor from a per-arm noun to a
        // per-callsite string — this test pins the current per-arm
        // per-noun carving. Sibling posture to
        // `template_invariant_kind_message_static_projects_static_subset_to_typed_option`.
        for idx in [0_usize, 1, 42, 99, usize::MAX] {
            assert_eq!(
                super::TemplateInvariantKind::SubstBadIndex(idx).descriptor_dynamic(),
                Some(super::TemplateInvariantKind::SUBST_BAD_INDEX_DESCRIPTOR),
                "SubstBadIndex({idx}) must project to Some(SUBST_BAD_INDEX_DESCRIPTOR) — descriptor is per-arm, not per-idx",
            );
            assert_eq!(
                super::TemplateInvariantKind::SpliceBadIndex(idx).descriptor_dynamic(),
                Some(super::TemplateInvariantKind::SPLICE_BAD_INDEX_DESCRIPTOR),
                "SpliceBadIndex({idx}) must project to Some(SPLICE_BAD_INDEX_DESCRIPTOR) — descriptor is per-arm, not per-idx",
            );
        }
        // STATIC arms project to None on the descriptor axis — their
        // full bytes bind on the message_static() axis, and they carry
        // no per-role descriptor slot to project.
        assert_eq!(
            super::TemplateInvariantKind::EndListEmptyStack.descriptor_dynamic(),
            None,
        );
        assert_eq!(
            super::TemplateInvariantKind::FinalNoValue.descriptor_dynamic(),
            None,
        );
    }

    #[test]
    fn template_invariant_kind_dynamic_descriptors_align_with_descriptor_dynamic_by_index() {
        // Pin the ALIGNMENT contract:
        // `Self::DYNAMIC_DESCRIPTORS[0] == Self::SubstBadIndex(_).descriptor_dynamic().unwrap()`
        // and
        // `Self::DYNAMIC_DESCRIPTORS[1] == Self::SpliceBadIndex(_).descriptor_dynamic().unwrap()`
        // element-wise. A regression that swaps the array's ordering
        // against the projection method's arm order fails loudly
        // here. Sibling posture to
        // `template_invariant_kind_static_messages_align_with_message_static_by_index`.
        assert_eq!(
            super::TemplateInvariantKind::DYNAMIC_DESCRIPTORS[0],
            super::TemplateInvariantKind::SubstBadIndex(0)
                .descriptor_dynamic()
                .unwrap(),
        );
        assert_eq!(
            super::TemplateInvariantKind::DYNAMIC_DESCRIPTORS[1],
            super::TemplateInvariantKind::SpliceBadIndex(0)
                .descriptor_dynamic()
                .unwrap(),
        );
    }

    #[test]
    fn template_invariant_kind_message_dynamic_projects_dynamic_subset_to_typed_option() {
        // Pin `message_dynamic(self) -> Option<String>`'s per-arm
        // truth table: the two DYNAMIC arms project to
        // `Some(rendered)` composing the shared
        // `"compiled template referenced bad {descriptor} index {idx}"`
        // template with their per-arm descriptor const + payload; the
        // two STATIC arms project to `None`. The DYNAMIC-subset bytes
        // are byte-for-byte equivalent to the pre-lift inline
        // `format!(...)` arms — authoring-tool substring greps see no
        // drift across the lift.
        for idx in [0_usize, 1, 42, 99] {
            assert_eq!(
                super::TemplateInvariantKind::SubstBadIndex(idx).message_dynamic(),
                Some(format!("compiled template referenced bad param index {idx}")),
                "SubstBadIndex({idx}).message_dynamic() must render the shared template with the `param` descriptor and idx payload",
            );
            assert_eq!(
                super::TemplateInvariantKind::SpliceBadIndex(idx).message_dynamic(),
                Some(format!("compiled template referenced bad splice index {idx}")),
                "SpliceBadIndex({idx}).message_dynamic() must render the shared template with the `splice` descriptor and idx payload",
            );
        }
        // STATIC arms project to None on the message_dynamic axis —
        // their full bytes bind on the message_static() axis and carry
        // no `usize` payload to format into the shared template.
        assert_eq!(
            super::TemplateInvariantKind::EndListEmptyStack.message_dynamic(),
            None,
        );
        assert_eq!(
            super::TemplateInvariantKind::FinalNoValue.message_dynamic(),
            None,
        );
    }

    #[test]
    fn template_invariant_kind_static_dynamic_projections_partition_closed_set() {
        // Pin the PARTITION contract: for every legal variant, EXACTLY
        // ONE of `message_static(self)` and `descriptor_dynamic(self)`
        // returns `Some`. Together the two typed subset projections
        // partition the four-arm closed set into its STATIC ⊕ DYNAMIC
        // halves at zero allocation cost. The partition is what makes
        // `message()`'s `.expect(...)` structurally unreachable —
        // rustc's exhaustive-match checks on both projections keep the
        // partition sound; this test pins the runtime witness. A
        // regression that widens EITHER subset (say, a lift that
        // projects `SubstBadIndex` into a per-role STATIC message)
        // fails loudly here because both projections would return
        // `Some` for the same variant.
        for variant in [
            super::TemplateInvariantKind::EndListEmptyStack,
            super::TemplateInvariantKind::FinalNoValue,
            super::TemplateInvariantKind::SubstBadIndex(0),
            super::TemplateInvariantKind::SubstBadIndex(usize::MAX),
            super::TemplateInvariantKind::SpliceBadIndex(0),
            super::TemplateInvariantKind::SpliceBadIndex(usize::MAX),
        ] {
            let static_hit = variant.message_static().is_some();
            let dynamic_hit = variant.descriptor_dynamic().is_some();
            assert!(
                static_hit ^ dynamic_hit,
                "message_static/descriptor_dynamic must partition the closed set — \
                 exactly one projection returns Some for {variant:?}, got static_hit={static_hit} dynamic_hit={dynamic_hit}",
            );
        }
    }

    #[test]
    fn template_invariant_kind_message_delegates_dynamic_arms_through_message_dynamic() {
        // Pin the `message()` composition contract on the DYNAMIC side:
        // for every arm on the DYNAMIC 2-of-4 subset,
        // `variant.message() == variant.message_dynamic().unwrap()`
        // — the projection method routes the DYNAMIC arms through
        // `message_dynamic()` (which itself routes through
        // `descriptor_dynamic()`), and any regression that re-inlines
        // the per-arm `format!(...)` at `message()` (undoing the
        // composition) still passes the per-variant byte pins but
        // fails THIS composition assertion. Peer to
        // `template_invariant_kind_message_delegates_static_arms_through_message_static`.
        for variant in [
            super::TemplateInvariantKind::SubstBadIndex(0),
            super::TemplateInvariantKind::SubstBadIndex(99),
            super::TemplateInvariantKind::SubstBadIndex(usize::MAX),
            super::TemplateInvariantKind::SpliceBadIndex(0),
            super::TemplateInvariantKind::SpliceBadIndex(42),
            super::TemplateInvariantKind::SpliceBadIndex(usize::MAX),
        ] {
            assert_eq!(
                variant.message(),
                variant.message_dynamic().unwrap(),
                "message() for {variant:?} must equal its message_dynamic() bytes — routed through the typed subset projection",
            );
        }
    }

    #[test]
    fn template_invariant_display_renders_legacy_compile_shape_for_subst_bad_idx() {
        // End-to-end through the `LispError` Display impl — pins the
        // rendered diagnostic byte-for-byte: `"compile error in
        // {macro_name}: compiled template referenced bad param index
        // {idx}"`. Authoring tools that substring-grep the rendered
        // diagnostic (`tatara-check`, REPL substring-greps) see no
        // drift across the lift from the pre-lift `Compile { form:
        // macro_name, message: format!(...) }` shape.
        let err = LispError::TemplateInvariant {
            macro_name: "test-macro".into(),
            kind: super::TemplateInvariantKind::SubstBadIndex(99),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in test-macro: compiled template referenced bad param index 99"
        );
    }

    #[test]
    fn template_invariant_display_renders_legacy_compile_shape_for_splice_bad_idx() {
        // Sibling Display test for the Splice gate. Pins the message
        // byte-for-byte: `"compile error in call-macro: compiled
        // template referenced bad splice index 42"`.
        let err = LispError::TemplateInvariant {
            macro_name: "call-macro".into(),
            kind: super::TemplateInvariantKind::SpliceBadIndex(42),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in call-macro: compiled template referenced bad splice index 42"
        );
    }

    #[test]
    fn template_invariant_display_renders_legacy_compile_shape_for_endlist() {
        // Sibling Display test for the EndList gate. Pins the static-
        // message byte-for-byte: `"compile error in wrap: compiled
        // template: EndList with empty stack"`. Even though this gate
        // is currently guarded by `last_mut().unwrap()` and not
        // reachable through any single CompiledTemplate, the structural
        // variant carries the canonical message verbatim — defensive
        // against future changes to the stack discipline.
        let err = LispError::TemplateInvariant {
            macro_name: "wrap".into(),
            kind: super::TemplateInvariantKind::EndListEmptyStack,
        };
        assert_eq!(
            format!("{err}"),
            "compile error in wrap: compiled template: EndList with empty stack"
        );
    }

    #[test]
    fn template_invariant_display_renders_legacy_compile_shape_for_final_no_value() {
        // Sibling Display test for the final-no-value gate. Pins the
        // static-message byte-for-byte: `"compile error in id: compiled
        // template produced no value"`. Closes the structural-
        // completeness floor of the closed-set `TemplateInvariantKind`
        // × Display matrix — all four reachable kinds are pinned.
        let err = LispError::TemplateInvariant {
            macro_name: "id".into(),
            kind: super::TemplateInvariantKind::FinalNoValue,
        };
        assert_eq!(
            format!("{err}"),
            "compile error in id: compiled template produced no value"
        );
    }

    #[test]
    fn template_invariant_display_preserves_legacy_substring_for_message_grep() {
        // Pin the legacy substring set — `"compiled template"`,
        // `"bad param index"`, `"bad splice index"`, `"EndList with
        // empty stack"`, `"produced no value"` — as a separate
        // assertion so a regression that drifts ANY of the four
        // surface words (e.g., to "invalid", "missing", "no result")
        // fails-loudly here. The substrings are what consumers
        // downstream (`tatara-check`, REPL) substring-match on today.
        let subst = LispError::TemplateInvariant {
            macro_name: "m".into(),
            kind: super::TemplateInvariantKind::SubstBadIndex(0),
        };
        let msg = format!("{subst}");
        assert!(
            msg.contains("compiled template"),
            "expected `compiled template` prefix, got: {msg}"
        );
        assert!(
            msg.contains("bad param index"),
            "expected `bad param index` substring, got: {msg}"
        );

        let splice = LispError::TemplateInvariant {
            macro_name: "m".into(),
            kind: super::TemplateInvariantKind::SpliceBadIndex(0),
        };
        let msg = format!("{splice}");
        assert!(
            msg.contains("bad splice index"),
            "expected `bad splice index` substring, got: {msg}"
        );

        let endlist = LispError::TemplateInvariant {
            macro_name: "m".into(),
            kind: super::TemplateInvariantKind::EndListEmptyStack,
        };
        let msg = format!("{endlist}");
        assert!(
            msg.contains("EndList with empty stack"),
            "expected `EndList with empty stack` substring, got: {msg}"
        );

        let final_nv = LispError::TemplateInvariant {
            macro_name: "m".into(),
            kind: super::TemplateInvariantKind::FinalNoValue,
        };
        let msg = format!("{final_nv}");
        assert!(
            msg.contains("produced no value"),
            "expected `produced no value` substring, got: {msg}"
        );
    }

    #[test]
    fn template_invariant_kind_is_copy_and_partial_eq() {
        // Pin the closed-set posture: `TemplateInvariantKind` derives
        // Copy + PartialEq + Eq + Debug so it composes ergonomically
        // in tests and in consumer pattern-matches (no clone-and-own
        // dance). Same posture as `CompilerSpecIoStage` and
        // `MacroDefHead`. A regression that drops Copy fails-loudly
        // here (the let-binding would move out instead of copy).
        let kind = super::TemplateInvariantKind::SubstBadIndex(7);
        let copied = kind;
        assert_eq!(kind, copied);
        assert_eq!(kind, super::TemplateInvariantKind::SubstBadIndex(7));
        assert_ne!(kind, super::TemplateInvariantKind::SubstBadIndex(8));
        assert_ne!(kind, super::TemplateInvariantKind::SpliceBadIndex(7));
        assert_ne!(kind, super::TemplateInvariantKind::EndListEmptyStack);
    }

    #[test]
    fn template_invariant_kind_index_payload_is_structurally_scoped_to_index_carrying_variants() {
        // The closed-set invariant: only `SubstBadIndex` and
        // `SpliceBadIndex` carry a `usize` payload; `EndListEmptyStack`
        // and `FinalNoValue` are bare. This is enforced by the variant
        // shape itself — there is no way to construct
        // `EndListEmptyStack(7)` because the variant has no fields.
        // This test pins the structural shape: the four reachable
        // failure modes split 2+2 into "index-carrying" and "bare".
        // A regression that adds a payload to the bare variants (or
        // strips it from the index-carrying ones) fails to compile,
        // making this test redundant — but the test documents the
        // shape for readers walking the closed set.
        match super::TemplateInvariantKind::SubstBadIndex(5) {
            super::TemplateInvariantKind::SubstBadIndex(idx) => assert_eq!(idx, 5),
            other => panic!("expected SubstBadIndex, got {other:?}"),
        }
        match super::TemplateInvariantKind::EndListEmptyStack {
            super::TemplateInvariantKind::EndListEmptyStack => {}
            other => panic!("expected EndListEmptyStack, got {other:?}"),
        }
    }

    // --- MacroDefHead typed-slot lift (the closed-set promotion) ---
    //
    // The next eight tests pin the typed-slot promotion that closes
    // the three-times rule across the `LispError::Defmacro*` family.
    // Before this lift the three variants' `head` slot was
    // `&'static str`, projected from a `MacroDefHead` via
    // `head.keyword()` at the helper boundary; consumers had to
    // substring-compare against three string literals to recognize
    // a head identity. After the lift the slot IS the typed enum,
    // so authoring tools (REPL, LSP, `tatara-check`) pattern-match
    // on `MacroDefHead::Defmacro` etc. directly — same posture as
    // `CompilerSpecIoStage` for `LispError::CompilerSpecIo` and
    // `TemplateInvariantKind` for `LispError::TemplateInvariant`.

    #[test]
    fn defmacro_arity_head_slot_is_macro_def_head_not_static_str() {
        // Pin that the `head` slot of `LispError::DefmacroArity` is
        // `MacroDefHead` (the typed closed-set enum), not `&'static
        // str`. A regression that reverts the slot to `&'static str`
        // breaks the typed binding here at compile time; a
        // construction with a stringly-typed head would fail to
        // construct. This test is the structural-completeness pin
        // for the typed-slot promotion, parallel to how
        // `compiler_spec_io_carries_typed_stage_field` (if it
        // existed) would pin `LispError::CompilerSpecIo.stage`.
        let err = LispError::DefmacroArity {
            head: MacroDefHead::Defmacro,
            arity: 1,
        };
        match err {
            LispError::DefmacroArity { head, arity } => {
                assert_eq!(head, MacroDefHead::Defmacro);
                assert_eq!(arity, 1);
            }
            other => panic!("expected DefmacroArity, got {other:?}"),
        }
    }

    #[test]
    fn defmacro_non_symbol_name_head_slot_is_macro_def_head_not_static_str() {
        // Sibling pin of `defmacro_arity_head_slot_is_macro_def_head_not_static_str`
        // for the `LispError::DefmacroNonSymbolName` variant. The
        // `head` slot carries `MacroDefHead` directly so consumers
        // bind on variant identity (`MacroDefHead::DefpointTemplate`)
        // instead of substring-matching the rendered diagnostic.
        let err = LispError::DefmacroNonSymbolName {
            head: MacroDefHead::DefpointTemplate,
            got: SexpWitness::new(SexpShape::Int, "5"),
        };
        match err {
            LispError::DefmacroNonSymbolName { head, got } => {
                assert_eq!(head, MacroDefHead::DefpointTemplate);
                assert_eq!(got.shape, SexpShape::Int);
                assert_eq!(got.display, "5");
            }
            other => panic!("expected DefmacroNonSymbolName, got {other:?}"),
        }
    }

    #[test]
    fn defmacro_non_list_params_head_slot_is_macro_def_head_not_static_str() {
        // Sibling pin of `defmacro_arity_head_slot_is_macro_def_head_not_static_str`
        // for the `LispError::DefmacroNonListParams` variant. The
        // `head` slot carries `MacroDefHead` directly so consumers
        // pattern-match on `MacroDefHead::Defcheck` etc. for the
        // workspace-coherence authoring surface's third head
        // keyword.
        let err = LispError::DefmacroNonListParams {
            head: MacroDefHead::Defcheck,
            got: SexpWitness::new(SexpShape::Int, "7"),
        };
        match err {
            LispError::DefmacroNonListParams { head, got } => {
                assert_eq!(head, MacroDefHead::Defcheck);
                assert_eq!(got.shape, SexpShape::Int);
                assert_eq!(got.display, "7");
            }
            other => panic!("expected DefmacroNonListParams, got {other:?}"),
        }
    }

    #[test]
    fn macro_def_head_display_renders_canonical_keyword_for_each_variant() {
        // Pin `MacroDefHead`'s Display impl — it must project through
        // `keyword()` so the `#[error(...)]` annotation on each
        // `LispError::Defmacro*` variant renders the canonical
        // `&'static str` literal byte-for-byte. The Display
        // bidirection is `MacroDefHead → &'static str`; the inverse
        // (`&str → Option<MacroDefHead>`) lives in `from_keyword`.
        // Together the two close the bidirectional projection on the
        // closed set.
        assert_eq!(format!("{}", MacroDefHead::Defmacro), "defmacro");
        assert_eq!(
            format!("{}", MacroDefHead::DefpointTemplate),
            "defpoint-template"
        );
        assert_eq!(format!("{}", MacroDefHead::Defcheck), "defcheck");
    }

    // ── `MacroDefHead::{DEFMACRO_KEYWORD, DEFPOINT_TEMPLATE_KEYWORD,
    // DEFCHECK_KEYWORD, KEYWORDS}` — the typed per-role head-keyword
    // algebra ─────────────────────────────────────────────────────
    //
    // Sibling posture to
    // `crate::macro_expand::MacroParams::{REST_MARKER,
    // OPTIONAL_MARKER, LAMBDA_LIST_KEYWORDS}` — the per-role canonical
    // `&'static str` marker + closed-set `[&'static str; N]` array
    // pattern applied to the `MacroDefHead` closed set. Pre-lift the
    // three canonical keyword literals lived at TWO structural sites
    // — the `Self::keyword` match arm AND
    // `macro_def_head_display_renders_canonical_keyword_for_each_variant`'s
    // per-variant `assert_eq!` truth-table — plus at consumer
    // test-site literals in `crate::ast` / `crate::compile`. Post-lift
    // each (variant, canonical `&'static str`) pairing binds at ONE
    // `pub const` on the typed [`MacroDefHead`] algebra the
    // [`Self::keyword`] arm routes through.

    #[test]
    fn macro_def_head_defmacro_keyword_projects_canonical_defmacro_bytes() {
        // Pins the exact `"defmacro"` bytes at the typed constant.
        // A regression that drifts the constant (e.g. typo
        // `"def-macro"` with a hyphen, `"defMacro"` in camelCase, or
        // an accidental trailing whitespace) fails-loudly here.
        // This is the single site the substrate's canonical-Lisp
        // macro-definition head keyword resolves to; every downstream
        // consumer (Display, FromStr, tests, LSP completion, metric
        // labels) routes through this constant.
        assert_eq!(
            MacroDefHead::DEFMACRO_KEYWORD,
            "defmacro",
            "MacroDefHead::DEFMACRO_KEYWORD drifted from the substrate- \
             canonical CL-style macro-definition head keyword `\"defmacro\"`"
        );
    }

    #[test]
    fn macro_def_head_defpoint_template_keyword_projects_canonical_defpoint_template_bytes() {
        // Pins the exact `"defpoint-template"` bytes at the typed
        // constant. The hyphen (NOT an underscore, NOT a camel-case
        // capital) is load-bearing: it matches the caixa Aplicacao
        // authoring surface's convention where multi-word Lisp-style
        // identifiers use kebab-case rather than snake_case.
        assert_eq!(
            MacroDefHead::DEFPOINT_TEMPLATE_KEYWORD,
            "defpoint-template",
            "MacroDefHead::DEFPOINT_TEMPLATE_KEYWORD drifted from the substrate- \
             canonical K8s-as-processes authoring-surface head keyword \
             `\"defpoint-template\"`"
        );
    }

    #[test]
    fn macro_def_head_defcheck_keyword_projects_canonical_defcheck_bytes() {
        // Pins the exact `"defcheck"` bytes at the typed constant.
        // The `tatara-reconciler/checks.lisp` workspace-coherence
        // driver reads this exact keyword to classify `(defcheck …)`
        // forms; any drift here silently breaks the check runner.
        assert_eq!(
            MacroDefHead::DEFCHECK_KEYWORD,
            "defcheck",
            "MacroDefHead::DEFCHECK_KEYWORD drifted from the substrate- \
             canonical workspace-coherence authoring-surface head keyword \
             `\"defcheck\"`"
        );
    }

    #[test]
    fn macro_def_head_keyword_method_routes_through_typed_constants() {
        // PATH-UNIFORMITY: the inherent `Self::keyword(self)` method
        // MUST return the per-role `pub const` byte-for-byte for each
        // reachable variant. A regression that reverts ONE arm to an
        // inline `"defmacro"` string literal (e.g. a merge-conflict
        // resolution that picked the pre-lift form) silently
        // reintroduces the ≥2 PRIME-DIRECTIVE trigger the lift
        // resolved — this test catches that by pinning the arm's
        // return value to the constant, so the two paths (inline vs.
        // typed constant) cannot both hold.
        assert_eq!(
            MacroDefHead::Defmacro.keyword(),
            MacroDefHead::DEFMACRO_KEYWORD,
            "MacroDefHead::Defmacro.keyword() drifted from \
             MacroDefHead::DEFMACRO_KEYWORD — the match arm reverted to \
             an inline literal"
        );
        assert_eq!(
            MacroDefHead::DefpointTemplate.keyword(),
            MacroDefHead::DEFPOINT_TEMPLATE_KEYWORD,
            "MacroDefHead::DefpointTemplate.keyword() drifted from \
             MacroDefHead::DEFPOINT_TEMPLATE_KEYWORD — the match arm \
             reverted to an inline literal"
        );
        assert_eq!(
            MacroDefHead::Defcheck.keyword(),
            MacroDefHead::DEFCHECK_KEYWORD,
            "MacroDefHead::Defcheck.keyword() drifted from \
             MacroDefHead::DEFCHECK_KEYWORD — the match arm reverted to \
             an inline literal"
        );
    }

    #[test]
    fn macro_def_head_keywords_has_expected_cardinality() {
        // Cardinality contract: `Self::KEYWORDS.len() == 3` — pinned
        // at the declaration site by rustc's forced-arity check on
        // `[&'static str; 3]`. This test surfaces the arity as a
        // fail-loud runtime pin so a future refactor that switches
        // the array type to `&[&'static str]` (dropping the compile-
        // time arity forcing) doesn't silently loosen the closed-set
        // discipline the family relies on. Sibling posture to
        // `macro_params_lambda_list_keywords_has_expected_cardinality`
        // on the `MacroParams::LAMBDA_LIST_KEYWORDS` family.
        assert_eq!(
            MacroDefHead::KEYWORDS.len(),
            3,
            "MacroDefHead::KEYWORDS cardinality drifted from 3 — the \
             head-keyword closed set gained or lost a variant without \
             the ALL / KEYWORDS pair being updated in tandem"
        );
    }

    #[test]
    fn macro_def_head_keywords_align_with_all_by_index() {
        // ALIGNMENT CONTRACT: `Self::KEYWORDS[i] ==
        // Self::ALL[i].keyword()` element-wise. The two ALL arrays
        // (typed variants, canonical `&'static str` keywords) share
        // ONE canonical declaration order — a regression that
        // reorders ONE array without reordering the other silently
        // misaligns every `zip(Self::ALL, Self::KEYWORDS)` consumer
        // (LSP completion providers, metric-label emitters, coverage
        // reporters). Pinning by-index alignment here catches the
        // reorder at test time.
        assert_eq!(
            MacroDefHead::KEYWORDS.len(),
            MacroDefHead::ALL.len(),
            "MacroDefHead::KEYWORDS and MacroDefHead::ALL diverged in \
             cardinality — the per-role constants and enum variants must \
             stay in lockstep"
        );
        for (i, head) in MacroDefHead::ALL.iter().enumerate() {
            assert_eq!(
                MacroDefHead::KEYWORDS[i],
                head.keyword(),
                "MacroDefHead::KEYWORDS[{i}] `{kw}` drifted from \
                 MacroDefHead::ALL[{i}].keyword() `{via_variant}` — the \
                 canonical declaration order of the two ALL arrays must \
                 match element-wise",
                kw = MacroDefHead::KEYWORDS[i],
                via_variant = head.keyword(),
            );
        }
    }

    #[test]
    fn macro_def_head_keywords_pairwise_distinct() {
        // PAIRWISE DISJOINTNESS: the three `&'static str` keywords on
        // the head-keyword algebra MUST differ so the derive-generated
        // FromStr's linear sweep cannot route two variants through
        // the same arm. Family-wide sweep over KEYWORDS × KEYWORDS —
        // supersedes any single per-pair assertion and picks up new
        // variants mechanically when the array grows. Sibling posture
        // to `macro_params_lambda_list_keywords_pairwise_distinct` on
        // the CL lambda-list-keyword family.
        for (i, a) in MacroDefHead::KEYWORDS.iter().enumerate() {
            for (j, b) in MacroDefHead::KEYWORDS.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "MacroDefHead::KEYWORDS[{i}] `{a}` collides with \
                     MacroDefHead::KEYWORDS[{j}] `{b}` — the derive- \
                     generated FromStr sweep would route two variants \
                     through the same arm"
                );
            }
        }
    }

    #[test]
    fn macro_def_head_keywords_all_round_trip_through_from_str() {
        // Family-wide bidirection: every entry of `Self::KEYWORDS`
        // MUST parse back to some `MacroDefHead` variant AND that
        // variant's `keyword()` MUST equal the original entry.
        // Sibling posture to `macro_def_head_keyword_round_trips_through_from_str`
        // (which sweeps over `Self::ALL`); this test sweeps over the
        // per-role `&'static str` constants directly, catching a
        // regression where one of the three constants drifts from
        // the corresponding `Self::keyword` arm (e.g. `DEFCHECK_KEYWORD`
        // set to `"defvalidation"` while `Self::Defcheck.keyword()`
        // still returns `Self::DEFCHECK_KEYWORD`, which would parse
        // to `MacroDefHead::Defcheck` correctly but break every
        // downstream consumer that pinned the literal `"defcheck"`
        // bytes).
        for kw in MacroDefHead::KEYWORDS {
            let parsed: MacroDefHead = kw.parse().unwrap_or_else(|_| {
                panic!(
                    "MacroDefHead::KEYWORDS entry `{kw}` failed to parse — \
                     the entry drifted from Self::keyword"
                )
            });
            assert_eq!(
                parsed.keyword(),
                kw,
                "MacroDefHead::KEYWORDS entry `{kw}` parses to a variant \
                 whose keyword() `{}` does not match — the constant and \
                 the match arm drifted apart",
                parsed.keyword(),
            );
        }
    }

    #[test]
    fn defmacro_arity_display_renders_legacy_prefix_via_macro_def_head_display() {
        // End-to-end through `LispError`'s Display: the typed `head:
        // MacroDefHead` slot projects to the canonical `&'static
        // str` literal at render time via `MacroDefHead`'s Display
        // impl, so the rendered diagnostic is byte-for-byte
        // identical to the pre-lift `head: &'static str` shape.
        // Authoring tools that substring-match on `"compile error
        // in defmacro:"` see no drift across the typed-slot
        // promotion.
        let err = LispError::DefmacroArity {
            head: MacroDefHead::Defmacro,
            arity: 2,
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defmacro: (defmacro name (params) body) required \
             (got 2 elements, need 4)"
        );
    }

    #[test]
    fn defmacro_non_symbol_name_display_renders_via_macro_def_head_display_for_defpoint_template() {
        // Sibling end-to-end test for the `defpoint-template` head:
        // pins that the typed-slot promotion preserves the
        // K8s-as-processes authoring surface's diagnostic shape
        // byte-for-byte. A regression that drifts `MacroDefHead`'s
        // Display impl (e.g. returns `"DefpointTemplate"` instead of
        // `"defpoint-template"`) fails-loudly here.
        let err = LispError::DefmacroNonSymbolName {
            head: MacroDefHead::DefpointTemplate,
            got: SexpWitness::new(SexpShape::Keyword, ":foo"),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defpoint-template: expected name symbol, got :foo"
        );
    }

    #[test]
    fn defmacro_non_list_params_display_renders_via_macro_def_head_display_for_defcheck() {
        // Sibling end-to-end test for the `defcheck` head: pins that
        // the typed-slot promotion preserves the workspace-coherence
        // authoring surface's diagnostic shape byte-for-byte.
        let err = LispError::DefmacroNonListParams {
            head: MacroDefHead::Defcheck,
            got: SexpWitness::new(SexpShape::Symbol, "x"),
        };
        assert_eq!(
            format!("{err}"),
            "compile error in defcheck: expected param list, got x"
        );
    }

    #[test]
    fn macro_def_head_is_copy_and_partial_eq_for_pattern_match_ergonomics() {
        // Pin that `MacroDefHead` derives `Copy + PartialEq + Eq +
        // Debug + Clone` — the posture every closed-set typed enum
        // in this module shares (`CompilerSpecIoStage`,
        // `TemplateInvariantKind`). Copy lets consumers pattern-match
        // on the variant without explicit cloning; `PartialEq + Eq`
        // makes `assert_eq!` and `matches!` ergonomic; `Debug` makes
        // the `other => panic!("got {other:?}")` shape ergonomic at
        // assertion sites. A regression that drops any of these
        // derives breaks compilation here.
        let h = MacroDefHead::Defmacro;
        let h_copy: MacroDefHead = h; // Copy
        assert_eq!(h, h_copy); // PartialEq
        assert!(matches!(h, MacroDefHead::Defmacro)); // exhaustive match
        let _: String = format!("{h:?}"); // Debug
    }

    // --- UnquoteForm typed-slot lift (the closed-set promotion) ---
    //
    // The next six tests pin the typed-slot promotion that closes the
    // three-times rule across `LispError::UnboundTemplateVar` /
    // `LispError::NonSymbolUnquoteTarget` — the two template-marker
    // rejection variants for the no-evaluator template language.
    // Before this lift each variant's `prefix` slot was `&'static
    // str`, set from the literal `","` / `",@"` at four (Unbound) +
    // four (NonSymbol) call sites; consumers had to substring-compare
    // against two string literals to recognize the marker identity.
    // After the lift the slot IS the typed `UnquoteForm` enum, so
    // authoring tools (REPL, LSP, `tatara-check`) pattern-match on
    // `UnquoteForm::Splice` etc. directly — same posture as
    // `MacroDefHead` for `LispError::Defmacro*`, `CompilerSpecIoStage`
    // for `LispError::CompilerSpecIo`, `TemplateInvariantKind` for
    // `LispError::TemplateInvariant`.

    #[test]
    fn unbound_template_var_prefix_slot_is_unquote_form_not_static_str() {
        // Pin that the `prefix` slot of `LispError::UnboundTemplateVar`
        // is `UnquoteForm` (the typed closed-set enum), not `&'static
        // str`. A regression that reverts the slot to `&'static str`
        // breaks the typed binding here at compile time; a
        // construction with a stringly-typed prefix would fail to
        // construct. This test is the structural-completeness pin
        // for the typed-slot promotion, parallel to how
        // `defmacro_arity_head_slot_is_macro_def_head_not_static_str`
        // pins `LispError::DefmacroArity.head`.
        let err = LispError::UnboundTemplateVar {
            prefix: UnquoteForm::Unquote,
            name: "xs".into(),
            hint: None,
        };
        match err {
            LispError::UnboundTemplateVar { prefix, name, hint } => {
                assert_eq!(prefix, UnquoteForm::Unquote);
                assert_eq!(name, "xs");
                assert_eq!(hint, None);
            }
            other => panic!("expected UnboundTemplateVar, got {other:?}"),
        }
    }

    #[test]
    fn non_symbol_unquote_target_prefix_slot_is_unquote_form_not_static_str() {
        // Sibling pin for `LispError::NonSymbolUnquoteTarget`. The
        // `prefix` slot carries `UnquoteForm` directly so consumers
        // bind on variant identity (`UnquoteForm::Splice`) instead
        // of substring-matching the rendered diagnostic. Together
        // with `unbound_template_var_prefix_slot_is_unquote_form_not_static_str`,
        // the two pin the typed-slot promotion across ALL template-
        // marker rejection variants — the two reachable rejection
        // identities (`UnboundTemplateVar`, `NonSymbolUnquoteTarget`)
        // share ONE typed marker identity.
        let err = LispError::NonSymbolUnquoteTarget {
            prefix: UnquoteForm::Splice,
            got: SexpWitness::new(SexpShape::List, "(list 1 2)"),
        };
        match err {
            LispError::NonSymbolUnquoteTarget { prefix, got } => {
                assert_eq!(prefix, UnquoteForm::Splice);
                assert_eq!(got.shape, SexpShape::List);
                assert_eq!(got.display, "(list 1 2)");
            }
            other => panic!("expected NonSymbolUnquoteTarget, got {other:?}"),
        }
    }

    #[test]
    fn unquote_form_marker_projects_canonical_literal_for_each_variant() {
        // Pin `UnquoteForm::marker()` — it must project each variant
        // to the canonical `&'static str` literal byte-for-byte. The
        // projection feeds the `#[error(...)]` annotation on
        // `LispError::UnboundTemplateVar` /
        // `LispError::NonSymbolUnquoteTarget` via the Display impl,
        // and the `unbound_hint_suffix` helper's `prefix.marker()`
        // call site. A regression that drifts the literal (e.g.,
        // returns `"un"` instead of `","`) fails-loudly here.
        assert_eq!(UnquoteForm::Unquote.marker(), ",");
        assert_eq!(UnquoteForm::Splice.marker(), ",@");
    }

    #[test]
    fn unquote_form_display_renders_canonical_marker_for_each_variant() {
        // Pin `UnquoteForm`'s Display impl — it must project through
        // `marker()` so the `#[error(...)]` annotation on each
        // affected `LispError::*` variant renders the canonical
        // `&'static str` literal byte-for-byte. Same posture as
        // `MacroDefHead`'s Display impl (which projects through
        // `keyword()`).
        assert_eq!(format!("{}", UnquoteForm::Unquote), ",");
        assert_eq!(format!("{}", UnquoteForm::Splice), ",@");
    }

    #[test]
    fn unbound_template_var_display_renders_canonical_marker_for_each_variant() {
        // End-to-end through `LispError`'s Display: the typed `prefix:
        // UnquoteForm` slot projects to the canonical `&'static str`
        // literal at render time via `UnquoteForm`'s Display impl,
        // so the rendered diagnostic is byte-for-byte identical to
        // the pre-lift `prefix: &'static str` shape. Authoring tools
        // that substring-match on `,xs` / `,@xs` see no drift across
        // the typed-slot promotion. Paired with
        // `non_symbol_unquote_target_display_renders_canonical_marker_for_each_variant`
        // to pin the lift end-to-end on BOTH affected variants.
        let unquote = LispError::UnboundTemplateVar {
            prefix: UnquoteForm::Unquote,
            name: "xs".into(),
            hint: None,
        };
        assert_eq!(format!("{unquote}"), "compile error in ,xs: unbound");

        let splice = LispError::UnboundTemplateVar {
            prefix: UnquoteForm::Splice,
            name: "argz".into(),
            hint: Some("args".into()),
        };
        assert_eq!(
            format!("{splice}"),
            "compile error in ,@argz: unbound; did you mean ,@args?"
        );
    }

    #[test]
    fn non_symbol_unquote_target_display_renders_canonical_marker_for_each_variant() {
        // Sibling end-to-end pin for `LispError::NonSymbolUnquoteTarget`.
        // Pins that the typed-slot promotion preserves the
        // template-marker diagnostic shape byte-for-byte for BOTH
        // variants of `UnquoteForm`.
        let unquote = LispError::NonSymbolUnquoteTarget {
            prefix: UnquoteForm::Unquote,
            got: SexpWitness::new(SexpShape::List, "(list 1 2)"),
        };
        assert_eq!(
            format!("{unquote}"),
            "compile error in ,: expected symbol, got (list 1 2)"
        );

        let splice = LispError::NonSymbolUnquoteTarget {
            prefix: UnquoteForm::Splice,
            got: SexpWitness::new(SexpShape::Int, "5"),
        };
        assert_eq!(
            format!("{splice}"),
            "compile error in ,@: expected symbol, got 5"
        );
    }

    #[test]
    fn unquote_form_is_copy_and_partial_eq_for_pattern_match_ergonomics() {
        // Pin that `UnquoteForm` derives `Copy + PartialEq + Eq +
        // Debug + Clone` — the posture every closed-set typed enum
        // in this module shares (`MacroDefHead`, `CompilerSpecIoStage`,
        // `TemplateInvariantKind`). Copy lets consumers pattern-match
        // on the variant without explicit cloning; `PartialEq + Eq`
        // makes `assert_eq!` and `matches!` ergonomic; `Debug` makes
        // the `other => panic!("got {other:?}")` shape ergonomic at
        // assertion sites. A regression that drops any of these
        // derives breaks compilation here.
        let f = UnquoteForm::Splice;
        let f_copy: UnquoteForm = f; // Copy
        assert_eq!(f, f_copy); // PartialEq
        assert!(matches!(f, UnquoteForm::Splice)); // exhaustive match
        assert_ne!(f, UnquoteForm::Unquote); // Eq/Ne
        let _: String = format!("{f:?}"); // Debug
    }

    #[test]
    fn kwarg_path_named_display_renders_legacy_colon_key_literal() {
        // `KwargPath::Named(":<key>")` Display must render the literal
        // `:<key>` byte-for-byte equivalent to the pre-lift
        // `format!(":{key}")` inline literal in `kwarg_form`. The
        // canonical literal lives in ONE place (the Display impl), so
        // a regression that drifts the prefix (e.g., to `key:` or
        // `<key>:`) fails-loudly here AND breaks every
        // `LispError::TypeMismatch.form` consumer that depends on the
        // `:<key>` shape (the substrate's hot path).
        assert_eq!(format!("{}", KwargPath::named("threshold")), ":threshold");
    }

    #[test]
    fn kwarg_path_item_display_renders_legacy_colon_key_bracket_idx_literal() {
        // `KwargPath::Item { key, idx }` Display must render
        // `:<key>[<idx>]` byte-for-byte equivalent to the pre-lift
        // `format!(":{key}[{idx}]")` inline literal in `kwarg_item_form`.
        // The bracketed-index suffix is what `extract_string_list`'s
        // per-item failure path emits; a regression that drifts the
        // bracket-shape (e.g., to `:steps.1` or `:steps#1`) breaks every
        // LSP underline that depends on the bracket shape.
        assert_eq!(format!("{}", KwargPath::item("steps", 1)), ":steps[1]");
    }

    #[test]
    fn kwarg_path_slot_display_renders_legacy_kwargs_bracket_idx_literal() {
        // `KwargPath::Slot(idx)` Display must render `kwargs[<idx>]`
        // byte-for-byte equivalent to the pre-lift
        // `format!("kwargs[{idx}]")` inline literal in `kwargs_pos_form`.
        // The `kwargs` prefix (no leading colon) is what `parse_kwargs`'s
        // "this-position-must-be-a-keyword" gate emits when the slot
        // failed BEFORE a key was known; the slot shape is structurally
        // distinct from the named-kwarg shape (`:<key>` vs `kwargs[i]`)
        // so consumers can bifurcate on path identity.
        assert_eq!(format!("{}", KwargPath::Slot(0)), "kwargs[0]");
    }

    #[test]
    fn kwarg_path_named_carries_kebab_case_keys_unchanged() {
        // Kebab-cased kwarg names (`:notify-ref`, `:window-seconds`)
        // round-trip through the Display unchanged — the path shape
        // doesn't transform the key, it just wraps it in the `:<…>`
        // prefix. Pinning this contract means a regression that
        // camelCases or lowercases the key in the rendered prefix
        // fails-loudly here.
        assert_eq!(format!("{}", KwargPath::named("notify-ref")), ":notify-ref");
        assert_eq!(
            format!("{}", KwargPath::item("window-seconds", 3)),
            ":window-seconds[3]"
        );
    }

    #[test]
    fn kwarg_path_is_clone_and_partial_eq_for_pattern_match_ergonomics() {
        // `KwargPath` derives Clone + Debug + PartialEq + Eq so that
        // pattern-matching call sites (REPL diagnostic capture,
        // `tatara-check`'s failure clustering, an LSP that surfaces
        // "your `:steps[3]` failed" with structural binding) compare
        // by reference cheaply AND inhabit the same kind of test
        // assertion shape as `MacroDefHead`, `UnquoteForm`,
        // `CompilerSpecIoStage`, and `TemplateInvariantKind`. `Copy`
        // is intentionally NOT derived because `String` is not `Copy`
        // — the owned key payload is the load-bearing property of the
        // typed-slot promotion onto `LispError::TypeMismatch.form`. A
        // regression that drops any of the retained derives or that
        // re-adds `Copy` breaks compilation here.
        let p = KwargPath::item("steps", 2);
        let p_clone = p.clone(); // Clone
        assert_eq!(p, p_clone); // PartialEq
        assert!(matches!(p, KwargPath::Item { idx: 2, .. })); // exhaustive match
        assert_ne!(p, KwargPath::Slot(2)); // Eq/Ne — Item and Slot are distinct path identities
        let _: String = format!("{p:?}"); // Debug
    }

    #[test]
    fn kwarg_path_named_and_slot_have_distinct_display_shapes() {
        // The bifurcation between named-kwarg failures (`:<key>`) and
        // pre-key slot failures (`kwargs[<idx>]`) is structural — same
        // failure surface (kwargs gate), different path identity. Pin
        // the structural-distinctness: even at the rendered-string
        // level the two shapes don't collide. Two consumers depend on
        // this:
        //   1. `tatara-check`'s diagnostic capture, which groups by
        //      path prefix — a slot failure must NOT be confused with
        //      a `:kwargs`-keyed named-kwarg failure.
        //   2. An LSP's structural binding — the `KwargPath::Slot`
        //      identity says "we don't know which kwarg yet"; the
        //      `KwargPath::Named` identity says "we know the kwarg
        //      identifier and it's this".
        let named = format!("{}", KwargPath::named("kwargs"));
        let slot = format!("{}", KwargPath::Slot(0));
        assert_eq!(named, ":kwargs");
        assert_eq!(slot, "kwargs[0]");
        assert_ne!(named, slot);
    }

    #[test]
    fn type_mismatch_form_carries_typed_kwarg_path_named_through_variant_slot() {
        // After the typed-slot promotion, `LispError::TypeMismatch.form`
        // is `KwargPath` — owned, structurally bound to the closed-set
        // typed enum. Consumers (REPL, LSP, `tatara-check`) pattern-match
        // on the variant identity `KwargPath::Named(_)` directly rather
        // than substring-matching a rendered prefix. Pin the structural
        // binding AND the Display projection so the byte-for-byte
        // rendering contract is anchored from both angles. A regression
        // that re-introduces a String-shaped form (collapsing the typed
        // enum back into a free-form label) fails-loudly here.
        let err = LispError::TypeMismatch {
            form: KwargPath::named("threshold"),
            expected: ExpectedKwargShape::Number,
            got: SexpShape::String,
        };
        match &err {
            LispError::TypeMismatch { form, .. } => {
                assert_eq!(*form, KwargPath::Named("threshold".into()));
            }
            other => panic!("expected TypeMismatch, got {other:?}"),
        }
        assert_eq!(
            format!("{err}"),
            "compile error in :threshold: expected number, got string"
        );
    }

    #[test]
    fn type_mismatch_form_carries_typed_kwarg_path_item_through_variant_slot() {
        // Sibling pin to `…_named_…` for the per-item path. The
        // `KwargPath::Item { key, idx }` shape names the offending kwarg
        // AND the failing item index in one structural variant; the
        // bracketed `:<key>[<idx>]` rendering is unchanged.
        let err = LispError::TypeMismatch {
            form: KwargPath::item("steps", 3),
            expected: ExpectedKwargShape::String,
            got: SexpShape::Int,
        };
        match &err {
            LispError::TypeMismatch { form, .. } => {
                assert_eq!(
                    *form,
                    KwargPath::Item {
                        key: "steps".into(),
                        idx: 3
                    }
                );
            }
            other => panic!("expected TypeMismatch, got {other:?}"),
        }
        assert_eq!(
            format!("{err}"),
            "compile error in :steps[3]: expected string, got int"
        );
    }

    #[test]
    fn type_mismatch_form_carries_typed_kwarg_path_slot_through_variant_slot() {
        // Sibling pin to `…_named_…` for the pre-key slot path. The
        // `KwargPath::Slot(idx)` shape names the offending position
        // without binding a key — it's the
        // "this-position-must-be-a-keyword" gate firing before any
        // identifier is known. The rendered `kwargs[<idx>]` shape
        // (no leading colon) bifurcates structurally from
        // `KwargPath::Named`'s `:<key>` shape.
        let err = LispError::TypeMismatch {
            form: KwargPath::Slot(2),
            expected: ExpectedKwargShape::Keyword,
            got: SexpShape::String,
        };
        match &err {
            LispError::TypeMismatch { form, .. } => {
                assert_eq!(*form, KwargPath::Slot(2));
            }
            other => panic!("expected TypeMismatch, got {other:?}"),
        }
        assert_eq!(
            format!("{err}"),
            "compile error in kwargs[2]: expected keyword, got string"
        );
    }

    // ── KwargPathKind closed-set lift ───────────────────────────────────
    //
    // Sibling discriminator view of `KwargPath` — the payload-stripped
    // closed set of path-shape CATEGORIES (`Named` / `Item` / `Slot`).
    // Same shape every sibling payload-carrying closed-set enum in the
    // workspace pairs with (`AutoTerminate` / `AutoTerminateKind`,
    // `TerminateReason` / `TerminateReasonKind`, `SelectStrategy` /
    // `SelectStrategyKind`, `ChannelVariant` / `ChannelKind`). Consumers
    // that bucket type-mismatch failures by path-shape category (metrics
    // labels `path_kind=named` etc., a future tatara-check failure
    // histogram, an LSP that switches UI before drilling into the
    // bracket suffix) project through `KwargPath::kind` instead of
    // pattern-matching the full payload and discarding it at every site.

    #[test]
    fn kwarg_path_kind_all_is_unique_and_complete() {
        // Closed-set posture: `ALL` enumerates every reachable variant
        // EXACTLY ONCE — no duplicates, no omissions. The `[Self; 3]`
        // array literal in the declaration forces the arity at compile
        // time; this test catches the orthogonal failure modes — a
        // future variant added at the type without being added to ALL
        // (silently dropped from every consumer's sweep), or a typo
        // that duplicates an entry (silently double-counted). Same
        // truth-table pinning every sibling closed-set lift in the
        // workspace uses (ExpectedKwargShape::ALL, SexpShape::ALL,
        // MacroDefHead::ALL, CompilerSpecIoStage::ALL,
        // AutoTerminateKind::ALL, SelectStrategyKind::ALL, …).
        //
        // The `iter+map+collect+sort_unstable` quadruple this test
        // inlined pre-lift now binds at `<KwargPathKind as
        // ClosedSet>::sorted_labels()` — the canonical-ordered
        // candidate-list projection on the trait. Distinctness of the
        // sorted result is covered by
        // `assert_closed_set_well_formed::<KwargPathKind>()`.
        assert_eq!(KwargPathKind::ALL.len(), 3);
        assert_eq!(
            <KwargPathKind as tatara_closed_set::ClosedSet>::sorted_labels(),
            vec!["item", "named", "slot"],
            "KwargPathKind::ALL must cover every reachable path-shape category"
        );
    }

    #[test]
    fn kwarg_path_kind_label_round_trips_through_from_str() {
        // Bidirectional `label` ↔ `FromStr` contract: for every variant
        // in ALL, `kind.label().parse() == Ok(kind)`. A regression that
        // drifts the (variant, literal) pairing at ONE arm of `label`
        // (typo, capitalization drift) OR at the `FromStr` decode body
        // (off-by-one, missing variant in the sweep) fails-loudly here.
        // The canonical-literal site is singular (`label`) so the
        // round-trip is the only way the typed surface and the rendered
        // category literal can drift apart — pinning it here means they
        // cannot. Mirror of `expected_kwarg_shape_label_round_trips_…`
        // and every sibling closed-set round-trip in the workspace.
        for kind in KwargPathKind::ALL {
            let parsed: KwargPathKind = kind
                .label()
                .parse()
                .expect("every ALL variant's label must round-trip through FromStr");
            assert_eq!(
                parsed,
                kind,
                "FromStr({}) must round-trip to the same variant",
                kind.label()
            );
        }
    }

    #[test]
    fn kwarg_path_kind_display_matches_label_for_every_variant() {
        // Display delegates to `label` — pin the byte-for-byte equality
        // for every variant so a future Display impl that diverges from
        // the canonical projection (e.g., re-adds a prefix like
        // `"kind=named"`) fails-loudly here. Same posture as
        // `expected_kwarg_shape_display_matches_label_for_every_variant`.
        for kind in KwargPathKind::ALL {
            assert_eq!(format!("{kind}"), kind.label());
        }
    }

    #[test]
    fn unknown_kwarg_path_kind_carries_offending_input_verbatim() {
        // Operator-facing diagnostic contract: the offending input lands
        // in the typed error verbatim — no normalization, no case-folding,
        // no truncation. Pin the exact `#[error(...)]` rendering AND the
        // typed `.0` field projection so a future refactor that
        // normalizes (e.g. `.to_lowercase()`) before building the error
        // or that drops the input fails-loudly here. Symmetric to every
        // sibling `Unknown*` carrier in the workspace.
        let err: UnknownKwargPathKind = "Named".parse::<KwargPathKind>().expect_err(
            "capitalized `Named` must NOT decode — labels are byte-equal case-sensitive",
        );
        assert_eq!(err.0, "Named");
        assert_eq!(format!("{err}"), "unknown kwarg path kind: Named");

        // A kwargs-path RENDERING (`:foo`) is NOT a kind label — the
        // CATEGORY axis is orthogonal to the IDENTITY axis; FromStr must
        // reject rendered identities, not silently coerce them.
        let err: UnknownKwargPathKind = ":foo"
            .parse::<KwargPathKind>()
            .expect_err("`:foo` is a KwargPath rendering, not a KwargPathKind label");
        assert_eq!(err.0, ":foo");
        assert_eq!(format!("{err}"), "unknown kwarg path kind: :foo");

        let err: UnknownKwargPathKind = ""
            .parse::<KwargPathKind>()
            .expect_err("empty input must NOT decode to a KwargPathKind");
        assert_eq!(err.0, "");
        assert_eq!(format!("{err}"), "unknown kwarg path kind: ");
    }

    #[test]
    fn kwarg_path_kind_projects_each_variant_to_canonical_kind() {
        // Load-bearing discriminator contract: `KwargPath::kind()` strips
        // the payload and projects to the canonical `KwargPathKind`
        // variant for each `KwargPath` shape. A regression that swaps
        // arms (e.g., `Named` → `KwargPathKind::Slot`) fails-loudly here
        // AND breaks every consumer that buckets by category. Symmetric
        // to `AutoTerminate::kind` and `TerminateReason::kind` in
        // tatara-process.
        assert_eq!(KwargPath::named("threshold").kind(), KwargPathKind::Named);
        assert_eq!(KwargPath::item("steps", 3).kind(), KwargPathKind::Item);
        assert_eq!(KwargPath::Slot(2).kind(), KwargPathKind::Slot);
    }

    #[test]
    fn kwarg_path_kind_is_copy_and_hash_for_metrics_label_ergonomics() {
        // `KwargPathKind` derives Clone + Copy + Debug + PartialEq + Eq
        // + Hash so consumers that use the kind as a metrics-label key
        // (failure-cluster histogram keyed by `path_kind`), a HashMap
        // key (per-category counter), or a Copy-able discriminator in a
        // hot loop (kind projection in a kwarg-gate batching loop) reach
        // for the type without `.clone()` overhead. `String`-carrying
        // `KwargPath` is intentionally NOT `Copy`; `KwargPathKind` IS —
        // the split is the whole point of the discriminator view. A
        // regression that drops Copy or Hash breaks compilation here.
        let k = KwargPathKind::Named;
        let k_copy = k; // Copy
        assert_eq!(k, k_copy);
        let _: String = format!("{k:?}"); // Debug
        let mut s: std::collections::HashSet<KwargPathKind> = std::collections::HashSet::new();
        s.insert(KwargPathKind::Named);
        s.insert(KwargPathKind::Item);
        s.insert(KwargPathKind::Slot);
        s.insert(KwargPathKind::Named); // duplicate insert is a no-op (Hash + Eq)
        assert_eq!(s.len(), 3);
    }

    #[test]
    fn kwarg_path_kind_label_does_not_overlap_kwarg_path_display_renderings() {
        // Cross-axis guard: the CATEGORY labels (`"named"` / `"item"` /
        // `"slot"`) are intentionally disjoint from the IDENTITY
        // renderings (`":<key>"` / `":<key>[<idx>]"` / `"kwargs[<idx>]"`)
        // so a consumer that confuses the two surfaces (e.g., parses
        // `kind.label()` as a `KwargPath` rendering, or parses a rendered
        // path as a kind label) fails-loudly through `FromStr` rejection
        // in both directions. Pin the non-overlap so a future label
        // rename that drifts into the rendering vocabulary (e.g.,
        // renaming `Slot`'s label to `"kwargs"`) fails-loudly here.
        for kind in KwargPathKind::ALL {
            let label = kind.label();
            assert!(
                !label.starts_with(':'),
                "kind label {label:?} must not start with `:` (would collide with KwargPath::Named/Item rendering)"
            );
            assert!(
                !label.contains('['),
                "kind label {label:?} must not contain `[` (would collide with KwargPath::Item/Slot rendering)"
            );
        }
    }

    // ── `KwargPathKind::{NAMED_LABEL, ITEM_LABEL, SLOT_LABEL, LABELS}`
    // — the typed per-role category-label algebra ─────────────────────
    //
    // Sibling posture to `MacroDefHead::{DEFMACRO_KEYWORD,
    // DEFPOINT_TEMPLATE_KEYWORD, DEFCHECK_KEYWORD, KEYWORDS}` — the
    // per-role canonical `&'static str` marker + closed-set
    // `[&'static str; N]` array pattern applied to the
    // `KwargPathKind` closed set. Pre-lift the three canonical
    // category labels lived at TWO structural sites — the
    // `Self::label` match arm AND the sibling truth-table tests
    // (`kwarg_path_kind_all_is_unique_and_complete` sorted-labels
    // pin, `kwarg_path_kind_label_does_not_overlap_kwarg_path_display_renderings`
    // disjointness sweep). Post-lift each (variant, canonical
    // `&'static str`) pairing binds at ONE `pub const` on the typed
    // `KwargPathKind` algebra the `Self::label` arm routes through.

    #[test]
    fn kwarg_path_kind_named_label_projects_canonical_named_bytes() {
        // Pins the exact `"named"` bytes at the typed constant. A
        // regression that drifts the constant (e.g. typo `"name"`,
        // `"Named"` in PascalCase, or an accidental trailing
        // whitespace) fails-loudly here. This is the single site
        // the substrate's canonical typed-atom-extractor failure
        // category resolves to; every downstream consumer (Display,
        // FromStr, tests, LSP completion, metric labels) routes
        // through this constant.
        assert_eq!(
            KwargPathKind::NAMED_LABEL,
            "named",
            "KwargPathKind::NAMED_LABEL drifted from the substrate-\
             canonical typed-atom-extractor failure category `\"named\"`"
        );
    }

    #[test]
    fn kwarg_path_kind_item_label_projects_canonical_item_bytes() {
        // Pins the exact `"item"` bytes at the typed constant. The
        // `extract_string_list` per-item gate emits this exact
        // category; any drift here silently breaks every metric or
        // diagnostic consumer that partitions failures by category.
        assert_eq!(
            KwargPathKind::ITEM_LABEL,
            "item",
            "KwargPathKind::ITEM_LABEL drifted from the substrate-\
             canonical list-item failure category `\"item\"`"
        );
    }

    #[test]
    fn kwarg_path_kind_slot_label_projects_canonical_slot_bytes() {
        // Pins the exact `"slot"` bytes at the typed constant. The
        // `parse_kwargs` slot-must-be-a-keyword gate emits this
        // exact category; any drift here silently breaks every
        // metric or diagnostic consumer that partitions failures by
        // category.
        assert_eq!(
            KwargPathKind::SLOT_LABEL,
            "slot",
            "KwargPathKind::SLOT_LABEL drifted from the substrate-\
             canonical kwargs-slice-slot failure category `\"slot\"`"
        );
    }

    #[test]
    fn kwarg_path_kind_label_method_routes_through_typed_constants() {
        // PATH-UNIFORMITY: the inherent `Self::label(self)` method
        // MUST return the per-role `pub const` byte-for-byte for
        // each reachable variant. A regression that reverts ONE arm
        // to an inline `"named"` string literal (e.g. a merge-
        // conflict resolution that picked the pre-lift form)
        // silently reintroduces the ≥2 PRIME-DIRECTIVE trigger the
        // lift resolved — this test catches that by pinning the
        // arm's return value to the constant, so the two paths
        // (inline vs. typed constant) cannot both hold. Sibling
        // posture to `macro_def_head_keyword_method_routes_through_typed_constants`
        // on the `MacroDefHead` head-keyword algebra.
        assert_eq!(
            KwargPathKind::Named.label(),
            KwargPathKind::NAMED_LABEL,
            "KwargPathKind::Named.label() drifted from \
             KwargPathKind::NAMED_LABEL — the match arm reverted to \
             an inline literal"
        );
        assert_eq!(
            KwargPathKind::Item.label(),
            KwargPathKind::ITEM_LABEL,
            "KwargPathKind::Item.label() drifted from \
             KwargPathKind::ITEM_LABEL — the match arm reverted to \
             an inline literal"
        );
        assert_eq!(
            KwargPathKind::Slot.label(),
            KwargPathKind::SLOT_LABEL,
            "KwargPathKind::Slot.label() drifted from \
             KwargPathKind::SLOT_LABEL — the match arm reverted to \
             an inline literal"
        );
    }

    #[test]
    fn kwarg_path_kind_labels_has_expected_cardinality() {
        // Cardinality contract: `Self::LABELS.len() == 3` — pinned
        // at the declaration site by rustc's forced-arity check on
        // `[&'static str; 3]`. This test surfaces the arity as a
        // fail-loud runtime pin so a future refactor that switches
        // the array type to `&[&'static str]` (dropping the
        // compile-time arity forcing) doesn't silently loosen the
        // closed-set discipline the family relies on. Sibling
        // posture to `macro_def_head_keywords_has_expected_cardinality`
        // on the `MacroDefHead::KEYWORDS` family.
        assert_eq!(
            KwargPathKind::LABELS.len(),
            3,
            "KwargPathKind::LABELS cardinality drifted from 3 — the \
             category-label closed set gained or lost a variant \
             without the ALL / LABELS pair being updated in tandem"
        );
    }

    #[test]
    fn kwarg_path_kind_labels_align_with_all_by_index() {
        // ALIGNMENT CONTRACT: `Self::LABELS[i] ==
        // Self::ALL[i].label()` element-wise. The two ALL arrays
        // (typed variants, canonical `&'static str` labels) share
        // ONE canonical declaration order — a regression that
        // reorders ONE array without reordering the other silently
        // misaligns every `zip(Self::ALL, Self::LABELS)` consumer
        // (LSP completion providers, metric-label emitters, coverage
        // reporters). Pinning by-index alignment here catches the
        // reorder at test time. Sibling posture to
        // `macro_def_head_keywords_align_with_all_by_index` on the
        // `MacroDefHead::KEYWORDS` family.
        assert_eq!(
            KwargPathKind::LABELS.len(),
            KwargPathKind::ALL.len(),
            "KwargPathKind::LABELS and KwargPathKind::ALL diverged in \
             cardinality — the per-role constants and enum variants \
             must stay in lockstep"
        );
        for (i, kind) in KwargPathKind::ALL.iter().enumerate() {
            assert_eq!(
                KwargPathKind::LABELS[i],
                kind.label(),
                "KwargPathKind::LABELS[{i}] `{lb}` drifted from \
                 KwargPathKind::ALL[{i}].label() `{via_variant}` — \
                 the canonical declaration order of the two ALL \
                 arrays must match element-wise",
                lb = KwargPathKind::LABELS[i],
                via_variant = kind.label(),
            );
        }
    }

    #[test]
    fn kwarg_path_kind_labels_pairwise_distinct() {
        // PAIRWISE DISJOINTNESS: the three `&'static str` labels on
        // the category-label algebra MUST differ so the derive-
        // generated FromStr's linear sweep cannot route two variants
        // through the same arm. Family-wide sweep over LABELS ×
        // LABELS — supersedes any single per-pair assertion and
        // picks up new variants mechanically when the array grows.
        // Sibling posture to `macro_def_head_keywords_pairwise_distinct`
        // on the `MacroDefHead::KEYWORDS` family.
        for (i, a) in KwargPathKind::LABELS.iter().enumerate() {
            for (j, b) in KwargPathKind::LABELS.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "KwargPathKind::LABELS[{i}] `{a}` collides with \
                     KwargPathKind::LABELS[{j}] `{b}` — the derive-\
                     generated FromStr sweep would route two variants \
                     through the same arm"
                );
            }
        }
    }

    #[test]
    fn kwarg_path_kind_labels_all_round_trip_through_from_str() {
        // Family-wide bidirection: every entry of `Self::LABELS`
        // MUST parse back to some `KwargPathKind` variant AND that
        // variant's `label()` MUST equal the original entry.
        // Sibling posture to `macro_def_head_keywords_all_round_trip_through_from_str`
        // (which sweeps over `Self::ALL`); this test sweeps over the
        // per-role `&'static str` constants directly, catching a
        // regression where one of the three constants drifts from
        // the corresponding `Self::label` arm (e.g. `SLOT_LABEL` set
        // to `"slice"` while `Self::Slot.label()` still returns
        // `Self::SLOT_LABEL`, which would parse to
        // `KwargPathKind::Slot` correctly but break every downstream
        // consumer that pinned the literal `"slot"` bytes).
        for lb in KwargPathKind::LABELS {
            let parsed: KwargPathKind = lb.parse().unwrap_or_else(|_| {
                panic!(
                    "KwargPathKind::LABELS entry `{lb}` failed to parse \
                     — the entry drifted from Self::label"
                )
            });
            assert_eq!(
                parsed.label(),
                lb,
                "KwargPathKind::LABELS entry `{lb}` parses to a variant \
                 whose label() `{}` does not match — the constant and \
                 the match arm drifted apart",
                parsed.label(),
            );
        }
    }

    // ── ExpectedKwargShape closed-set lift ──────────────────────────────
    //
    // The `LispError::TypeMismatch.expected` slot was promoted from
    // `&'static str` to the typed closed-set `ExpectedKwargShape` enum.
    // The seven reachable expected-shape labels — `Keyword` /
    // `String` / `Int` / `Number` / `Bool` / `List` / `ListOfStrings`
    // — are now encoded as variant identities so authoring tools (REPL,
    // LSP, `tatara-check`) bind on `ExpectedKwargShape::Number` etc.
    // directly rather than substring-matching `expected == "number"`.
    // Same posture as `KwargPath`, `MacroDefHead`, `UnquoteForm`,
    // `CompilerSpecIoStage`, and `TemplateInvariantKind`.

    #[test]
    fn label_renders_canonical_string_for_every_variant() {
        // Pin every variant's canonical `&'static str` projection — a
        // regression that drifts any label (typo in `"strin"` for
        // `"string"`, swap of `"int"` ↔ `"number"`) fails-loudly here.
        // The seven labels are byte-for-byte identical to the pre-lift
        // `&'static str` literals scattered across `domain.rs` so
        // existing `format!("{err}").contains("expected string")`
        // / `expected int` / `expected number` / etc. assertions in
        // consumer crates pass unchanged across the lift.
        assert_eq!(ExpectedKwargShape::Keyword.label(), "keyword");
        assert_eq!(ExpectedKwargShape::String.label(), "string");
        assert_eq!(ExpectedKwargShape::Int.label(), "int");
        assert_eq!(ExpectedKwargShape::Number.label(), "number");
        assert_eq!(ExpectedKwargShape::Bool.label(), "bool");
        assert_eq!(ExpectedKwargShape::List.label(), "list");
        assert_eq!(ExpectedKwargShape::ListOfStrings.label(), "list of strings");
    }

    #[test]
    fn display_matches_label_for_every_variant() {
        // Pin Display-equals-label: the `#[error("... expected
        // {expected}, ...")]` annotation on `LispError::TypeMismatch`
        // projects through Display, and Display delegates to `label()`.
        // A regression that introduces a Display impl that deviates from
        // `label()` (e.g. capitalizing one variant) would drift the
        // diagnostic surface; this test pins the contract.
        assert_eq!(format!("{}", ExpectedKwargShape::Keyword), "keyword");
        assert_eq!(format!("{}", ExpectedKwargShape::String), "string");
        assert_eq!(format!("{}", ExpectedKwargShape::Int), "int");
        assert_eq!(format!("{}", ExpectedKwargShape::Number), "number");
        assert_eq!(format!("{}", ExpectedKwargShape::Bool), "bool");
        assert_eq!(format!("{}", ExpectedKwargShape::List), "list");
        assert_eq!(
            format!("{}", ExpectedKwargShape::ListOfStrings),
            "list of strings"
        );
    }

    #[test]
    fn type_mismatch_expected_carries_typed_shape_through_variant_slot() {
        // After the typed-slot promotion, `LispError::TypeMismatch.expected`
        // is `ExpectedKwargShape` — the closed-set typed enum.
        // Consumers (REPL, LSP, `tatara-check`) pattern-match on the
        // variant identity `ExpectedKwargShape::Number` directly rather
        // than substring-matching a rendered `"expected number"` prefix.
        // Pin the structural binding AND the Display projection so the
        // byte-for-byte rendering contract is anchored from both
        // angles. A regression that re-introduces a `&'static str`-
        // shaped expected slot (collapsing the typed enum back into a
        // free-form label) fails-loudly here.
        let err = LispError::TypeMismatch {
            form: KwargPath::named("threshold"),
            expected: ExpectedKwargShape::Number,
            got: SexpShape::String,
        };
        match &err {
            LispError::TypeMismatch { expected, .. } => {
                assert_eq!(*expected, ExpectedKwargShape::Number);
            }
            other => panic!("expected TypeMismatch, got {other:?}"),
        }
        assert_eq!(
            format!("{err}"),
            "compile error in :threshold: expected number, got string"
        );
    }

    #[test]
    fn type_mismatch_expected_list_of_strings_bifurcates_from_list() {
        // The `extract_string_list` outer-shape gate emits
        // `ExpectedKwargShape::ListOfStrings` (`"list of strings"`),
        // bifurcating structurally from `extract_vec_via_serde`'s
        // outer-shape gate which emits `ExpectedKwargShape::List`
        // (`"list"`). Two related-but-distinct gates, two distinct
        // variant identities; the typed enum makes that bifurcation
        // load-bearing. A regression that collapses them into one
        // variant (e.g. `ExpectedKwargShape::AnyList`) would drift the
        // diagnostic message; this test pins both shapes.
        let list_of_strings = LispError::TypeMismatch {
            form: KwargPath::named("tags"),
            expected: ExpectedKwargShape::ListOfStrings,
            got: SexpShape::String,
        };
        let list = LispError::TypeMismatch {
            form: KwargPath::named("steps"),
            expected: ExpectedKwargShape::List,
            got: SexpShape::String,
        };
        assert_eq!(
            format!("{list_of_strings}"),
            "compile error in :tags: expected list of strings, got string"
        );
        assert_eq!(
            format!("{list}"),
            "compile error in :steps: expected list, got string"
        );
        match (&list_of_strings, &list) {
            (
                LispError::TypeMismatch { expected: a, .. },
                LispError::TypeMismatch { expected: b, .. },
            ) => {
                assert_ne!(a, b);
                assert_eq!(*a, ExpectedKwargShape::ListOfStrings);
                assert_eq!(*b, ExpectedKwargShape::List);
            }
            _ => panic!("both must be TypeMismatch"),
        }
    }

    #[test]
    fn expected_kwarg_shape_all_is_unique_and_complete() {
        // Closed-set posture: `ALL` enumerates every reachable variant
        // EXACTLY ONCE — no duplicates, no omissions. The `[Self; 7]`
        // array literal in the declaration forces the arity at compile
        // time; this test catches the orthogonal failure modes — a
        // future variant added at the type without being added to ALL
        // (silently dropped from every consumer's sweep), or a typo
        // that duplicates an entry (silently double-counted). Same
        // truth-table pinning every sibling closed-set lift in the
        // workspace uses (SexpShape::ALL, MacroDefHead::ALL,
        // UnquoteForm::ALL, RequestorKind::ALL, ReceiptKind::ALL,
        // ConditionKind::ALL, ProcessPhase::ALL, ChannelKind::ALL, …).
        //
        // The `iter+map+collect+sort_unstable` quadruple this test
        // inlined pre-lift now binds at `<ExpectedKwargShape as
        // ClosedSet>::sorted_labels()` — the canonical-ordered
        // candidate-list projection on the trait. Distinctness of the
        // sorted result is covered by
        // `assert_closed_set_well_formed::<ExpectedKwargShape>()`.
        assert_eq!(ExpectedKwargShape::ALL.len(), 7);
        assert_eq!(
            <ExpectedKwargShape as tatara_closed_set::ClosedSet>::sorted_labels(),
            vec![
                "bool",
                "int",
                "keyword",
                "list",
                "list of strings",
                "number",
                "string",
            ],
            "ExpectedKwargShape::ALL must cover every reachable expected-shape label"
        );
    }

    #[test]
    fn expected_kwarg_shape_label_round_trips_through_from_str() {
        // Bidirectional `label` ↔ `FromStr` contract: for every
        // variant in ALL, `shape.label().parse() == Ok(shape)`. A
        // regression that drifts the (variant, literal) pairing at
        // ONE arm of `label` (typo, capitalization drift) OR at the
        // `FromStr` decode body (off-by-one, missing variant in the
        // sweep) fails-loudly here. The canonical-literal site is
        // singular (`label`) so the round-trip is the only way the
        // typed surface and the rendered diagnostic literal can drift
        // apart — pinning it here means they cannot. Mirror of
        // `sexp_shape_label_round_trips_through_from_str` and every
        // sibling closed-set round-trip in the workspace.
        for shape in ExpectedKwargShape::ALL {
            let parsed: ExpectedKwargShape = shape
                .label()
                .parse()
                .expect("every ALL variant's label must round-trip through FromStr");
            assert_eq!(
                parsed,
                shape,
                "FromStr({}) must round-trip to the same variant",
                shape.label()
            );
        }
    }

    #[test]
    fn unknown_expected_kwarg_shape_carries_offending_input_verbatim() {
        // Operator-facing diagnostic contract: the offending input
        // lands in the typed error verbatim — no normalization, no
        // case-folding, no truncation. Pin the exact `#[error(...)]`
        // rendering AND the typed `.0` field projection so a future
        // refactor that normalizes (e.g. `.to_lowercase()`) before
        // building the error or that drops the input fails-loudly
        // here. Symmetric to every sibling `Unknown*` carrier in the
        // workspace.
        let err: UnknownExpectedKwargShape = "Number".parse::<ExpectedKwargShape>().expect_err(
            "capitalized `Number` must NOT decode — labels are byte-equal case-sensitive",
        );
        assert_eq!(err.0, "Number");
        assert_eq!(format!("{err}"), "unknown expected kwarg shape: Number");

        let err: UnknownExpectedKwargShape = "float"
            .parse::<ExpectedKwargShape>()
            .expect_err("`float` is SexpShape's vocabulary, not ExpectedKwargShape's");
        assert_eq!(err.0, "float");
        assert_eq!(format!("{err}"), "unknown expected kwarg shape: float");

        let err: UnknownExpectedKwargShape = ""
            .parse::<ExpectedKwargShape>()
            .expect_err("empty input must NOT decode to an ExpectedKwargShape");
        assert_eq!(err.0, "");
        assert_eq!(format!("{err}"), "unknown expected kwarg shape: ");
    }

    #[test]
    fn expected_kwarg_shape_from_str_accepts_only_canonical_labels() {
        // Cross-axis guard: `SexpShape::label()`'s vocabulary overlaps
        // with `ExpectedKwargShape::label()` on five of seven entries
        // (`keyword` / `string` / `int` / `bool` / `list`) and DOES
        // NOT overlap on the structural-only `nil` / `symbol` /
        // `float` / `quote` / `quasiquote` / `unquote` / `unquote-splice`
        // entries — those name Sexp identities the typed-entry kwarg
        // gate cannot `expect`. The overlap is intentional — both
        // axes are projections of the same `Sexp` algebra at typed-
        // entry gates — but the non-overlap is the load-bearing part:
        // a `FromStr` that silently accepts `"float"` as an
        // `ExpectedKwargShape` would corrupt the typed identity. Pin
        // BOTH directions: the overlap decodes successfully (and to
        // the matching `ExpectedKwargShape` variant), the non-overlap
        // rejects. Symmetric to `sexp_shape_from_str_accepts_only_
        // canonical_labels` from the other axis.
        assert_eq!(
            "keyword".parse::<ExpectedKwargShape>().unwrap(),
            ExpectedKwargShape::Keyword
        );
        assert_eq!(
            "string".parse::<ExpectedKwargShape>().unwrap(),
            ExpectedKwargShape::String
        );
        assert_eq!(
            "int".parse::<ExpectedKwargShape>().unwrap(),
            ExpectedKwargShape::Int
        );
        assert_eq!(
            "bool".parse::<ExpectedKwargShape>().unwrap(),
            ExpectedKwargShape::Bool
        );
        assert_eq!(
            "list".parse::<ExpectedKwargShape>().unwrap(),
            ExpectedKwargShape::List
        );
        // Non-overlap: SexpShape-only labels reject through FromStr.
        for sexp_only in ["nil", "symbol", "float", "quote", "quasiquote", "unquote"] {
            sexp_only.parse::<ExpectedKwargShape>().unwrap_err();
        }
        // ExpectedKwargShape-only labels: `number` and `list of strings`
        // decode here but reject through SexpShape::FromStr — the
        // non-overlap axis is symmetric.
        assert_eq!(
            "number".parse::<ExpectedKwargShape>().unwrap(),
            ExpectedKwargShape::Number
        );
        assert_eq!(
            "list of strings".parse::<ExpectedKwargShape>().unwrap(),
            ExpectedKwargShape::ListOfStrings
        );
        "number".parse::<SexpShape>().unwrap_err();
        "list of strings".parse::<SexpShape>().unwrap_err();
    }

    // ── ExpectedKwargShape per-role `pub const` + LABELS ALL array lift ─
    //
    // Sibling posture to `KwargPathKind::{NAMED_LABEL, ITEM_LABEL,
    // SLOT_LABEL, LABELS}` on the kwarg-path category algebra —
    // per-role canonical `&'static str` marker + closed-set
    // `[&'static str; N]` array pattern applied to the
    // `ExpectedKwargShape` closed set. Pre-lift the seven canonical
    // expected-shape labels lived at TWO structural sites — the
    // `Self::label` match arms AND the sibling truth-table tests
    // (`label_renders_canonical_string_for_every_variant`,
    // `expected_kwarg_shape_all_is_unique_and_complete` sorted-labels
    // pin). Post-lift each (variant, canonical `&'static str`)
    // pairing binds at ONE `pub const` on the typed algebra the
    // `Self::label` arm routes through.

    #[test]
    fn expected_kwarg_shape_keyword_label_projects_canonical_keyword_bytes() {
        // Pins the exact `"keyword"` bytes at the typed constant. The
        // `parse_kwargs` slot-must-be-a-keyword gate emits this exact
        // expected-shape; any drift here silently breaks every metric
        // or diagnostic consumer that partitions failures by expected-
        // shape. Sibling posture to
        // `kwarg_path_kind_named_label_projects_canonical_named_bytes`.
        assert_eq!(
            ExpectedKwargShape::KEYWORD_LABEL,
            "keyword",
            "ExpectedKwargShape::KEYWORD_LABEL drifted from the \
             substrate-canonical slot-must-be-a-keyword gate label \
             `\"keyword\"`"
        );
    }

    #[test]
    fn expected_kwarg_shape_string_label_projects_canonical_string_bytes() {
        // Pins the exact `"string"` bytes at the typed constant.
        // `extract_string` / `extract_optional_string` / the
        // `extract_string_list` per-item gate all emit this exact
        // expected-shape; any drift here silently breaks every
        // consumer. Byte-equal to `SexpShape::STRING_LABEL` (future
        // lift) — the cross-axis overlap on the same `Sexp` algebra
        // is load-bearing.
        assert_eq!(
            ExpectedKwargShape::STRING_LABEL,
            "string",
            "ExpectedKwargShape::STRING_LABEL drifted from the \
             substrate-canonical extract-string gate label \
             `\"string\"`"
        );
    }

    #[test]
    fn expected_kwarg_shape_int_label_projects_canonical_int_bytes() {
        // Pins the exact `"int"` bytes at the typed constant.
        // `extract_int` / `extract_optional_int` emit this exact
        // expected-shape; the sibling `NUMBER_LABEL` names the wider
        // numeric-union the `extract_float` extractor emits.
        assert_eq!(
            ExpectedKwargShape::INT_LABEL,
            "int",
            "ExpectedKwargShape::INT_LABEL drifted from the substrate-\
             canonical extract-int gate label `\"int\"`"
        );
    }

    #[test]
    fn expected_kwarg_shape_number_label_projects_canonical_number_bytes() {
        // Pins the exact `"number"` bytes at the typed constant.
        // `extract_float` / `extract_optional_float` emit this exact
        // expected-shape; the naming (not `"float"`) is load-bearing
        // — `extract_float` accepts BOTH `Sexp::Atom(Float(_))` and
        // `Sexp::Atom(Int(_))` via `Sexp::as_float`, so the label
        // names the union rather than the narrower Float element-
        // type. A regression to `"float"` here would silently narrow
        // the diagnostic's semantics without changing the extractor's
        // acceptance set.
        assert_eq!(
            ExpectedKwargShape::NUMBER_LABEL,
            "number",
            "ExpectedKwargShape::NUMBER_LABEL drifted from the \
             substrate-canonical extract-float gate label \
             `\"number\"`"
        );
    }

    #[test]
    fn expected_kwarg_shape_bool_label_projects_canonical_bool_bytes() {
        // Pins the exact `"bool"` bytes at the typed constant.
        // `extract_bool` / `extract_optional_bool` emit this exact
        // expected-shape.
        assert_eq!(
            ExpectedKwargShape::BOOL_LABEL,
            "bool",
            "ExpectedKwargShape::BOOL_LABEL drifted from the substrate-\
             canonical extract-bool gate label `\"bool\"`"
        );
    }

    #[test]
    fn expected_kwarg_shape_list_label_projects_canonical_list_bytes() {
        // Pins the exact `"list"` bytes at the typed constant.
        // `extract_vec_via_serde`'s outer-shape gate emits this exact
        // expected-shape; the sibling `LIST_OF_STRINGS_LABEL` names
        // the element-typed variant `extract_string_list`'s outer
        // gate emits.
        assert_eq!(
            ExpectedKwargShape::LIST_LABEL,
            "list",
            "ExpectedKwargShape::LIST_LABEL drifted from the substrate-\
             canonical extract-vec-via-serde gate label `\"list\"`"
        );
    }

    #[test]
    fn expected_kwarg_shape_list_of_strings_label_projects_canonical_bytes() {
        // Pins the exact `"list of strings"` bytes at the typed
        // constant. `extract_string_list`'s outer-shape gate emits
        // this exact expected-shape; the naming (not the narrower
        // `"list"`) is load-bearing — it names the element-type so
        // the diagnostic reads `expected list of strings, got
        // string` instead of the ambiguous `expected list, got
        // string`. A regression to `"list"` here would silently
        // collapse the two structurally distinct extractor gates
        // into one indistinguishable diagnostic.
        assert_eq!(
            ExpectedKwargShape::LIST_OF_STRINGS_LABEL,
            "list of strings",
            "ExpectedKwargShape::LIST_OF_STRINGS_LABEL drifted from \
             the substrate-canonical extract-string-list outer-shape \
             gate label `\"list of strings\"`"
        );
    }

    #[test]
    fn expected_kwarg_shape_label_method_routes_through_typed_constants() {
        // PATH-UNIFORMITY: the inherent `Self::label(self)` method
        // MUST return the per-role `pub const` byte-for-byte for
        // each reachable variant. A regression that reverts ONE arm
        // to an inline `"number"` / `"list of strings"` string
        // literal (e.g. a merge-conflict resolution that picked the
        // pre-lift form) silently reintroduces the ≥2 PRIME-DIRECTIVE
        // trigger the lift resolved — this test catches that by
        // pinning the arm's return value to the constant, so the two
        // paths (inline vs. typed constant) cannot both hold.
        // Sibling posture to
        // `kwarg_path_kind_label_method_routes_through_typed_constants`.
        assert_eq!(
            ExpectedKwargShape::Keyword.label(),
            ExpectedKwargShape::KEYWORD_LABEL,
            "ExpectedKwargShape::Keyword.label() drifted from \
             ExpectedKwargShape::KEYWORD_LABEL — the match arm \
             reverted to an inline literal"
        );
        assert_eq!(
            ExpectedKwargShape::String.label(),
            ExpectedKwargShape::STRING_LABEL,
            "ExpectedKwargShape::String.label() drifted from \
             ExpectedKwargShape::STRING_LABEL — the match arm \
             reverted to an inline literal"
        );
        assert_eq!(
            ExpectedKwargShape::Int.label(),
            ExpectedKwargShape::INT_LABEL,
            "ExpectedKwargShape::Int.label() drifted from \
             ExpectedKwargShape::INT_LABEL — the match arm reverted \
             to an inline literal"
        );
        assert_eq!(
            ExpectedKwargShape::Number.label(),
            ExpectedKwargShape::NUMBER_LABEL,
            "ExpectedKwargShape::Number.label() drifted from \
             ExpectedKwargShape::NUMBER_LABEL — the match arm \
             reverted to an inline literal"
        );
        assert_eq!(
            ExpectedKwargShape::Bool.label(),
            ExpectedKwargShape::BOOL_LABEL,
            "ExpectedKwargShape::Bool.label() drifted from \
             ExpectedKwargShape::BOOL_LABEL — the match arm reverted \
             to an inline literal"
        );
        assert_eq!(
            ExpectedKwargShape::List.label(),
            ExpectedKwargShape::LIST_LABEL,
            "ExpectedKwargShape::List.label() drifted from \
             ExpectedKwargShape::LIST_LABEL — the match arm reverted \
             to an inline literal"
        );
        assert_eq!(
            ExpectedKwargShape::ListOfStrings.label(),
            ExpectedKwargShape::LIST_OF_STRINGS_LABEL,
            "ExpectedKwargShape::ListOfStrings.label() drifted from \
             ExpectedKwargShape::LIST_OF_STRINGS_LABEL — the match \
             arm reverted to an inline literal"
        );
    }

    #[test]
    fn expected_kwarg_shape_labels_has_expected_cardinality() {
        // Cardinality contract: `Self::LABELS.len() == 7` — pinned at
        // the declaration site by rustc's forced-arity check on
        // `[&'static str; 7]`. This test surfaces the arity as a
        // fail-loud runtime pin so a future refactor that switches
        // the array type to `&[&'static str]` (dropping the compile-
        // time arity forcing) doesn't silently loosen the closed-set
        // discipline the family relies on. Sibling posture to
        // `kwarg_path_kind_labels_has_expected_cardinality` on the
        // `KwargPathKind::LABELS` family.
        assert_eq!(
            ExpectedKwargShape::LABELS.len(),
            7,
            "ExpectedKwargShape::LABELS cardinality drifted from 7 \
             — the expected-shape closed set gained or lost a variant \
             without the ALL / LABELS pair being updated in tandem"
        );
    }

    #[test]
    fn expected_kwarg_shape_labels_align_with_all_by_index() {
        // ALIGNMENT CONTRACT: `Self::LABELS[i] ==
        // Self::ALL[i].label()` element-wise. The two ALL arrays
        // (typed variants, canonical `&'static str` labels) share
        // ONE canonical declaration order — a regression that
        // reorders ONE array without reordering the other silently
        // misaligns every `zip(Self::ALL, Self::LABELS)` consumer
        // (LSP completion providers, metric-label emitters, coverage
        // reporters). Pinning by-index alignment here catches the
        // reorder at test time. Sibling posture to
        // `kwarg_path_kind_labels_align_with_all_by_index`.
        assert_eq!(
            ExpectedKwargShape::LABELS.len(),
            ExpectedKwargShape::ALL.len(),
            "ExpectedKwargShape::LABELS and ExpectedKwargShape::ALL \
             diverged in cardinality — the per-role constants and \
             enum variants must stay in lockstep"
        );
        for (i, shape) in ExpectedKwargShape::ALL.iter().enumerate() {
            assert_eq!(
                ExpectedKwargShape::LABELS[i],
                shape.label(),
                "ExpectedKwargShape::LABELS[{i}] `{lb}` drifted from \
                 ExpectedKwargShape::ALL[{i}].label() `{via_variant}` \
                 — the canonical declaration order of the two ALL \
                 arrays must match element-wise",
                lb = ExpectedKwargShape::LABELS[i],
                via_variant = shape.label(),
            );
        }
    }

    #[test]
    fn expected_kwarg_shape_labels_pairwise_distinct() {
        // PAIRWISE DISJOINTNESS: the seven `&'static str` labels on
        // the expected-shape algebra MUST differ so the derive-
        // generated FromStr's linear sweep cannot route two variants
        // through the same arm. Family-wide sweep over LABELS ×
        // LABELS — supersedes any single per-pair assertion and picks
        // up new variants mechanically when the array grows. Sibling
        // posture to `kwarg_path_kind_labels_pairwise_distinct`.
        for (i, a) in ExpectedKwargShape::LABELS.iter().enumerate() {
            for (j, b) in ExpectedKwargShape::LABELS.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "ExpectedKwargShape::LABELS[{i}] `{a}` collides \
                     with ExpectedKwargShape::LABELS[{j}] `{b}` — the \
                     derive-generated FromStr sweep would route two \
                     variants through the same arm"
                );
            }
        }
    }

    #[test]
    fn expected_kwarg_shape_labels_all_round_trip_through_from_str() {
        // Family-wide bidirection: every entry of `Self::LABELS` MUST
        // parse back to some `ExpectedKwargShape` variant AND that
        // variant's `label()` MUST equal the original entry. Sibling
        // posture to
        // `kwarg_path_kind_labels_all_round_trip_through_from_str`
        // (sweeps over `Self::ALL`); this test sweeps over the per-
        // role `&'static str` constants directly, catching a
        // regression where one of the seven constants drifts from
        // the corresponding `Self::label` arm (e.g.
        // `LIST_OF_STRINGS_LABEL` set to `"list-of-strings"` while
        // `Self::ListOfStrings.label()` still returns
        // `Self::LIST_OF_STRINGS_LABEL`, which would parse to
        // `ExpectedKwargShape::ListOfStrings` correctly but break
        // every downstream consumer that pinned the literal `"list of
        // strings"` bytes).
        for lb in ExpectedKwargShape::LABELS {
            let parsed: ExpectedKwargShape = lb.parse().unwrap_or_else(|_| {
                panic!(
                    "ExpectedKwargShape::LABELS entry `{lb}` failed to \
                     parse — the entry drifted from Self::label"
                )
            });
            assert_eq!(
                parsed.label(),
                lb,
                "ExpectedKwargShape::LABELS entry `{lb}` parses to a \
                 variant whose label() `{}` does not match — the \
                 constant and the match arm drifted apart",
                parsed.label(),
            );
        }
    }

    #[test]
    fn expected_kwarg_shape_labels_cover_sorted_closed_set() {
        // Family-wide sweep: `Self::LABELS`, projected through sort,
        // MUST equal the derive-generated `sorted_labels()` on the
        // `ClosedSet` trait. Catches a regression where a new
        // variant is added to `Self::ALL` + `Self::label` (so
        // `sorted_labels()` grows) but the maintainer forgets to
        // extend the parallel per-role `pub const` + `Self::LABELS`
        // pair. Distinct from `_align_with_all_by_index` (which pins
        // ORDER preservation) and `_pairwise_distinct` (which pins
        // WITHIN-array uniqueness): this pin cross-checks the LABELS
        // array against the derive-generated candidate-list on the
        // trait, so a partial extension where LABELS grows but ALL
        // doesn't (or vice-versa) surfaces at both this pin AND
        // `_align_with_all_by_index`.
        let mut sorted_labels: Vec<&'static str> = ExpectedKwargShape::LABELS.to_vec();
        sorted_labels.sort_unstable();
        assert_eq!(
            sorted_labels,
            <ExpectedKwargShape as tatara_closed_set::ClosedSet>::sorted_labels(),
            "ExpectedKwargShape::LABELS diverged from the derive-\
             generated `sorted_labels()` — a variant was added or \
             removed from one array without the other tracking"
        );
    }

    // ── SexpShape closed-set lift ───────────────────────────────────────
    //
    // The `LispError::TypeMismatch.got` and
    // `LispError::NamedFormNonSymbolName.got` slots were promoted from
    // `&'static str` to the typed closed-set `SexpShape` enum. The
    // twelve reachable Sexp outermost shapes — `Nil` / `Symbol` /
    // `Keyword` / `String` / `Int` / `Float` / `Bool` / `List` /
    // `Quote` / `Quasiquote` / `Unquote` / `UnquoteSplice` — are now
    // encoded as variant identities so authoring tools (REPL, LSP,
    // `tatara-check`) bind on `SexpShape::Int` etc. directly rather
    // than substring-matching `got == "int"`. Same posture as
    // `KwargPath`, `ExpectedKwargShape`, `MacroDefHead`, `UnquoteForm`,
    // `CompilerSpecIoStage`, and `TemplateInvariantKind`. After this
    // lift the `TypeMismatch` variant is fully closed-set typed in
    // ALL THREE of its slots — no `&'static str` projection remains
    // at any helper boundary.

    #[test]
    fn sexp_shape_label_renders_canonical_string_for_every_variant() {
        // Pin every variant's canonical `&'static str` projection — a
        // regression that drifts any label (typo in `"strin"` for
        // `"string"`, swap of `"int"` ↔ `"float"`, capitalization
        // drift `"Quote"` for `"quote"`) fails-loudly here. The twelve
        // labels are byte-for-byte identical to the pre-lift
        // `sexp_type_name` projection so existing
        // `format!("{err}").contains("got int")` /
        // `got string` / `got list` / etc. assertions in consumer
        // crates pass unchanged across the lift.
        assert_eq!(SexpShape::Nil.label(), "nil");
        assert_eq!(SexpShape::Symbol.label(), "symbol");
        assert_eq!(SexpShape::Keyword.label(), "keyword");
        assert_eq!(SexpShape::String.label(), "string");
        assert_eq!(SexpShape::Int.label(), "int");
        assert_eq!(SexpShape::Float.label(), "float");
        assert_eq!(SexpShape::Bool.label(), "bool");
        assert_eq!(SexpShape::List.label(), "list");
        assert_eq!(SexpShape::Quote.label(), "quote");
        assert_eq!(SexpShape::Quasiquote.label(), "quasiquote");
        assert_eq!(SexpShape::Unquote.label(), "unquote");
        assert_eq!(SexpShape::UnquoteSplice.label(), "unquote-splice");
    }

    #[test]
    fn sexp_shape_display_matches_label_for_every_variant() {
        // Pin Display-equals-label: the `#[error("... got {got}")]`
        // annotations on `LispError::TypeMismatch` and
        // `LispError::NamedFormNonSymbolName` project through Display,
        // and Display delegates to `label()`. A regression that
        // introduces a Display impl that deviates from `label()`
        // (e.g. capitalizing one variant) would drift the diagnostic
        // surface; this test pins the contract.
        assert_eq!(format!("{}", SexpShape::Nil), "nil");
        assert_eq!(format!("{}", SexpShape::Symbol), "symbol");
        assert_eq!(format!("{}", SexpShape::Keyword), "keyword");
        assert_eq!(format!("{}", SexpShape::String), "string");
        assert_eq!(format!("{}", SexpShape::Int), "int");
        assert_eq!(format!("{}", SexpShape::Float), "float");
        assert_eq!(format!("{}", SexpShape::Bool), "bool");
        assert_eq!(format!("{}", SexpShape::List), "list");
        assert_eq!(format!("{}", SexpShape::Quote), "quote");
        assert_eq!(format!("{}", SexpShape::Quasiquote), "quasiquote");
        assert_eq!(format!("{}", SexpShape::Unquote), "unquote");
        assert_eq!(format!("{}", SexpShape::UnquoteSplice), "unquote-splice");
    }

    #[test]
    fn sexp_shape_label_routes_through_typed_per_variant_constants() {
        // PATH-UNIFORMITY: `SexpShape::label(v)` MUST equal the per-role
        // `pub const V_LABEL` for every `v`. Pre-lift the twelve arms
        // held inline `&'static str` literals; post-lift each arm binds
        // to its per-role constant. A regression that reverts ANY arm
        // to an inline literal (e.g. `Self::Symbol => "symbol"`) still
        // renders identically at runtime but silently disagrees with
        // the typed source of truth — this pin closes that drift.
        assert_eq!(SexpShape::Nil.label(), SexpShape::NIL_LABEL);
        assert_eq!(SexpShape::Symbol.label(), SexpShape::SYMBOL_LABEL);
        assert_eq!(SexpShape::Keyword.label(), SexpShape::KEYWORD_LABEL);
        assert_eq!(SexpShape::String.label(), SexpShape::STRING_LABEL);
        assert_eq!(SexpShape::Int.label(), SexpShape::INT_LABEL);
        assert_eq!(SexpShape::Float.label(), SexpShape::FLOAT_LABEL);
        assert_eq!(SexpShape::Bool.label(), SexpShape::BOOL_LABEL);
        assert_eq!(SexpShape::List.label(), SexpShape::LIST_LABEL);
        assert_eq!(SexpShape::Quote.label(), SexpShape::QUOTE_LABEL);
        assert_eq!(SexpShape::Quasiquote.label(), SexpShape::QUASIQUOTE_LABEL);
        assert_eq!(SexpShape::Unquote.label(), SexpShape::UNQUOTE_LABEL);
        assert_eq!(
            SexpShape::UnquoteSplice.label(),
            SexpShape::UNQUOTE_SPLICE_LABEL
        );
    }

    #[test]
    fn sexp_shape_labels_has_expected_cardinality() {
        // Cardinality contract: `Self::LABELS.len() == 12` — the closed
        // set of Sexp outermost shapes has EXACTLY twelve members. A
        // regression that loosens the type to `&[&'static str]` fails
        // HERE, as does a refactor that adds a thirteenth variant to
        // ALL without adding its label to LABELS (rustc's forced-arity
        // check on `[&'static str; 12]` fails compilation).
        assert_eq!(
            SexpShape::LABELS.len(),
            12,
            "SexpShape::LABELS cardinality drifted from 12 — the twelve \
             reachable Sexp outermost shapes were extended without \
             extending the LABELS array in lockstep"
        );
        assert_eq!(SexpShape::LABELS.len(), SexpShape::ALL.len(),);
    }

    #[test]
    fn sexp_shape_labels_align_with_all_by_index() {
        // ALIGNMENT CONTRACT: `Self::LABELS[i] == Self::ALL[i].label()`
        // element-wise. Binds the closed-set outer algebra's ordering
        // to the per-role LABEL constant ordering so any
        // `zip(SexpShape::ALL, SexpShape::LABELS)` consumer (LSP
        // completion, `tatara-check` coverage sweep, Sekiban metric-
        // label emitter) reads a coherent (variant, label) pair off
        // ONE forced-arity array pair rather than through a per-
        // consumer paired-iteration convention.
        for (i, v) in SexpShape::ALL.iter().enumerate() {
            assert_eq!(
                SexpShape::LABELS[i],
                v.label(),
                "SexpShape::LABELS[{i}] `{kw}` drifted from \
                 SexpShape::ALL[{i}].label() `{via_variant}` — the \
                 canonical ALL ordering and the LABELS ordering must \
                 match element-wise",
                kw = SexpShape::LABELS[i],
                via_variant = v.label(),
            );
        }
    }

    #[test]
    fn sexp_shape_labels_pairwise_distinct() {
        // Pairwise disjointness contract: every distinct pair of rows
        // in `Self::LABELS` MUST be byte-distinct. A collision would
        // silently degrade a `TypeMismatch { got: SexpShape::Int, ... }`
        // and a `TypeMismatch { got: SexpShape::Float, ... }` to
        // identically-rendered diagnostics, defeating the closed-set
        // typed-slot promotion. Twelve labels × twelve rows sweeps
        // `LABELS × LABELS` — supersedes any single collision pin.
        for (i, a) in SexpShape::LABELS.iter().enumerate() {
            for (j, b) in SexpShape::LABELS.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "SexpShape::LABELS[{i}] `{a}` collides with \
                     SexpShape::LABELS[{j}] `{b}` — the diagnostic \
                     label surface must be pairwise byte-distinct across \
                     the twelve reachable Sexp outermost shapes"
                );
            }
        }
    }

    #[test]
    fn sexp_shape_atom_carving_labels_align_with_expected_kwarg_shape_labels() {
        // CROSS-AXIS IDENTITY: the SexpShape's atomic-payload carving
        // ({Symbol, Keyword, String, Int, Bool, List}) shares FIVE
        // label-bytes byte-for-byte with ExpectedKwargShape's
        // corresponding per-role constants — the ExpectedKwargShape
        // docstrings on `KEYWORD_LABEL`, `STRING_LABEL`, `INT_LABEL`,
        // `BOOL_LABEL`, `LIST_LABEL` already anticipate this identity
        // ("matches `SexpShape::X_LABEL` byte-for-byte"). Post-lift the
        // identity is a compile-time cross-const composition pin
        // rather than a per-consumer byte-string convention.
        //
        // The overlap is intentional and load-bearing: consumer
        // diagnostic strings like `"expected keyword, got keyword"`
        // reuse the SAME byte-string on both sides of the got/expected
        // gate, so a spelling migration on ONE axis without the OTHER
        // would introduce a silent diagnostic asymmetry. Pinned here.
        assert_eq!(SexpShape::KEYWORD_LABEL, ExpectedKwargShape::KEYWORD_LABEL);
        assert_eq!(SexpShape::STRING_LABEL, ExpectedKwargShape::STRING_LABEL);
        assert_eq!(SexpShape::INT_LABEL, ExpectedKwargShape::INT_LABEL);
        assert_eq!(SexpShape::BOOL_LABEL, ExpectedKwargShape::BOOL_LABEL);
        assert_eq!(SexpShape::LIST_LABEL, ExpectedKwargShape::LIST_LABEL);
        // Non-overlapping bytes on the sibling axes: SexpShape::Float
        // ("float") is the narrower element-type; ExpectedKwargShape's
        // NUMBER_LABEL ("number") is the wider numeric-union label the
        // `extract_float` gate emits. The pair is intentionally
        // distinct — pin it so a naive rename doesn't collapse them.
        assert_ne!(SexpShape::FLOAT_LABEL, ExpectedKwargShape::NUMBER_LABEL);
    }

    #[test]
    fn expected_kwarg_shape_per_role_labels_alias_sexp_shape_per_role_labels_via_static_ptr() {
        // ALIAS-CHAIN ROUTING CONTRACT: the FIVE per-role
        // `pub const ExpectedKwargShape::X_LABEL` constants that share
        // vocabulary with a matching `SexpShape` carving arm MUST route
        // through the parent-superset's `pub const SexpShape::X_LABEL`
        // as a compile-time typed alias
        // (`pub const ExpectedKwargShape::X_LABEL: &'static str =
        // SexpShape::X_LABEL`) rather than as two independent inline
        // string literals whose bytes happen to agree — the byte-
        // equality contract is anchored one test up at
        // `sexp_shape_atom_carving_labels_align_with_expected_kwarg_shape_labels`;
        // THIS pin catches a regression that re-inlines ONE per-role
        // ExpectedKwargShape constant to a fresh literal even when the
        // rendered bytes still agree (because a distinct inline
        // literal lives at a different `&'static str` address inside
        // the rodata segment, while a `pub const` aliased through
        // `SexpShape::X_LABEL` MUST point at the SAME rodata address
        // as the parent superset's constant).
        //
        // Sibling-shape pin to the four prior-run alias-chain routing
        // pins on the UnquoteForm ⊂ QuoteForm 2-of-4 subset carving
        // (`unquote_form_marker_routes_through_to_quote_form_prefix_via_composition`,
        // `unquote_form_label_routes_through_to_quote_form_label_via_composition`,
        // `unquote_form_iac_forge_tag_routes_through_to_quote_form_iac_forge_tag_via_composition`,
        // `unquote_form_hash_discriminator_routes_through_to_quote_form_hash_discriminator_via_composition`)
        // — those pin the substitution-subset composition through the
        // superset via runtime pointer-equality on a value-carrying
        // method; THIS pin pins the ExpectedKwargShape ⊂ SexpShape
        // 5-of-7 subset carving's alias-chain through the parent-
        // superset via compile-time `pub const` identity on a
        // vocabulary-carrying constant.
        //
        // The TWO non-overlapping ExpectedKwargShape arms
        // (`NUMBER_LABEL` and `LIST_OF_STRINGS_LABEL`) stay OUTSIDE
        // this pin's sweep — those are direct-literal constants with
        // no [`SexpShape`] peer to alias through.
        //
        // Theory anchor: THEORY.md §II.1 invariant 5 (composition
        // preserves proofs) — the alias-chain composition law
        // `ExpectedKwargShape::X_LABEL == SexpShape::X_LABEL` on the
        // 5-of-7 subset carving is a rustc-time typed identity, not a
        // runtime byte-equality convention.
        assert!(
            std::ptr::eq(
                ExpectedKwargShape::KEYWORD_LABEL.as_ptr(),
                SexpShape::KEYWORD_LABEL.as_ptr(),
            ),
            "ExpectedKwargShape::KEYWORD_LABEL and SexpShape::KEYWORD_LABEL disagree on `&'static str` rodata address — the alias chain has been broken by an inline-literal re-derivation on the ExpectedKwargShape side",
        );
        assert!(
            std::ptr::eq(
                ExpectedKwargShape::STRING_LABEL.as_ptr(),
                SexpShape::STRING_LABEL.as_ptr(),
            ),
            "ExpectedKwargShape::STRING_LABEL and SexpShape::STRING_LABEL disagree on `&'static str` rodata address — the alias chain has been broken by an inline-literal re-derivation on the ExpectedKwargShape side",
        );
        assert!(
            std::ptr::eq(
                ExpectedKwargShape::INT_LABEL.as_ptr(),
                SexpShape::INT_LABEL.as_ptr(),
            ),
            "ExpectedKwargShape::INT_LABEL and SexpShape::INT_LABEL disagree on `&'static str` rodata address — the alias chain has been broken by an inline-literal re-derivation on the ExpectedKwargShape side",
        );
        assert!(
            std::ptr::eq(
                ExpectedKwargShape::BOOL_LABEL.as_ptr(),
                SexpShape::BOOL_LABEL.as_ptr(),
            ),
            "ExpectedKwargShape::BOOL_LABEL and SexpShape::BOOL_LABEL disagree on `&'static str` rodata address — the alias chain has been broken by an inline-literal re-derivation on the ExpectedKwargShape side",
        );
        assert!(
            std::ptr::eq(
                ExpectedKwargShape::LIST_LABEL.as_ptr(),
                SexpShape::LIST_LABEL.as_ptr(),
            ),
            "ExpectedKwargShape::LIST_LABEL and SexpShape::LIST_LABEL disagree on `&'static str` rodata address — the alias chain has been broken by an inline-literal re-derivation on the ExpectedKwargShape side",
        );
    }

    #[test]
    fn expected_kwarg_shape_residual_labels_lie_outside_sexp_shape_label_vocabulary() {
        // RESIDUAL-CARVING DISJOINTNESS CONTRACT: the TWO
        // ExpectedKwargShape arms that lie OUTSIDE the 5-of-7 aliased
        // subset carving (`NUMBER_LABEL`, `LIST_OF_STRINGS_LABEL`)
        // MUST carry vocabulary distinct from EVERY per-role
        // `SexpShape::X_LABEL` constant — otherwise the 5-of-7
        // carving would fail its subset-and-residual invariant (the
        // subset would carry MORE than 5 aliasable arms, or the
        // residual would carry FEWER than 2 direct-literal arms). The
        // pre-existing pin
        // `sexp_shape_atom_carving_labels_align_with_expected_kwarg_shape_labels`
        // anchors ONE of the two disjointness edges (SexpShape::FLOAT
        // vs ExpectedKwargShape::NUMBER); THIS pin anchors the
        // whole-family disjointness of both residual arms against
        // every SexpShape label at once.
        //
        // A regression that adds `SexpShape::Number` as a new variant
        // (renaming Float to Number) would fail HERE by making
        // `ExpectedKwargShape::NUMBER_LABEL` collide with the newly
        // added `SexpShape::NUMBER_LABEL`; the 5-of-7 carving MUST be
        // re-derived to 6-of-7 in that case (aliasing NUMBER_LABEL
        // through the new SexpShape arm). The pin surfaces the
        // structural-partition-change requirement at the disjointness
        // gate rather than through a silent literal-duplication.
        for &shape in SexpShape::ALL.iter() {
            let via_shape = SexpShape::label(shape);
            assert_ne!(
                ExpectedKwargShape::NUMBER_LABEL,
                via_shape,
                "ExpectedKwargShape::NUMBER_LABEL `\"number\"` collides with SexpShape::{shape:?}.label() `{via_shape}` — the 5-of-7 aliased subset carving's residual arm {{NUMBER}} MUST lie outside every SexpShape label; a collision means the carving needs to be re-derived to a 6-of-7 subset aliased through the newly-overlapping SexpShape arm",
            );
            assert_ne!(
                ExpectedKwargShape::LIST_OF_STRINGS_LABEL,
                via_shape,
                "ExpectedKwargShape::LIST_OF_STRINGS_LABEL `\"list of strings\"` collides with SexpShape::{shape:?}.label() `{via_shape}` — the 5-of-7 aliased subset carving's residual arm {{LIST_OF_STRINGS}} MUST lie outside every SexpShape label",
            );
        }
    }

    #[test]
    fn sexp_shape_quote_carving_labels_align_with_quote_form_iac_forge_tags() {
        // CROSS-AXIS IDENTITY: SexpShape's quote-family carving
        // ({Quote, Quasiquote, Unquote}) shares THREE label-bytes
        // byte-for-byte with QuoteForm's corresponding iac-forge tag
        // constants. Post-lift the identity is a compile-time cross-
        // const composition pin rather than a per-consumer convention.
        //
        // The UnquoteSplice variant is the ONE intentional exception:
        // SexpShape::UNQUOTE_SPLICE_LABEL is `"unquote-splice"` (short
        // form used in `LispError::TypeMismatch` diagnostic Display)
        // while QuoteForm::UNQUOTE_SPLICE_IAC_FORGE_TAG is
        // `"unquote-splicing"` (long form used for cross-crate byte-
        // identical interoperability with the iac-forge canonical
        // form). The asymmetry is documented in the per-role constant's
        // docstring and pinned in
        // `sexp_shape_unquote_splice_label_differs_from_quote_form_iac_forge_tag`.
        assert_eq!(
            SexpShape::QUOTE_LABEL,
            crate::ast::QuoteForm::QUOTE_IAC_FORGE_TAG
        );
        assert_eq!(
            SexpShape::QUASIQUOTE_LABEL,
            crate::ast::QuoteForm::QUASIQUOTE_IAC_FORGE_TAG
        );
        assert_eq!(
            SexpShape::UNQUOTE_LABEL,
            crate::ast::QuoteForm::UNQUOTE_IAC_FORGE_TAG
        );
    }

    #[test]
    fn sexp_shape_unquote_splice_label_differs_from_quote_form_iac_forge_tag() {
        // ONE intentional cross-axis asymmetry: SexpShape's diagnostic
        // label surface uses the SHORTER `"unquote-splice"` bytes while
        // QuoteForm's iac-forge canonical-form tag surface uses the
        // LONGER `"unquote-splicing"` bytes. Pin the asymmetry so a
        // naive rename on either surface doesn't collapse the two
        // sibling label vocabularies onto ONE spelling.
        assert_ne!(
            SexpShape::UNQUOTE_SPLICE_LABEL,
            crate::ast::QuoteForm::UNQUOTE_SPLICE_IAC_FORGE_TAG,
            "SexpShape::UNQUOTE_SPLICE_LABEL and \
             QuoteForm::UNQUOTE_SPLICE_IAC_FORGE_TAG collapsed to ONE \
             spelling — the two sibling label surfaces must render \
             distinct bytes so the UnquoteSplice diagnostic renders \
             the short `\"unquote-splice\"` bytes while iac-forge \
             canonical-form emits the long `\"unquote-splicing\"` bytes"
        );
        assert_eq!(SexpShape::UNQUOTE_SPLICE_LABEL, "unquote-splice");
        assert_eq!(
            crate::ast::QuoteForm::UNQUOTE_SPLICE_IAC_FORGE_TAG,
            "unquote-splicing"
        );
    }

    #[test]
    fn type_mismatch_got_carries_typed_shape_through_variant_slot() {
        // After the typed-slot promotion, `LispError::TypeMismatch.got`
        // is `SexpShape` — the closed-set typed enum. Consumers
        // (REPL, LSP, `tatara-check`) pattern-match on the variant
        // identity `SexpShape::Int` directly rather than
        // substring-matching a rendered `"got int"` prefix. Pin the
        // structural binding AND the Display projection so the
        // byte-for-byte rendering contract is anchored from both
        // angles. A regression that re-introduces a `&'static str`-
        // shaped `got` slot (collapsing the typed enum back into a
        // free-form label) fails-loudly here.
        let err = LispError::TypeMismatch {
            form: KwargPath::named("threshold"),
            expected: ExpectedKwargShape::Number,
            got: SexpShape::String,
        };
        match &err {
            LispError::TypeMismatch { got, .. } => {
                assert_eq!(*got, SexpShape::String);
            }
            other => panic!("expected TypeMismatch, got {other:?}"),
        }
        assert_eq!(
            format!("{err}"),
            "compile error in :threshold: expected number, got string"
        );
    }

    #[test]
    fn named_form_non_symbol_name_got_carries_typed_shape_through_variant_slot() {
        // Sibling pin to `type_mismatch_got_…` on the second `got`
        // slot that flows from `sexp_shape`. Both
        // `LispError::TypeMismatch.got` and
        // `LispError::NamedFormNonSymbolName.got` are typed
        // `SexpShape` now — one helper (`crate::domain::sexp_shape`)
        // is the single projection source, and rustc-enforces
        // matching at every projection site. A regression that
        // bifurcates the two slots (e.g. typed `SexpShape` on one,
        // `&'static str` on the other) fails-loudly here.
        let err = LispError::NamedFormNonSymbolName {
            keyword: "defpoint",
            got: SexpShape::List,
        };
        match &err {
            LispError::NamedFormNonSymbolName { got, .. } => {
                assert_eq!(*got, SexpShape::List);
            }
            other => panic!("expected NamedFormNonSymbolName, got {other:?}"),
        }
        assert_eq!(
            format!("{err}"),
            "compile error in defpoint: positional NAME must be a symbol or string (got list)"
        );
    }

    #[test]
    fn sexp_shape_all_is_unique_and_complete() {
        // Closed-set posture: `ALL` enumerates every reachable variant
        // EXACTLY ONCE — no duplicates, no omissions. The `[Self; 12]`
        // array literal in the declaration forces the arity at compile
        // time; this test catches the orthogonal failure modes — a
        // future variant added at the type without being added to ALL
        // (silently dropped from every consumer's sweep), or a typo
        // that duplicates an entry (silently double-counted). Same
        // truth-table pinning every sibling closed-set lift in the
        // workspace uses (RequestorKind::ALL, ReceiptKind::ALL,
        // ConditionKind::ALL, ProcessPhase::ALL, ChannelKind::ALL, …).
        //
        // The `iter+map+collect+sort_unstable` quadruple this test
        // inlined pre-lift now binds at `<SexpShape as
        // ClosedSet>::sorted_labels()` — the canonical-ordered
        // candidate-list projection on the trait. Distinctness of the
        // sorted result is covered by
        // `assert_closed_set_well_formed::<SexpShape>()`.
        assert_eq!(SexpShape::ALL.len(), 12);
        assert_eq!(
            <SexpShape as tatara_closed_set::ClosedSet>::sorted_labels(),
            vec![
                "bool",
                "float",
                "int",
                "keyword",
                "list",
                "nil",
                "quasiquote",
                "quote",
                "string",
                "symbol",
                "unquote",
                "unquote-splice",
            ],
            "SexpShape::ALL must cover every reachable Sexp outermost shape"
        );
    }

    #[test]
    fn sexp_shape_label_round_trips_through_from_str() {
        // Bidirectional `label` ↔ `FromStr` contract: for every
        // variant in ALL, `shape.label().parse() == Ok(shape)`. A
        // regression that drifts the (variant, literal) pairing at
        // ONE arm of `label` (typo, capitalization drift) OR at the
        // `FromStr` decode body (off-by-one, missing variant in the
        // sweep) fails-loudly here. The canonical-literal site is
        // singular (`label`) so the round-trip is the only way the
        // typed surface and the rendered diagnostic literal can
        // drift apart — pinning it here means they cannot.
        for shape in SexpShape::ALL {
            let parsed: SexpShape = shape
                .label()
                .parse()
                .expect("every ALL variant's label must round-trip through FromStr");
            assert_eq!(
                parsed,
                shape,
                "FromStr({}) must round-trip to the same variant",
                shape.label()
            );
        }
    }

    #[test]
    fn unknown_sexp_shape_carries_offending_input_verbatim() {
        // Operator-facing diagnostic contract: the offending input
        // lands in the typed error verbatim — no normalization, no
        // case-folding, no truncation. Pin the exact `#[error(...)]`
        // rendering AND the typed `.0` field projection so a future
        // refactor that normalizes (e.g. `.to_lowercase()`) before
        // building the error or that drops the input fails-loudly
        // here. Symmetric to every sibling `Unknown*` carrier in the
        // workspace.
        let err: UnknownSexpShape = "Symbol".parse::<SexpShape>().expect_err(
            "capitalized `Symbol` must NOT decode — labels are byte-equal case-sensitive",
        );
        assert_eq!(err.0, "Symbol");
        assert_eq!(format!("{err}"), "unknown sexp shape: Symbol");

        let err: UnknownSexpShape = "number"
            .parse::<SexpShape>()
            .expect_err("`number` is ExpectedKwargShape's vocabulary, not SexpShape's");
        assert_eq!(err.0, "number");
        assert_eq!(format!("{err}"), "unknown sexp shape: number");

        let err: UnknownSexpShape = ""
            .parse::<SexpShape>()
            .expect_err("empty input must NOT decode to a SexpShape");
        assert_eq!(err.0, "");
        assert_eq!(format!("{err}"), "unknown sexp shape: ");
    }

    #[test]
    fn sexp_shape_from_str_accepts_only_canonical_labels() {
        // Cross-axis guard: `ExpectedKwargShape::label()`'s vocabulary
        // overlaps with `SexpShape::label()` on five of seven entries
        // (`keyword` / `string` / `int` / `bool` / `list`) and DOES
        // NOT overlap on two (`number` / `list of strings`). The
        // overlap is intentional — both axes are projections of the
        // same `Sexp` algebra at typed-entry gates — but the
        // non-overlap is the load-bearing part: a `FromStr` that
        // silently accepts `"number"` as a `SexpShape` would corrupt
        // the typed identity. Pin BOTH directions: the overlap
        // decodes successfully (and to the matching `SexpShape`
        // variant), the non-overlap rejects.
        assert_eq!("keyword".parse::<SexpShape>().unwrap(), SexpShape::Keyword);
        assert_eq!("string".parse::<SexpShape>().unwrap(), SexpShape::String);
        assert_eq!("int".parse::<SexpShape>().unwrap(), SexpShape::Int);
        assert_eq!("bool".parse::<SexpShape>().unwrap(), SexpShape::Bool);
        assert_eq!("list".parse::<SexpShape>().unwrap(), SexpShape::List);

        assert!("number".parse::<SexpShape>().is_err());
        assert!("list of strings".parse::<SexpShape>().is_err());

        // Sanity: every UnquoteForm marker literal (`,` / `,@` / etc.)
        // is also NOT a SexpShape label — the marker projection lives
        // on a different axis (the rendered punctuation) than the
        // shape label (the structural identity).
        assert!(",".parse::<SexpShape>().is_err());
        assert!(",@".parse::<SexpShape>().is_err());
    }

    #[test]
    fn sexp_shape_int_bifurcates_from_float_through_variant_slot() {
        // `Int` and `Float` are distinct typed variants — a regression
        // that collapses them into a single `Number` variant (which
        // would drop the bifurcation that `Sexp::Atom(Int(_))` and
        // `Sexp::Atom(Float(_))` already carry at the AST layer) is
        // caught here. The two render distinct rendered labels and
        // hold distinct variant identities.
        let int_err = LispError::TypeMismatch {
            form: KwargPath::named("count"),
            expected: ExpectedKwargShape::String,
            got: SexpShape::Int,
        };
        let float_err = LispError::TypeMismatch {
            form: KwargPath::named("ratio"),
            expected: ExpectedKwargShape::String,
            got: SexpShape::Float,
        };
        assert_eq!(
            format!("{int_err}"),
            "compile error in :count: expected string, got int"
        );
        assert_eq!(
            format!("{float_err}"),
            "compile error in :ratio: expected string, got float"
        );
        match (&int_err, &float_err) {
            (LispError::TypeMismatch { got: a, .. }, LispError::TypeMismatch { got: b, .. }) => {
                assert_ne!(a, b);
                assert_eq!(*a, SexpShape::Int);
                assert_eq!(*b, SexpShape::Float);
            }
            _ => panic!("both must be TypeMismatch"),
        }
    }

    // ── SexpShape ↔ AtomKind / QuoteForm: typed-shape lattice inverses ──
    //
    // The forward embed projections [`crate::ast::AtomKind::sexp_shape`]
    // (6→12) and [`crate::ast::QuoteForm::sexp_shape`] (4→12) have
    // existed for prior runs (commits 121bb60 + b15-ish); their dual
    // projections [`SexpShape::as_atom_kind`] (12→6, partial) and
    // [`SexpShape::as_quote_form`] (12→4, partial) close the
    // embed/project section on the typed-shape lattice. The
    // composition laws below pin the (embed, project) pair is an
    // `Iso(AtomKind, AtomShape ⊂ SexpShape)` AND
    // `Iso(QuoteForm, QuoteShape ⊂ SexpShape)` — every typed marker
    // round-trips through the embed, every shape pre-image recovers
    // the typed marker. Pre-lift the typed-shape lattice's two
    // forward embeds had no dual projection naming the inverse 6-of-
    // 12 + 4-of-12 carvings; post-lift the carvings live at ONE site
    // each on the [`SexpShape`] algebra so a regression that drifts
    // the inverse from the embed surfaces at the round-trip pin
    // instead of at every speculative LSP / REPL / `tatara-check` /
    // metrics consumer's per-carving inline `match`.

    #[test]
    fn as_atom_kind_projects_each_atom_shape_to_canonical_atom_kind_and_rejects_non_atom_shapes() {
        // Per-variant truth-table sweep across every `SexpShape::ALL`
        // entry — pins each variant's canonical mapping (atomic-payload
        // arms project to the matching `AtomKind`; `Nil` / `List` /
        // every quote-family arm project to `None`) byte-for-byte so a
        // regression that drifts ONE arm (e.g. swaps `Symbol →
        // AtomKind::Keyword`, drops `Bool`'s arm to `None`, accepts
        // `List` as `Some(AtomKind::Str)`) fails loudly. The full
        // `SexpShape::ALL` sweep doubles as exhaustiveness — adding a
        // hypothetical thirteenth variant (e.g. `Vector` for `#(...)`)
        // forces the test author to extend BOTH this sweep AND the
        // typed `match` body, with rustc enforcing the match arm's
        // presence and this sweep enforcing the (variant, projected
        // mapping) pairing's canonical-form.
        use crate::ast::AtomKind;
        for shape in SexpShape::ALL {
            let projected = shape.as_atom_kind();
            let expected = match shape {
                SexpShape::Symbol => Some(AtomKind::Symbol),
                SexpShape::Keyword => Some(AtomKind::Keyword),
                SexpShape::String => Some(AtomKind::Str),
                SexpShape::Int => Some(AtomKind::Int),
                SexpShape::Float => Some(AtomKind::Float),
                SexpShape::Bool => Some(AtomKind::Bool),
                SexpShape::Nil
                | SexpShape::List
                | SexpShape::Quote
                | SexpShape::Quasiquote
                | SexpShape::Unquote
                | SexpShape::UnquoteSplice => None,
            };
            assert_eq!(
                projected, expected,
                "SexpShape::{shape:?}.as_atom_kind() drifted from canonical mapping"
            );
        }
    }

    #[test]
    fn atom_kind_sexp_shape_round_trips_through_as_atom_kind() {
        // The embed/project section law on the atomic carving:
        // `AtomKind::sexp_shape(k).as_atom_kind() == Some(k)` for every
        // `k: AtomKind::ALL`. Pinning the round-trip for every variant
        // in the closed set proves the (embed, project) pair is an
        // `Iso(AtomKind, AtomShape ⊂ SexpShape)` — the section is total
        // on `AtomKind`'s carving. A regression that drifts EITHER
        // direction (an `AtomKind::sexp_shape` arm that mis-maps OR a
        // `SexpShape::as_atom_kind` arm that mis-inverts) fails here
        // without depending on any per-consumer call site. Same posture
        // as `unquote_form_marker_routes_through_to_quote_form_prefix_
        // via_composition`'s round-trip on the 2-of-4 quote-family
        // subset.
        use crate::ast::AtomKind;
        for kind in AtomKind::ALL {
            let shape = kind.sexp_shape();
            let recovered = shape.as_atom_kind();
            assert_eq!(
                recovered,
                Some(kind),
                "AtomKind::{kind:?} did NOT round-trip — sexp_shape().as_atom_kind() must recover the typed marker"
            );
        }
    }

    #[test]
    fn as_quote_form_projects_each_quote_shape_to_canonical_quote_form_and_rejects_non_quote_shapes(
    ) {
        // Per-variant truth-table sweep across every `SexpShape::ALL`
        // entry — pins each variant's canonical mapping (quote-family
        // arms project to the matching `QuoteForm`; `Nil` / `List` /
        // every atomic-payload arm project to `None`) byte-for-byte.
        // Sibling sweep to
        // `as_atom_kind_projects_each_atom_shape_to_canonical_atom_kind_and_rejects_non_atom_shapes`
        // on the quote-family axis.
        use crate::ast::QuoteForm;
        for shape in SexpShape::ALL {
            let projected = shape.as_quote_form();
            let expected = match shape {
                SexpShape::Quote => Some(QuoteForm::Quote),
                SexpShape::Quasiquote => Some(QuoteForm::Quasiquote),
                SexpShape::Unquote => Some(QuoteForm::Unquote),
                SexpShape::UnquoteSplice => Some(QuoteForm::UnquoteSplice),
                SexpShape::Nil
                | SexpShape::List
                | SexpShape::Symbol
                | SexpShape::Keyword
                | SexpShape::String
                | SexpShape::Int
                | SexpShape::Float
                | SexpShape::Bool => None,
            };
            assert_eq!(
                projected, expected,
                "SexpShape::{shape:?}.as_quote_form() drifted from canonical mapping"
            );
        }
    }

    #[test]
    fn quote_form_sexp_shape_round_trips_through_as_quote_form() {
        // The embed/project section law on the quote-family carving:
        // `QuoteForm::sexp_shape(qf).as_quote_form() == Some(qf)` for
        // every `qf: QuoteForm::ALL`. Proves the (embed, project) pair
        // is an `Iso(QuoteForm, QuoteShape ⊂ SexpShape)` — the section
        // is total on `QuoteForm`'s carving. Sibling round-trip to
        // `atom_kind_sexp_shape_round_trips_through_as_atom_kind` on
        // the quote-family axis.
        use crate::ast::QuoteForm;
        for qf in QuoteForm::ALL {
            let shape = qf.sexp_shape();
            let recovered = shape.as_quote_form();
            assert_eq!(
                recovered,
                Some(qf),
                "QuoteForm::{qf:?} did NOT round-trip — sexp_shape().as_quote_form() must recover the typed marker"
            );
        }
    }

    #[test]
    fn as_atom_kind_and_as_quote_form_partition_carvable_sexp_shape_variants() {
        // Disjointness invariant: for every variant in
        // `SexpShape::ALL`, AT MOST ONE of `as_atom_kind()` and
        // `as_quote_form()` returns `Some` — the typed-shape lattice's
        // two named carvings partition the carve-able SexpShape
        // variants. The two non-carved variants (`Nil`, `List`) project
        // to `None` through BOTH projections — the kernel of both
        // partial inverses. A regression that drifts the partition
        // (e.g. accepts `SexpShape::List` as an atom kind, or as a
        // quote form) fails here. Sibling to
        // `as_atom_kind_projects_each_atom_shape_to_canonical_atom_kind_and_rejects_non_atom_shapes`
        // and
        // `as_quote_form_projects_each_quote_shape_to_canonical_quote_form_and_rejects_non_quote_shapes`
        // — those pin the per-axis canonical mapping; this pins the
        // joint disjointness across both axes. The residual-side of the
        // partition (the two `Nil`/`List` variants) is now itself a
        // typed carving `StructuralKind` — pinned by
        // `sexp_shape_partition_is_total_across_atom_quote_structural_carvings`.
        for shape in SexpShape::ALL {
            let atom = shape.as_atom_kind().is_some();
            let quote = shape.as_quote_form().is_some();
            assert!(
                !(atom && quote),
                "SexpShape::{shape:?} projects as BOTH an atom kind AND a quote form — typed-shape carvings must be disjoint"
            );
            // Cross-axis closure: the only variants that project as
            // NEITHER are the structural-residual shapes (`Nil` and
            // `List`). Every other variant must be in exactly ONE of
            // the two named carvings — the substrate's typed-shape
            // lattice's structural completeness pin. Post-lift the
            // residual-side identity binds to the typed
            // `as_structural_kind()` projection rather than a runtime
            // `matches!(shape, SexpShape::Nil | SexpShape::List)`
            // predicate; the invariant lives at ONE closed-set match
            // on the outer algebra.
            let carved = atom || quote;
            let expected_carved = shape.as_structural_kind().is_none();
            assert_eq!(
                carved, expected_carved,
                "SexpShape::{shape:?} must be carved iff it does not project through as_structural_kind"
            );
        }
    }

    #[test]
    fn sexp_shape_partition_is_total_across_atom_quote_structural_carvings() {
        // Partition-total invariant across ALL THREE typed-shape
        // carvings — the (typed theorem, previously test assertion)
        // this lift makes structural. For every variant in
        // `SexpShape::ALL`, EXACTLY ONE of `as_atom_kind()`,
        // `as_quote_form()`, `as_structural_kind()` returns `Some(_)`.
        // Pre-lift the residual side lived at ONE inline
        // `!matches!(shape, SexpShape::Nil | SexpShape::List)`
        // assertion inside the carving-disjointness pin above (the
        // runtime witness the substrate maintained by test
        // discipline); post-lift the residual is a TYPED CARVING
        // binding at ONE typed-algebra method, and the partition-
        // total invariant across the three carvings becomes a TYPED
        // THEOREM the joint sweep here surfaces byte-for-byte.
        //
        // Cardinalities: 6 + 4 + 2 = 12 (atomic-payload + quote-family
        // + structural-residual = every SexpShape). A regression that
        // drifts the partition-membership of any variant across any
        // of the three carvings surfaces here.
        let mut atom_count = 0;
        let mut quote_count = 0;
        let mut structural_count = 0;
        for shape in SexpShape::ALL {
            let atom = shape.as_atom_kind().is_some();
            let quote = shape.as_quote_form().is_some();
            let structural = shape.as_structural_kind().is_some();
            let membership = usize::from(atom) + usize::from(quote) + usize::from(structural);
            assert_eq!(
                membership, 1,
                "SexpShape::{shape:?} lands in {membership} carvings — partition must land it in EXACTLY ONE of (as_atom_kind, as_quote_form, as_structural_kind)",
            );
            atom_count += usize::from(atom);
            quote_count += usize::from(quote);
            structural_count += usize::from(structural);
        }
        assert_eq!(
            atom_count, 6,
            "atomic-payload carving must cover EXACTLY 6 of SexpShape::ALL",
        );
        assert_eq!(
            quote_count, 4,
            "quote-family carving must cover EXACTLY 4 of SexpShape::ALL",
        );
        assert_eq!(
            structural_count, 2,
            "structural-residual carving must cover EXACTLY 2 of SexpShape::ALL",
        );
        assert_eq!(
            atom_count + quote_count + structural_count,
            SexpShape::ALL.len(),
            "the three carvings must partition SexpShape::ALL totally (6 + 4 + 2 = 12)",
        );
    }

    #[test]
    fn as_atom_kind_composes_with_sexp_shape_via_atom_kind_label_round_trip() {
        // Cross-projection composition law: for every atom kind, the
        // diagnostic label round-trips through both directions of the
        // embed/project pair AND `AtomKind::label`:
        // `AtomKind::ALL[i].label() == AtomKind::ALL[i].sexp_shape()
        // .as_atom_kind().expect("...").label()`. This pin proves the
        // typed-shape lattice's two carvings are not only structural
        // inverses but ALSO label-coherent — a regression that drifts
        // the (AtomKind variant, SexpShape variant) pairing while
        // preserving the projection's structural inverseness (e.g. a
        // future refactor that renames the variants in lockstep but
        // leaves the per-variant labels stale) surfaces here. The
        // label-coherence binds the diagnostic surface to the typed
        // algebra at BOTH layers.
        use crate::ast::AtomKind;
        for kind in AtomKind::ALL {
            let via_round_trip = kind
                .sexp_shape()
                .as_atom_kind()
                .expect("every AtomKind round-trips through the embed/project pair")
                .label();
            assert_eq!(
                via_round_trip,
                kind.label(),
                "AtomKind::{kind:?}.label() drifted from sexp_shape().as_atom_kind().label() — embed/project must preserve label coherence"
            );
        }
    }

    #[test]
    fn as_quote_form_composes_with_sexp_shape_via_quote_form_prefix_round_trip() {
        // Cross-projection composition law (quote-family sibling of
        // `as_atom_kind_composes_with_sexp_shape_via_atom_kind_label_round_trip`):
        // for every `qf: QuoteForm::ALL`,
        // `qf.prefix() == qf.sexp_shape().as_quote_form().expect("...").prefix()`.
        // Pins the (QuoteForm variant, SexpShape variant) pairing
        // round-trips through the embed/project pair AND preserves
        // each variant's canonical homoiconic-prefix punctuation
        // (`"'"` / `` "`" `` / `","` / `",@"`) — a regression that
        // drifts the round-trip OR drifts the prefix surfaces here.
        use crate::ast::QuoteForm;
        for qf in QuoteForm::ALL {
            let via_round_trip = qf
                .sexp_shape()
                .as_quote_form()
                .expect("every QuoteForm round-trips through the embed/project pair")
                .prefix();
            assert_eq!(
                via_round_trip,
                qf.prefix(),
                "QuoteForm::{qf:?}.prefix() drifted from sexp_shape().as_quote_form().prefix() — embed/project must preserve prefix coherence"
            );
        }
    }

    // ── UnquoteForm: ALL closure + FromStr round-trip ──────────────────
    //
    // `UnquoteForm` (the two template-marker syntactic forms `,` and
    // `,@`) joins the substrate's closed-set algebra family —
    // `SexpShape::ALL` + `FromStr`, `AtomKind::ALL` + `FromStr`,
    // `RequestorKind::ALL` + `FromStr`, etc. — by lifting the canonical
    // `&'static str` marker literal vocabulary onto ONE site
    // (`Self::marker` keyed by `Self::ALL`) the operator-facing decode
    // path inverts. Pre-lift the punctuation vocabulary lived ONLY
    // in `marker()`'s match arms; post-lift the SAME vocabulary
    // round-trips through `FromStr` keyed on the closed set, so the
    // typed surface and the rendered diagnostic literal cannot drift.
    // Same posture as `sexp_shape_label_round_trips_through_from_str`
    // / `atom_kind_label_round_trips_through_from_str`.

    #[test]
    fn unquote_form_all_is_unique_and_complete() {
        // Closed-set posture: `ALL` enumerates every reachable variant
        // EXACTLY ONCE — no duplicates, no omissions. The `[Self; 2]`
        // array literal in the declaration forces the arity at compile
        // time; this test catches the orthogonal failure modes — a
        // future variant added at the type without being added to ALL
        // (silently dropped from every consumer's sweep), or a typo
        // that duplicates an entry (silently double-counted). Same
        // truth-table pinning every sibling closed-set lift in the
        // workspace uses (SexpShape::ALL, AtomKind::ALL,
        // RequestorKind::ALL, ReceiptKind::ALL, ConditionKind::ALL, …).
        //
        // The `iter+map+collect+sort_unstable` quadruple this test
        // inlined pre-lift now binds at `<UnquoteForm as
        // ClosedSet>::sorted_labels()` — the canonical-ordered
        // candidate-list projection on the trait. Distinctness of the
        // sorted result is covered by
        // `assert_closed_set_well_formed::<UnquoteForm>()`.
        assert_eq!(UnquoteForm::ALL.len(), 2);
        assert_eq!(
            <UnquoteForm as tatara_closed_set::ClosedSet>::sorted_labels(),
            vec![",", ",@"],
            "UnquoteForm::ALL must cover both template-marker syntactic forms"
        );
    }

    #[test]
    fn unquote_form_marker_round_trips_through_from_str() {
        // Bidirectional `marker` ↔ `FromStr` contract: for every
        // variant in ALL, `form.marker().parse() == Ok(form)`. A
        // regression that drifts the (variant, literal) pairing at
        // ONE arm of `marker` (typo, `,,` instead of `,`, `, @` with
        // a stray space) OR at the `FromStr` decode body (off-by-one,
        // missing variant in the sweep) fails-loudly here. The
        // canonical-literal site is singular (`marker`) so the
        // round-trip is the only way the typed surface and the
        // rendered diagnostic literal can drift apart — pinning it
        // here means they cannot.
        for form in UnquoteForm::ALL {
            let parsed: UnquoteForm = form
                .marker()
                .parse()
                .expect("every ALL variant's marker must round-trip through FromStr");
            assert_eq!(
                parsed,
                form,
                "FromStr({}) must round-trip to the same variant",
                form.marker()
            );
        }
    }

    #[test]
    fn unknown_unquote_form_carries_offending_input_verbatim() {
        // Operator-facing diagnostic contract: the offending input
        // lands in the typed error verbatim — no normalization, no
        // truncation, no whitespace coercion. Pin the exact
        // `#[error(...)]` rendering AND the typed `.0` field
        // projection so a future refactor that normalizes (e.g.
        // `.trim()`) before building the error or that drops the
        // input fails-loudly here. Symmetric to every sibling
        // `Unknown*` carrier in the workspace
        // ([`UnknownSexpShape`], [`crate::ast::UnknownAtomKind`],
        // `tatara_process::allocation::UnknownRequestorKind`, …).
        let err: UnknownUnquoteForm = ",,"
            .parse::<UnquoteForm>()
            .expect_err("doubled comma `,,` is not a canonical template marker");
        assert_eq!(err.0, ",,");
        assert_eq!(format!("{err}"), "unknown unquote form: ,,");

        let err: UnknownUnquoteForm = ",@@"
            .parse::<UnquoteForm>()
            .expect_err("doubled-at `,@@` is not a canonical template marker");
        assert_eq!(err.0, ",@@");
        assert_eq!(format!("{err}"), "unknown unquote form: ,@@");

        let err: UnknownUnquoteForm = ""
            .parse::<UnquoteForm>()
            .expect_err("empty input must NOT decode to an UnquoteForm");
        assert_eq!(err.0, "");
        assert_eq!(format!("{err}"), "unknown unquote form: ");
    }

    #[test]
    fn unquote_form_from_str_rejects_sexp_shape_labels_on_template_marker_axis() {
        // Cross-axis guard: [`SexpShape`] projects the SAME two
        // `Sexp::Unquote` / `Sexp::UnquoteSplice` constructors as
        // [`UnquoteForm`] does, but onto a DIFFERENT vocabulary —
        // `"unquote"` / `"unquote-splice"` (structural-identity labels)
        // vs `","` / `",@"` (punctuation markers). The two axes share
        // the same closed-set cardinality (2) but their vocabularies
        // are intentionally disjoint. A `FromStr` that silently
        // accepted `"unquote"` as an `UnquoteForm` would corrupt the
        // typed identity at the diagnostic boundary. Pin BOTH
        // directions: the SAME punctuation labels (`,` / `,@`) decode
        // through [`UnquoteForm`] but NOT through [`SexpShape`]; the
        // SAME structural labels (`"unquote"` / `"unquote-splice"`)
        // decode through [`SexpShape`] but NOT through [`UnquoteForm`].
        // Anchors the cross-axis disjointness from BOTH sides so a
        // regression that conflates the two axes' vocabularies fails
        // here.
        assert_eq!(",".parse::<UnquoteForm>().unwrap(), UnquoteForm::Unquote);
        assert_eq!(",@".parse::<UnquoteForm>().unwrap(), UnquoteForm::Splice);

        // The structural-identity labels project the SAME variants on
        // the SexpShape axis but are NOT canonical UnquoteForm markers.
        assert!("unquote".parse::<UnquoteForm>().is_err());
        assert!("unquote-splice".parse::<UnquoteForm>().is_err());

        // Sibling homoiconic-prefix-wrapper markers (`'` for quote,
        // `` ` `` for quasiquote) belong to the WIDER QuoteForm
        // superset on the SAME punctuation axis — they MUST reject
        // here because UnquoteForm carves the 2-of-4 template-
        // substitution subset of QuoteForm's 4-prefix closed set.
        assert!("'".parse::<UnquoteForm>().is_err());
        assert!("`".parse::<UnquoteForm>().is_err());

        // Whitespace-padded markers are NOT canonical — the
        // round-trip must be exact byte-for-byte against `marker()`.
        assert!(" ,".parse::<UnquoteForm>().is_err());
        assert!(", ".parse::<UnquoteForm>().is_err());
        assert!(", @".parse::<UnquoteForm>().is_err());
    }

    #[test]
    fn unquote_form_to_quote_form_round_trips_through_as_unquote_form() {
        // Pin the 2-of-4 subset → superset projection as a typed
        // section of [`crate::ast::QuoteForm::as_unquote_form`]: for
        // every `uf: UnquoteForm`, `uf.to_quote_form().as_unquote_form()
        // == Some(uf)`. Closes the (UnquoteForm, QuoteForm) pairing as
        // a round-trip identity on the typed algebra — pre-lift the
        // pairing only lived in the existing
        // `unquote_form_marker_subset_decodes_through_quote_form_from_str`
        // cross-axis test (which round-tripped through the rendered
        // marker string + FromStr); post-lift the pairing rides the
        // typed projection directly so a future regression that drifts
        // the (UnquoteForm variant, QuoteForm variant) pairing
        // (e.g., a future arm that maps `UnquoteForm::Splice →
        // QuoteForm::Unquote`) fails this assertion without depending
        // on the FromStr decoder sitting between the two.
        use crate::ast::QuoteForm;
        for uf in UnquoteForm::ALL {
            assert_eq!(
                uf.to_quote_form().as_unquote_form(),
                Some(uf),
                "UnquoteForm::{uf:?} → QuoteForm via to_quote_form does not invert through QuoteForm::as_unquote_form — the 2-of-4 subset projection is no longer a section",
            );
        }

        // Per-arm pinning of the canonical mapping (the byte-for-byte
        // pairing the composition `marker == to_quote_form().prefix()`
        // depends on).
        assert_eq!(UnquoteForm::Unquote.to_quote_form(), QuoteForm::Unquote);
        assert_eq!(
            UnquoteForm::Splice.to_quote_form(),
            QuoteForm::UnquoteSplice
        );
    }

    #[test]
    fn unquote_form_marker_routes_through_to_quote_form_prefix_via_composition() {
        // Post-lift composition pin: for every `uf: UnquoteForm`,
        // `uf.marker()` and `uf.to_quote_form().prefix()` agree on
        // BOTH axes — (a) byte equality (the rendered diagnostic
        // literal cannot drift between the two projections); (b)
        // pointer equality (the canonical `&'static str` literal lives
        // at ONE site — `QuoteForm::prefix`'s Unquote/UnquoteSplice
        // arms in `ast.rs` — and `UnquoteForm::marker` routes through
        // that ONE address via the typed composition).
        //
        // The pointer-equality axis is load-bearing: a regression that
        // re-inlines the literals at `UnquoteForm::marker` as a
        // parallel match-table fails the pointer pin even when the
        // rendered bytes still agree (the inline-literal-table copy
        // lives at a different `&'static str` address — rustc may
        // de-duplicate identical literals within a single Rust
        // compilation unit, but the contract this test pins is
        // routing-through-the-canonical-site, not deduplication-by-the-
        // optimizer; a future build flag that disables literal dedup
        // would unmask the regression that the bytes-only assertion
        // misses). Sibling-shape pin to commit 1db697f's
        // `atom_kind_label_routes_through_sexp_shape_label_via_sexp_shape_projection`
        // — both pin the subset's projection through the superset's
        // canonical site via pointer-equality, the structural invariant
        // the subset-to-superset composition was lifted to make
        // load-bearing on the type system rather than on per-callsite
        // discipline.
        for uf in UnquoteForm::ALL {
            let from_marker = uf.marker();
            let from_composition = uf.to_quote_form().prefix();
            assert_eq!(
                from_marker, from_composition,
                "UnquoteForm::{uf:?}.marker() bytes drifted from .to_quote_form().prefix() bytes — the subset's diagnostic vocabulary is no longer derived from the superset's canonical site",
            );
            assert!(
                std::ptr::eq(from_marker.as_ptr(), from_composition.as_ptr()),
                "UnquoteForm::{uf:?}.marker() and .to_quote_form().prefix() disagree on `&'static str` address — pointer drift means the lift composes through a parallel literal table rather than routing into the canonical QuoteForm::prefix site",
            );
        }
    }

    #[test]
    fn unquote_form_per_role_markers_alias_quote_form_per_role_prefixes_byte_for_byte() {
        // ALIAS CONTRACT: pin both per-role `pub const UnquoteForm::*_MARKER`
        // aliases equal the corresponding `pub const QuoteForm::*_PREFIX`
        // byte-for-byte — so the UnquoteForm ⊂ QuoteForm marker-vocabulary
        // containment routes through the typed
        // `pub const UnquoteForm::V_MARKER: &'static str = QuoteForm::V_PREFIX`
        // alias chain rather than through two independent literal-discipline
        // sites. A regression that renames the QuoteForm side without
        // updating the UnquoteForm alias pointing at it fails-loudly here
        // with the exact axis identified (UNQUOTE / SPLICE); a regression
        // that re-inlines the UnquoteForm constant to a fresh literal still
        // passes this pin but loses the alias-chain typing (which is what
        // `unquote_form_marker_arms_route_through_per_role_markers_for_every_variant`
        // + `unquote_form_markers_align_with_all_by_index` catch in
        // combination).
        //
        // Sibling posture to
        // `atom_kind_per_role_labels_alias_sexp_shape_per_role_labels_byte_for_byte`
        // (commit fc126b8): both pin the invariant that a typed-subset
        // enum's per-role bytes are structurally derived from the parent
        // superset's per-role bytes via a `pub const = Parent::CONST`
        // alias rather than through parallel literal tables. The subset
        // there is AtomKind ⊂ SexpShape (6-of-12 on the atomic-payload
        // axis); the subset here is UnquoteForm ⊂ QuoteForm (2-of-4 on
        // the template-substitution axis) — both are load-bearing
        // structural carvings whose per-role vocabularies MUST agree
        // byte-for-byte with their parent's.
        use crate::ast::QuoteForm;
        assert_eq!(UnquoteForm::UNQUOTE_MARKER, QuoteForm::UNQUOTE_PREFIX);
        assert_eq!(UnquoteForm::SPLICE_MARKER, QuoteForm::UNQUOTE_SPLICE_PREFIX);
    }

    #[test]
    fn unquote_form_marker_arms_route_through_per_role_markers_for_every_variant() {
        // PATH-UNIFORMITY: `UnquoteForm::V.marker()` MUST equal the
        // per-role `pub const UnquoteForm::V_MARKER` for every
        // `v: UnquoteForm`. Pre-lift the two template-marker bytes
        // were reachable through `UnquoteForm::marker` (the composition
        // `self.to_quote_form().prefix()` — routing into
        // `QuoteForm::UNQUOTE_PREFIX` / `UNQUOTE_SPLICE_PREFIX`) OR
        // through direct `QuoteForm::UNQUOTE_PREFIX` reach-across;
        // post-lift each variant's canonical bytes are reachable
        // through the per-role `UnquoteForm::*_MARKER` alias too. Pin
        // the byte-equality between the runtime projection and the
        // compile-time alias so a regression that renames the alias
        // without updating the arm (or vice versa) fails-loudly at
        // the exact axis.
        //
        // Sibling-shape pin to
        // `atom_kind_label_arms_route_through_per_role_labels_for_every_variant`
        // one algebra layer over — the AtomKind subset algebra's per-
        // role aliases are pinned against `AtomKind::label`'s
        // composition-routed arms there; this pin binds the
        // UnquoteForm subset algebra's per-role aliases against
        // `UnquoteForm::marker`'s composition-routed arms so the two
        // template-marker bytes project through ONE aliased typed
        // source of truth per role rather than through per-consumer
        // inline literals.
        assert_eq!(UnquoteForm::Unquote.marker(), UnquoteForm::UNQUOTE_MARKER);
        assert_eq!(UnquoteForm::Splice.marker(), UnquoteForm::SPLICE_MARKER);
    }

    #[test]
    fn unquote_form_markers_has_expected_cardinality() {
        // Cardinality pin: `MARKERS.len() == 2` matches `ALL.len()` so
        // a refactor that loosens the type to `&'static [&'static str]`
        // fails HERE (the `[_; 2]` slot cannot be sliced silently),
        // and a variant added to `ALL` without a matching `MARKERS`
        // row fails the pair-arity gate at the array literal itself
        // before this test even runs. The pin doubles as an operator-
        // visible mark of the family's cardinality across the
        // substrate — two template markers, matching the 2-of-4
        // carving of the parent `QuoteForm::PREFIXES` (the
        // substitution-subset of the four canonical homoiconic prefix
        // bytes).
        assert_eq!(UnquoteForm::MARKERS.len(), 2);
        assert_eq!(UnquoteForm::MARKERS.len(), UnquoteForm::ALL.len());
    }

    #[test]
    fn unquote_form_markers_align_with_all_by_index() {
        // ALIGNMENT PIN: sweep `MARKERS[i] == ALL[i].marker()` so any
        // `zip(ALL, MARKERS)` consumer reads a coherent (variant,
        // marker) pair off ONE forced-arity array pair. The
        // declaration-order pin makes a family-wide consumer that
        // walks the ALL / MARKERS pair in lockstep (an LSP completion
        // bar keyed on `UnquoteForm::MARKERS`, a Sekiban metric
        // emitter labeling
        // `tatara_lisp_unbound_template_var_total{prefix}` by the
        // per-index marker) read one canonical (variant, bytes) pair
        // per slot rather than routing through per-consumer paired-
        // iteration. A regression that reorders MARKERS without also
        // reordering ALL (or vice versa) fails-loudly at the exact
        // index that drifted.
        assert_eq!(UnquoteForm::MARKERS.len(), UnquoteForm::ALL.len());
        for (i, form) in UnquoteForm::ALL.iter().enumerate() {
            assert_eq!(
                UnquoteForm::MARKERS[i],
                form.marker(),
                "UnquoteForm::MARKERS[{i}] `{mkr}` drifted from \
                 UnquoteForm::ALL[{i}].marker() `{via_variant}` — the \
                 canonical ALL ordering and the MARKERS ordering must \
                 match element-wise",
                mkr = UnquoteForm::MARKERS[i],
                via_variant = form.marker(),
            );
        }
    }

    #[test]
    fn unquote_form_markers_pairwise_distinct() {
        // 2x2 pairwise sweep so a collision between the two markers
        // (which would silently degrade two distinct template-
        // substitution markers to the SAME diagnostic bytes and
        // violate the closed-set FromStr round-trip) fails-loudly at
        // the exact pair. Distinctness is already enforced
        // structurally by `assert_closed_set_well_formed::<UnquoteForm>()`
        // (clause 3), so this pin is a secondary guard focused on the
        // per-role `pub const` surface directly rather than the
        // runtime projection through the trait's default `labels()`.
        for (i, a) in UnquoteForm::MARKERS.iter().enumerate() {
            for (j, b) in UnquoteForm::MARKERS.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "UnquoteForm::MARKERS[{i}] ({a:?}) collides with \
                     UnquoteForm::MARKERS[{j}] ({b:?}) — two distinct \
                     template markers cannot share diagnostic bytes",
                );
            }
        }
    }

    #[test]
    fn unquote_form_unquote_lead_aliases_quote_form_unquote_lead_byte_for_byte() {
        // ALIAS CONTRACT: pin the sole per-role
        // `pub const UnquoteForm::UNQUOTE_LEAD` alias equals
        // `pub const QuoteForm::UNQUOTE_LEAD` byte-for-byte — so the
        // UnquoteForm ⊂ QuoteForm reader-lead-char vocabulary
        // containment routes through the typed
        // `pub const UnquoteForm::UNQUOTE_LEAD: char =
        // QuoteForm::UNQUOTE_LEAD` alias chain rather than through an
        // independent literal-discipline site. A regression that
        // renames the QuoteForm side (a hypothetical repartitioning
        // that swaps the substitution-family lead byte from `,` to a
        // different char) without updating the UnquoteForm alias
        // pointing at it fails-loudly here; a regression that re-
        // inlines the UnquoteForm constant to a fresh `','` literal
        // still passes this pin but loses the alias-chain typing
        // (which is what the routing pin below catches in
        // combination).
        //
        // Sibling posture to
        // `unquote_form_per_role_markers_alias_quote_form_per_role_prefixes_byte_for_byte`
        // (commit 3640f76 — reader-punctuation-prefix axis),
        // `unquote_form_per_role_iac_forge_tags_alias_quote_form_per_role_iac_forge_tags_byte_for_byte`
        // (commit 6acab84 — iac-forge canonical-form axis),
        // `unquote_form_per_role_labels_alias_quote_form_per_role_labels_byte_for_byte`
        // (commit da68af5 — diagnostic-label axis), and
        // `unquote_form_per_role_hash_discriminators_alias_quote_form_per_role_hash_discriminators_byte_for_byte`
        // (commit eca4730 — outer-`Sexp` cache-key axis) — this
        // FIFTH alias-contract pin closes the QUINTUPLE of per-role
        // `pub const` axes on the UnquoteForm subset carving.
        assert_eq!(
            UnquoteForm::UNQUOTE_LEAD,
            crate::ast::QuoteForm::UNQUOTE_LEAD,
            "UnquoteForm::UNQUOTE_LEAD drifted from QuoteForm::UNQUOTE_LEAD — the alias chain broke",
        );
    }

    #[test]
    fn unquote_form_unquote_lead_pins_canonical_reader_lead_char() {
        // Byte-for-byte pin of the canonical
        // (UnquoteForm, reader-lead char) mapping at the per-role
        // `pub const` axis: `UnquoteForm::UNQUOTE_LEAD == ','` — the
        // exact char the reader's outer tokenizer dispatch selects
        // template-substitution-family entry on. This char is
        // load-bearing: the reader's outer tokenizer pre-check
        // (`QuoteForm::from_lead_char(ch)`) routes into the
        // substitution-family branch iff `ch == UNQUOTE_LEAD`, and
        // the `,`-vs-`,@` disambiguation lives at the reader's
        // peek-then-consume `@` second-char step (promoting the
        // default `Unquote` return into a `Splice` on `@`). A
        // regression that drifts this const from `,` silently
        // fractures the reader's outer dispatch AND the
        // `PROMOTIONS[0].1 == UNQUOTE_LEAD.next_char_promoter_source`
        // structural pairing that the promotion table binds to.
        // Sibling of
        // `unquote_form_per_role_hash_discriminators_pin_legacy_cache_key_bytes`
        // (which pins the outer-`Sexp` cache-key bytes at the
        // per-role `pub const` axis) — this test pins the reader-
        // lead char on the same axis one production vocabulary over.
        assert_eq!(
            UnquoteForm::UNQUOTE_LEAD,
            ',',
            "UnquoteForm::UNQUOTE_LEAD drifted from legacy reader-lead char ','",
        );
    }

    #[test]
    fn unquote_form_unquote_lead_routes_through_to_quote_form_lead_char_via_composition() {
        // Post-lift composition pin: for every `uf: UnquoteForm`,
        // `UnquoteForm::UNQUOTE_LEAD` and
        // `uf.to_quote_form().lead_char()` agree byte-for-byte — the
        // (subset marker, reader-lead char) pairing rides through the
        // superset's canonical `QuoteForm::lead_char` closed-set
        // match rather than through a parallel two-arm inline table
        // on the subset. A regression that re-inlines the two arms
        // as a parallel match-table (e.g. a future edit that spells
        // `Self::Unquote => ',' / Self::Splice => ','` directly at
        // `UnquoteForm::lead_char` instead of routing through
        // `self.to_quote_form().lead_char()`) is caught here — both
        // subset variants project to the SAME parent-superset lead
        // byte at
        // [`crate::ast::QuoteForm::lead_char`]'s
        // `Self::Unquote | Self::UnquoteSplice => Self::UNQUOTE_LEAD`
        // MERGED arm, and this composition pin binds that merge on
        // the subset carving. Sibling-shape pin to the four prior-
        // lift composition pins on `UnquoteForm`:
        // `unquote_form_marker_routes_through_to_quote_form_prefix_via_composition`,
        // `unquote_form_iac_forge_tag_routes_through_to_quote_form_iac_forge_tag_via_composition`,
        // `unquote_form_label_routes_through_to_quote_form_label_via_composition`,
        // and
        // `unquote_form_hash_discriminator_routes_through_to_quote_form_hash_discriminator_via_composition`
        // — all five pin the subset's projection through the
        // superset's canonical site via the same typed composition
        // posture. The FIFTH composition-through-`to_quote_form`
        // axis on the substitution-subset closed set is now load-
        // bearing on the type system.
        for uf in UnquoteForm::ALL {
            let via_composition = uf.to_quote_form().lead_char();
            assert_eq!(
                UnquoteForm::UNQUOTE_LEAD, via_composition,
                "UnquoteForm::{uf:?} projects through .to_quote_form().lead_char() = `{via_composition}` — but UnquoteForm::UNQUOTE_LEAD = `{}` — the SHAPE-ASYMMETRIC-COLLAPSE identity (both subset arms → one lead byte) broke",
                UnquoteForm::UNQUOTE_LEAD,
            );
        }
    }

    #[test]
    fn unquote_form_leads_has_expected_shape_asymmetric_cardinality() {
        // Cardinality pin: `LEADS.len() == 1` — the SHAPE-ASYMMETRIC-
        // COLLAPSE cardinality that IS the collapse witness on the
        // 2-of-4 subset carving. UnquoteForm has 2 arms
        // (`Self::ALL.len() == 2`), but both arms share the same
        // reader-lead byte `,`, so the distinct-lead-byte closed-set
        // ALL array collapses to `[char; 1]`. The cardinality gap
        // `Self::ALL.len() (== 2) - Self::LEADS.len() (== 1) == 1`
        // IS the shared-lead-char invariant carried at the type-
        // system level.
        //
        // Peer to `unquote_form_markers_has_expected_cardinality`
        // (which pins `MARKERS.len() == 2 == ALL.len()` — the
        // arm-per-arm axis has NO collapse), this test pins the
        // OPPOSITE `LEADS.len() == 1 < ALL.len()` invariant — the
        // distinct-lead-set axis DOES collapse. The two axes together
        // fully characterize the reader-vocabulary shape on the
        // UnquoteForm closed set.
        //
        // Peer to `quote_form_leads_has_expected_shape_asymmetric_cardinality`
        // (parent 4-of-4 carving pins `QuoteForm::LEADS.len() == 3`
        // for 4 arms — the same shared-lead-byte collapse identity
        // one algebra level up).
        assert_eq!(
            UnquoteForm::LEADS.len(),
            1,
            "UnquoteForm::LEADS cardinality drifted from 1 — the shared-lead-char collapse invariant on the 2-of-4 substitution-subset carving is broken",
        );
        assert!(
            UnquoteForm::LEADS.len() < UnquoteForm::ALL.len(),
            "UnquoteForm::LEADS.len() ({leads}) MUST be strictly less than UnquoteForm::ALL.len() ({all}) — the SHAPE-ASYMMETRIC-COLLAPSE identity requires a strict cardinality gap",
            leads = UnquoteForm::LEADS.len(),
            all = UnquoteForm::ALL.len(),
        );
    }

    #[test]
    fn unquote_form_leads_covers_all_variants_via_to_quote_form_lead_char() {
        // COVERAGE pin: every UnquoteForm variant's reader-lead byte
        // (projected through the superset composition
        // `self.to_quote_form().lead_char()`) MUST appear in
        // `UnquoteForm::LEADS`. Combined with the cardinality pin
        // above (`LEADS.len() == 1`), this pins that `LEADS` is
        // EXACTLY the image of `ALL` under the composition — no
        // superfluous entries, no missing coverage. A regression
        // that adds a spurious char to `LEADS` (e.g. a future edit
        // that includes both `,` and `@` in the array under the
        // mistaken belief that `,@` is a separate lead byte) fails
        // the cardinality pin above; a regression that DROPS the
        // sole entry from `LEADS` fails this coverage pin at every
        // variant.
        for uf in UnquoteForm::ALL {
            let lead = uf.to_quote_form().lead_char();
            assert!(
                UnquoteForm::LEADS.contains(&lead),
                "UnquoteForm::{uf:?} projects through .to_quote_form().lead_char() = `{lead}` — but UnquoteForm::LEADS ({leads:?}) does NOT contain `{lead}`; the distinct-lead-byte ALL array must cover every variant's lead byte",
                leads = UnquoteForm::LEADS,
            );
        }
    }

    #[test]
    fn unquote_form_leads_is_subset_of_quote_form_leads() {
        // CONTAINMENT pin: `UnquoteForm::LEADS` is a subset of
        // `QuoteForm::LEADS` — the substitution-subset carving's
        // reader-lead-byte set sits inside the parent QuoteForm
        // superset's reader-lead-byte set by the UnquoteForm ⊂
        // QuoteForm inclusion. The sole entry `UnquoteForm::LEADS[0]
        // == ','` must equal `QuoteForm::UNQUOTE_LEAD`, which IS the
        // third entry `QuoteForm::LEADS[2]` (Quote/Quasiquote/Unquote
        // in declaration order per `QuoteForm::LEADS`). A regression
        // that drifts `UnquoteForm::UNQUOTE_LEAD` out of alignment
        // with the parent (e.g. a future edit that inlines a fresh
        // `';'` literal into the UnquoteForm alias but leaves
        // QuoteForm's canonical byte at `','`) fails-loudly here.
        // Sibling of
        // `unquote_form_hash_discriminator_partitions_disjointly_from_non_substitution_carvings`
        // (which pins the cache-key axis's partition-membership on
        // the same subset carving) — this test pins the reader-lead-
        // byte axis's subset-membership one production vocabulary
        // over.
        use crate::ast::QuoteForm;
        for lead in UnquoteForm::LEADS {
            assert!(
                QuoteForm::LEADS.contains(&lead),
                "UnquoteForm::LEADS entry `{lead}` MUST appear in QuoteForm::LEADS ({parent:?}) — the UnquoteForm ⊂ QuoteForm subset-inclusion breaks otherwise",
                parent = QuoteForm::LEADS,
            );
        }
    }

    #[test]
    fn unquote_form_leads_matches_to_quote_form_lead_char_image_exactly() {
        // EXACT-IMAGE pin: `UnquoteForm::LEADS` as an unordered set
        // equals the image of `UnquoteForm::ALL` under
        // `.to_quote_form().lead_char()`. Combined with the
        // cardinality pin (`LEADS.len() == 1`) and the coverage pin
        // (every variant's lead appears in LEADS), this ties LEADS
        // to the composition's image at the SET level — a regression
        // that reorders entries, adds duplicates, or drops entries
        // fails at exactly one of the three pins.
        use std::collections::HashSet;
        let leads_set: HashSet<char> = UnquoteForm::LEADS.iter().copied().collect();
        let image_set: HashSet<char> = UnquoteForm::ALL
            .iter()
            .map(|uf| uf.to_quote_form().lead_char())
            .collect();
        assert_eq!(
            leads_set, image_set,
            "UnquoteForm::LEADS ({leads_set:?}) as a set MUST equal the image of UnquoteForm::ALL under .to_quote_form().lead_char() ({image_set:?}) — the distinct-lead-byte closed-set ALL array drifted from its composition source",
        );
    }

    #[test]
    fn unquote_form_per_role_iac_forge_tags_alias_quote_form_per_role_iac_forge_tags_byte_for_byte()
    {
        // ALIAS CONTRACT: pin both per-role
        // `pub const UnquoteForm::*_IAC_FORGE_TAG` aliases equal the
        // corresponding `pub const QuoteForm::*_IAC_FORGE_TAG`
        // byte-for-byte — so the UnquoteForm ⊂ QuoteForm iac-forge-
        // canonical-form vocabulary containment routes through the
        // typed
        // `pub const UnquoteForm::V_IAC_FORGE_TAG: &'static str = QuoteForm::V_IAC_FORGE_TAG`
        // alias chain rather than through two independent literal-
        // discipline sites. A regression that renames the QuoteForm
        // side (e.g. a Common-Lisp-standard rename of `"unquote-
        // splicing"` on the iac-forge canonical-form surface) without
        // updating the UnquoteForm alias pointing at it fails-loudly
        // here with the exact axis identified (UNQUOTE / SPLICE); a
        // regression that re-inlines the UnquoteForm constant to a
        // fresh literal still passes this pin but loses the alias-
        // chain typing (which is what
        // `unquote_form_iac_forge_tag_arms_route_through_per_role_iac_forge_tags_for_every_variant`
        // + `unquote_form_iac_forge_tags_align_with_all_by_index`
        // catch in combination).
        //
        // Sibling posture to
        // `unquote_form_per_role_markers_alias_quote_form_per_role_prefixes_byte_for_byte`
        // (commit 3640f76): both pin the invariant that the
        // UnquoteForm subset algebra's per-role bytes are structurally
        // derived from the parent QuoteForm superset's per-role bytes
        // via a `pub const = Parent::CONST` alias rather than through
        // parallel literal tables — the axis there is the reader-
        // punctuation vocabulary; the axis here is the iac-forge
        // canonical-form vocabulary. Both axes span the two production
        // byte-vocabularies the parent [`QuoteForm`] closed set
        // carries, and both bind through the same aliased typed source
        // of truth on this UnquoteForm subset.
        use crate::ast::QuoteForm;
        assert_eq!(
            UnquoteForm::UNQUOTE_IAC_FORGE_TAG,
            QuoteForm::UNQUOTE_IAC_FORGE_TAG,
        );
        assert_eq!(
            UnquoteForm::SPLICE_IAC_FORGE_TAG,
            QuoteForm::UNQUOTE_SPLICE_IAC_FORGE_TAG,
        );
    }

    #[test]
    fn unquote_form_iac_forge_tag_arms_route_through_per_role_iac_forge_tags_for_every_variant() {
        // PATH-UNIFORMITY: `UnquoteForm::V.iac_forge_tag()` MUST equal
        // the per-role `pub const UnquoteForm::V_IAC_FORGE_TAG` for
        // every `v: UnquoteForm`. Pre-lift the two iac-forge canonical-
        // form tag bytes were reachable through
        // `UnquoteForm::iac_forge_tag` (the composition
        // `self.to_quote_form().iac_forge_tag()` — routing into
        // `QuoteForm::UNQUOTE_IAC_FORGE_TAG` /
        // `UNQUOTE_SPLICE_IAC_FORGE_TAG`) OR through direct
        // `QuoteForm::UNQUOTE_IAC_FORGE_TAG` reach-across; post-lift
        // each variant's canonical bytes are reachable through the
        // per-role `UnquoteForm::*_IAC_FORGE_TAG` alias too. Pin the
        // byte-equality between the runtime projection and the
        // compile-time alias so a regression that renames the alias
        // without updating the arm (or vice versa) fails-loudly at the
        // exact axis.
        //
        // Sibling-shape pin to
        // `unquote_form_marker_arms_route_through_per_role_markers_for_every_variant`
        // one vocabulary over on the SAME subset algebra — the reader-
        // punctuation axis is pinned there; the iac-forge canonical-
        // form axis is pinned here. Together the two pins close the
        // subset algebra's `pub const *_MARKER` + `pub const
        // *_IAC_FORGE_TAG` surfaces against the runtime projections
        // that feed the two production byte-vocabularies.
        assert_eq!(
            UnquoteForm::Unquote.iac_forge_tag(),
            UnquoteForm::UNQUOTE_IAC_FORGE_TAG,
        );
        assert_eq!(
            UnquoteForm::Splice.iac_forge_tag(),
            UnquoteForm::SPLICE_IAC_FORGE_TAG,
        );
    }

    #[test]
    fn unquote_form_iac_forge_tags_has_expected_cardinality() {
        // Cardinality pin: `IAC_FORGE_TAGS.len() == 2` matches
        // `ALL.len()` so a refactor that loosens the type to
        // `&'static [&'static str]` fails HERE (the `[_; 2]` slot
        // cannot be sliced silently), and a variant added to `ALL`
        // without a matching `IAC_FORGE_TAGS` row fails the pair-arity
        // gate at the array literal itself before this test even runs.
        // The pin doubles as an operator-visible mark of the family's
        // cardinality across the substrate — two iac-forge tags,
        // matching the 2-of-4 carving of the parent
        // `QuoteForm::IAC_FORGE_TAGS` (the substitution-subset of the
        // four canonical homoiconic canonical-form tag strings).
        assert_eq!(UnquoteForm::IAC_FORGE_TAGS.len(), 2);
        assert_eq!(UnquoteForm::IAC_FORGE_TAGS.len(), UnquoteForm::ALL.len(),);
    }

    #[test]
    fn unquote_form_iac_forge_tags_align_with_all_by_index() {
        // ALIGNMENT PIN: sweep `IAC_FORGE_TAGS[i] ==
        // ALL[i].iac_forge_tag()` so any `zip(ALL, IAC_FORGE_TAGS)`
        // consumer reads a coherent (variant, iac-forge tag) pair off
        // ONE forced-arity array pair. The declaration-order pin
        // makes a family-wide consumer that walks the
        // ALL / IAC_FORGE_TAGS pair in lockstep (an LSP completion
        // bar keyed on `UnquoteForm::IAC_FORGE_TAGS`, a Sekiban
        // audit-trail metric labeling
        // `tatara_lisp_iac_forge_tag_total{tag}` by the per-index
        // iac-forge tag) read one canonical (variant, bytes) pair per
        // slot rather than routing through per-consumer paired-
        // iteration. A regression that reorders IAC_FORGE_TAGS without
        // also reordering ALL (or vice versa) fails-loudly at the
        // exact index that drifted.
        assert_eq!(UnquoteForm::IAC_FORGE_TAGS.len(), UnquoteForm::ALL.len(),);
        for (i, form) in UnquoteForm::ALL.iter().enumerate() {
            assert_eq!(
                UnquoteForm::IAC_FORGE_TAGS[i],
                form.iac_forge_tag(),
                "UnquoteForm::IAC_FORGE_TAGS[{i}] `{tag}` drifted \
                 from UnquoteForm::ALL[{i}].iac_forge_tag() \
                 `{via_variant}` — the canonical ALL ordering and \
                 the IAC_FORGE_TAGS ordering must match element-wise",
                tag = UnquoteForm::IAC_FORGE_TAGS[i],
                via_variant = form.iac_forge_tag(),
            );
        }
    }

    #[test]
    fn unquote_form_iac_forge_tags_pairwise_distinct() {
        // 2x2 pairwise sweep so a collision between the two iac-forge
        // canonical-form tags (which would silently degrade two
        // distinct template-substitution markers to the SAME cross-
        // crate canonical-form bytes and mis-hash the substrate's
        // BLAKE3 attestation intent-hash pillar) fails-loudly at the
        // exact pair. Sibling-shape pin to
        // `unquote_form_markers_pairwise_distinct` one vocabulary over
        // on the SAME subset algebra — the reader-punctuation axis is
        // pinned there; the iac-forge canonical-form axis is pinned
        // here.
        for (i, a) in UnquoteForm::IAC_FORGE_TAGS.iter().enumerate() {
            for (j, b) in UnquoteForm::IAC_FORGE_TAGS.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "UnquoteForm::IAC_FORGE_TAGS[{i}] ({a:?}) \
                     collides with UnquoteForm::IAC_FORGE_TAGS[{j}] \
                     ({b:?}) — two distinct template markers cannot \
                     share cross-crate canonical-form bytes",
                );
            }
        }
    }

    #[test]
    fn unquote_form_label_routes_through_to_quote_form_label_via_composition() {
        // Post-lift composition pin: for every `uf: UnquoteForm`,
        // `uf.label()` and `uf.to_quote_form().label()` agree on BOTH
        // axes — (a) byte equality (the rendered diagnostic literal
        // cannot drift between the two projections); (b) pointer
        // equality (the canonical `&'static str` literal lives at ONE
        // site — `SexpShape::UNQUOTE_LABEL` /
        // `SexpShape::UNQUOTE_SPLICE_LABEL` — reached through
        // `QuoteForm::label`'s composition through
        // `sexp_shape().label()`, and `UnquoteForm::label` routes
        // through that ONE address via the two-hop typed composition
        // `to_quote_form().label()`).
        //
        // The pointer-equality axis is load-bearing: a regression that
        // re-inlines the literals at `UnquoteForm::label` as a
        // parallel match-table fails the pointer pin even when the
        // rendered bytes still agree (the inline-literal-table copy
        // lives at a different `&'static str` address). Sibling-shape
        // pin to
        // `unquote_form_marker_routes_through_to_quote_form_prefix_via_composition`
        // and
        // `unquote_form_iac_forge_tag_routes_through_to_quote_form_iac_forge_tag_via_composition`
        // — this closes the THIRD composition-through-`to_quote_form`
        // per-role-bytes projection on the subset algebra pinned
        // against the superset's canonical site.
        for uf in UnquoteForm::ALL {
            let from_label = uf.label();
            let from_composition = uf.to_quote_form().label();
            assert_eq!(
                from_label, from_composition,
                "UnquoteForm::{uf:?}.label() bytes drifted from .to_quote_form().label() bytes — the subset's diagnostic vocabulary is no longer derived from the superset's canonical site",
            );
            assert!(
                std::ptr::eq(from_label.as_ptr(), from_composition.as_ptr()),
                "UnquoteForm::{uf:?}.label() and .to_quote_form().label() disagree on `&'static str` address — pointer drift means the lift composes through a parallel literal table rather than routing into the canonical QuoteForm::label / SexpShape::*_LABEL site",
            );
        }
    }

    #[test]
    fn unquote_form_per_role_labels_alias_quote_form_per_role_labels_byte_for_byte() {
        // ALIAS CONTRACT: pin both per-role
        // `pub const UnquoteForm::*_LABEL` aliases equal the
        // corresponding `pub const QuoteForm::*_LABEL` byte-for-byte
        // — so the UnquoteForm ⊂ QuoteForm diagnostic-label
        // vocabulary containment routes through the typed
        // `pub const UnquoteForm::V_LABEL: &'static str = QuoteForm::V_LABEL`
        // alias chain (which itself aliases the ultimate canonical
        // site at `SexpShape::*_LABEL`) rather than through two
        // independent literal-discipline sites. A regression that
        // renames the QuoteForm side without updating the UnquoteForm
        // alias pointing at it fails-loudly here with the exact axis
        // identified (UNQUOTE / SPLICE); a regression that re-inlines
        // the UnquoteForm constant to a fresh literal still passes
        // this pin but loses the alias-chain typing (which is what
        // `unquote_form_label_arms_route_through_per_role_labels_for_every_variant`
        // + `unquote_form_labels_align_with_all_by_index` catch in
        // combination).
        //
        // Sibling posture to
        // `unquote_form_per_role_markers_alias_quote_form_per_role_prefixes_byte_for_byte`
        // (commit 3640f76) and
        // `unquote_form_per_role_iac_forge_tags_alias_quote_form_per_role_iac_forge_tags_byte_for_byte`
        // (commit 6acab84): all three pin the invariant that the
        // UnquoteForm subset algebra's per-role bytes are structurally
        // derived from the parent QuoteForm superset's per-role bytes
        // via a `pub const = Parent::CONST` alias rather than through
        // parallel literal tables — the axis there is the reader-
        // punctuation vocabulary and the iac-forge canonical-form
        // vocabulary; the axis here is the substrate diagnostic-label
        // vocabulary. All three axes span the THREE production byte-
        // vocabularies the parent [`QuoteForm`] closed set carries,
        // and all three bind through the same aliased typed source of
        // truth on this UnquoteForm subset.
        use crate::ast::QuoteForm;
        assert_eq!(UnquoteForm::UNQUOTE_LABEL, QuoteForm::UNQUOTE_LABEL);
        assert_eq!(UnquoteForm::SPLICE_LABEL, QuoteForm::UNQUOTE_SPLICE_LABEL);
    }

    #[test]
    fn unquote_form_label_arms_route_through_per_role_labels_for_every_variant() {
        // PATH-UNIFORMITY: `UnquoteForm::V.label()` MUST equal the
        // per-role `pub const UnquoteForm::V_LABEL` for every
        // `v: UnquoteForm`. Pre-lift the two diagnostic-label bytes
        // were reachable through the two-step composition
        // `uf.to_quote_form().label()` OR through direct
        // `QuoteForm::UNQUOTE_LABEL` reach-across; post-lift each
        // variant's canonical bytes are reachable through the per-
        // role `UnquoteForm::*_LABEL` alias AND through the inherent
        // `label()` method too. Pin the byte-equality between the
        // runtime projection and the compile-time alias so a
        // regression that renames the alias without updating the arm
        // (or vice versa) fails-loudly at the exact axis.
        //
        // Sibling-shape pin to
        // `unquote_form_marker_arms_route_through_per_role_markers_for_every_variant`
        // and
        // `unquote_form_iac_forge_tag_arms_route_through_per_role_iac_forge_tags_for_every_variant`
        // one vocabulary over on the SAME subset algebra — together
        // the three pins close the subset algebra's
        // `pub const *_MARKER` + `pub const *_IAC_FORGE_TAG` +
        // `pub const *_LABEL` surfaces against the runtime
        // projections that feed the three production byte-
        // vocabularies.
        assert_eq!(UnquoteForm::Unquote.label(), UnquoteForm::UNQUOTE_LABEL);
        assert_eq!(UnquoteForm::Splice.label(), UnquoteForm::SPLICE_LABEL);
    }

    #[test]
    fn unquote_form_labels_has_expected_cardinality() {
        // Cardinality pin: `LABELS.len() == 2` matches `ALL.len()` so
        // a refactor that loosens the type to `&'static [&'static str]`
        // fails HERE (the `[_; 2]` slot cannot be sliced silently),
        // and a variant added to `ALL` without a matching `LABELS`
        // row fails the pair-arity gate at the array literal itself
        // before this test even runs.
        assert_eq!(UnquoteForm::LABELS.len(), 2);
        assert_eq!(UnquoteForm::LABELS.len(), UnquoteForm::ALL.len());
    }

    #[test]
    fn unquote_form_labels_align_with_all_by_index() {
        // ALIGNMENT PIN: sweep `LABELS[i] == ALL[i].label()` so any
        // `zip(ALL, LABELS)` consumer reads a coherent (variant,
        // label) pair off ONE forced-arity array pair. A regression
        // that reorders LABELS without also reordering ALL (or vice
        // versa) fails-loudly at the exact index that drifted.
        assert_eq!(UnquoteForm::LABELS.len(), UnquoteForm::ALL.len());
        for (i, form) in UnquoteForm::ALL.iter().enumerate() {
            assert_eq!(
                UnquoteForm::LABELS[i],
                form.label(),
                "UnquoteForm::LABELS[{i}] `{lbl}` drifted from \
                 UnquoteForm::ALL[{i}].label() `{via_variant}` — the \
                 canonical ALL ordering and the LABELS ordering must \
                 match element-wise",
                lbl = UnquoteForm::LABELS[i],
                via_variant = form.label(),
            );
        }
    }

    #[test]
    fn unquote_form_labels_pairwise_distinct() {
        // 2x2 pairwise sweep so a collision between the two
        // diagnostic labels (which would silently degrade two distinct
        // template-substitution markers to the SAME operator-facing
        // rendered vocabulary) fails-loudly at the exact pair.
        // Sibling-shape pin to `unquote_form_markers_pairwise_distinct`
        // and `unquote_form_iac_forge_tags_pairwise_distinct` one
        // vocabulary over on the SAME subset algebra.
        for (i, a) in UnquoteForm::LABELS.iter().enumerate() {
            for (j, b) in UnquoteForm::LABELS.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "UnquoteForm::LABELS[{i}] ({a:?}) collides with \
                     UnquoteForm::LABELS[{j}] ({b:?}) — two distinct \
                     template markers cannot share diagnostic bytes",
                );
            }
        }
    }

    #[test]
    fn unquote_form_label_emits_canonical_sexp_shape_label_for_every_marker() {
        // Per-arm truth-table pin of the canonical (UnquoteForm
        // variant, diagnostic label) mapping: `UnquoteForm::Unquote →
        // "unquote"` and `UnquoteForm::Splice → "unquote-splice"`
        // byte-for-byte. The `-splice` short form on `Splice` is
        // load-bearing: the substrate diagnostic surface renders
        // `unquote-splice`, distinct from the iac-forge canonical
        // form's `unquote-splicing` — a regression that homogenizes
        // the two axes surfaces here on the diagnostic-surface side
        // (`unquote_form_iac_forge_tag_diverges_from_sexp_shape_label_at_splice_arm`
        // surfaces it on the iac-forge-surface side). Sibling of
        // `unquote_form_iac_forge_tag_emits_canonical_cl_tag_for_every_marker`
        // on the iac-forge axis rather than the diagnostic axis.
        assert_eq!(
            UnquoteForm::Unquote.label(),
            "unquote",
            "UnquoteForm::Unquote.label() drifted from canonical substrate 'unquote' diagnostic",
        );
        assert_eq!(
            UnquoteForm::Splice.label(),
            "unquote-splice",
            "UnquoteForm::Splice.label() drifted from canonical substrate 'unquote-splice' \
             diagnostic — the short form is load-bearing (distinct from iac-forge 'unquote-splicing')",
        );
    }

    #[test]
    fn unquote_form_label_diverges_from_iac_forge_tag_at_splice_arm() {
        // BOUNDARY-DISTINCT CONTRACT (subset peer): the diagnostic
        // label for `UnquoteForm::Splice` is `"unquote-splice"` (short
        // substrate form), distinct from `UnquoteForm::Splice.iac_forge_tag()`
        // which renders the longer `"unquote-splicing"` (Common-Lisp
        // canonical form). Pins the divergence on the substitution-
        // subset carving. On the non-`Splice` arm the two projections
        // MUST agree (both spell `"unquote"` at the substitution-
        // subset's `Unquote` arm). Peer of
        // `unquote_form_iac_forge_tag_diverges_from_sexp_shape_label_at_splice_arm`
        // one composition path over — that pin routes through
        // `sexp_shape().label()`; this pin routes through the direct
        // subset `label()` inherent (which composes through
        // `to_quote_form().label()`).
        assert_eq!(
            UnquoteForm::Unquote.label(),
            UnquoteForm::Unquote.iac_forge_tag(),
            "UnquoteForm::Unquote.label() and .iac_forge_tag() must agree on 'unquote' — the two axes only diverge at the Splice arm",
        );
        assert_ne!(
            UnquoteForm::Splice.label(),
            UnquoteForm::Splice.iac_forge_tag(),
            "UnquoteForm::Splice.label() and .iac_forge_tag() must diverge — substrate renders 'unquote-splice', iac-forge canonical form is 'unquote-splicing'",
        );
    }

    #[test]
    fn unquote_form_wrap_routes_through_to_quote_form_wrap_via_composition() {
        // Post-lift composition pin: for every `uf: UnquoteForm` and
        // every representative `inner: Sexp`, `uf.wrap(inner.clone())
        // == uf.to_quote_form().wrap(inner)` byte-for-byte. The
        // (UnquoteForm marker, `Sexp::*` tuple-variant constructor)
        // pairing on the substitution-subset closed set is derived
        // structurally from the superset's canonical
        // [`crate::ast::QuoteForm::wrap`] closed-set match rather than
        // from a parallel two-arm inline table on this subset. A
        // regression that re-inlines the two arms as a parallel
        // match-table (a future edit that spells `Self::Unquote =>
        // Sexp::Unquote(Box::new(inner))` / `Self::Splice =>
        // Sexp::UnquoteSplice(Box::new(inner))` directly at
        // `UnquoteForm::wrap` instead of routing through
        // `self.to_quote_form().wrap(inner)`) still passes the round-
        // trip and canonical-tuple-variant sweeps below but fails
        // THIS composition pin — the subset's construct-family
        // vocabulary is no longer derived from the superset's
        // canonical site. Sibling-shape pin to commit 250c001's
        // `unquote_form_marker_routes_through_to_quote_form_prefix_via_composition`:
        // both pin the subset's projection through the superset's
        // canonical site via structural equality, the invariant the
        // subset-to-superset composition was lifted to make load-
        // bearing on the type system rather than on per-callsite
        // discipline.
        use crate::ast::Sexp;
        let inners = [
            Sexp::Nil,
            Sexp::symbol("x"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(42),
            Sexp::float(1.5),
            Sexp::boolean(true),
            Sexp::List(vec![Sexp::symbol("f"), Sexp::int(1), Sexp::int(2)]),
        ];
        for uf in UnquoteForm::ALL {
            for inner in &inners {
                let via_wrap = uf.wrap(inner.clone());
                let via_composition = uf.to_quote_form().wrap(inner.clone());
                assert_eq!(
                    via_wrap, via_composition,
                    "UnquoteForm::{uf:?}.wrap(inner) drifted from .to_quote_form().wrap(inner) — the subset's construct vocabulary is no longer derived from the superset's canonical site",
                );
            }
        }
    }

    #[test]
    fn unquote_form_wrap_emits_canonical_tuple_variant_for_every_marker() {
        // Byte-for-byte tuple-variant emission pin: for every
        // `uf: UnquoteForm` and every representative `inner: Sexp`,
        // `uf.wrap(inner)` produces the canonical `Sexp::Unquote(
        // Box::new(inner))` / `Sexp::UnquoteSplice(Box::new(inner))`
        // shape byte-for-byte. Pins the (subset marker, `Sexp::*`
        // tuple-variant constructor) pairing at the observable
        // wrapper-shape boundary — a regression that maps
        // `UnquoteForm::Unquote → Sexp::UnquoteSplice` (a marker/
        // constructor swap that still routes through the superset's
        // `wrap`) surfaces here because the composition through
        // `to_quote_form()` picks up the swap at the subset-to-
        // superset projection. Sibling of the outer `Sexp` construct
        // family's
        // `sexp_quote_family_constructors_emit_canonical_tuple_variant_for_every_marker`
        // (commit 38f076b) — same posture on the subset closed set.
        use crate::ast::Sexp;
        let inners = [
            Sexp::Nil,
            Sexp::symbol("x"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(-7),
            Sexp::float(2.0),
            Sexp::boolean(false),
            Sexp::List(vec![Sexp::symbol("f"), Sexp::int(1)]),
        ];
        for inner in &inners {
            assert_eq!(
                UnquoteForm::Unquote.wrap(inner.clone()),
                Sexp::Unquote(Box::new(inner.clone())),
                "UnquoteForm::Unquote.wrap({inner:?}) drifted from Sexp::Unquote(Box::new({inner:?})) canonical tuple-variant shape",
            );
            assert_eq!(
                UnquoteForm::Splice.wrap(inner.clone()),
                Sexp::UnquoteSplice(Box::new(inner.clone())),
                "UnquoteForm::Splice.wrap({inner:?}) drifted from Sexp::UnquoteSplice(Box::new({inner:?})) canonical tuple-variant shape",
            );
        }
    }

    #[test]
    fn unquote_form_wrap_round_trips_through_sexp_as_unquote() {
        // Section-for-retraction pin: `uf.wrap(inner).as_unquote() ==
        // Some((uf, &inner))` for every `uf: UnquoteForm` and every
        // representative `inner: Sexp`. Closes the (construct,
        // project) algebra dual on the closed-set `UnquoteForm`
        // algebra — the substitution-subset peer of the closed-set
        // superset algebra's already-closed
        // ([`crate::ast::QuoteForm::wrap`],
        // [`crate::ast::Sexp::as_quote_form`]) dual. The typed
        // constructor + typed projection pair form an `Iso(inner,
        // Sexp::X_variant(inner))` on the subset closed set. A future
        // arm added to `UnquoteForm` extends [`UnquoteForm::ALL`] +
        // [`UnquoteForm::to_quote_form`] + this sweep in lockstep —
        // rustc-enforced through the closed-set exhaustiveness across
        // the `UnquoteForm` match. Sibling of the outer `Sexp`
        // construct family's
        // `sexp_quote_family_constructors_round_trip_through_as_quote_form`
        // (commit 38f076b) — same posture on the subset closed set,
        // routed through `Sexp::as_unquote` rather than
        // `Sexp::as_quote_form`.
        use crate::ast::Sexp;
        let inners = [
            Sexp::Nil,
            Sexp::symbol("x"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(1),
            Sexp::List(vec![Sexp::symbol("f")]),
        ];
        for uf in UnquoteForm::ALL {
            for inner in &inners {
                let wrapped = uf.wrap(inner.clone());
                assert_eq!(
                    wrapped.as_unquote(),
                    Some((uf, inner)),
                    "UnquoteForm::{uf:?}.wrap({inner:?}).as_unquote() failed to round-trip — the (construct, project) pair on the subset algebra is not a section-for-retraction of Sexp::as_unquote",
                );
            }
        }
    }

    #[test]
    fn unquote_form_wrap_composes_with_shape_via_to_quote_form_sexp_shape() {
        // Outer-shape composition pin: for every `uf: UnquoteForm`
        // and every representative `inner: Sexp`, `uf.wrap(inner)
        // .shape() == uf.to_quote_form().sexp_shape()` — the
        // (subset marker, outer [`crate::error::SexpShape`]) pairing
        // binds through the SAME closed-set composition
        // (`to_quote_form` → `QuoteForm::sexp_shape`) that
        // [`crate::ast::QuoteForm::wrap`]'s outer-shape composition
        // rides on. A regression that drifts ONE construct arm's
        // outer-shape from the superset's `sexp_shape` while
        // preserving the tuple-variant emission surfaces here
        // alongside the round-trip pin. Sibling of the outer `Sexp`
        // construct family's
        // `sexp_quote_family_constructors_compose_with_shape_via_quote_form_sexp_shape`
        // (commit 38f076b) — same posture on the subset closed set.
        use crate::ast::Sexp;
        let inners = [
            Sexp::Nil,
            Sexp::symbol("x"),
            Sexp::int(42),
            Sexp::List(vec![Sexp::symbol("f")]),
        ];
        for uf in UnquoteForm::ALL {
            for inner in &inners {
                assert_eq!(
                    uf.wrap(inner.clone()).shape(),
                    uf.to_quote_form().sexp_shape(),
                    "UnquoteForm::{uf:?}.wrap({inner:?}).shape() drifted from .to_quote_form().sexp_shape() — the (subset marker, outer SexpShape) pairing is no longer derived from the superset's canonical composition",
                );
            }
        }
    }

    #[test]
    fn unquote_form_sexp_shape_routes_through_to_quote_form_sexp_shape_via_composition() {
        // Post-lift composition pin: for every `uf: UnquoteForm`,
        // `uf.sexp_shape()` and `uf.to_quote_form().sexp_shape()`
        // agree byte-for-byte — the (subset marker, outer SexpShape)
        // pairing rides through the superset's canonical
        // `QuoteForm::sexp_shape` closed-set match rather than through
        // a parallel two-arm inline table on the subset. A regression
        // that re-inlines the two arms as a parallel match-table (e.g.
        // a future edit that spells `Self::Unquote => SexpShape::Unquote`
        // / `Self::Splice => SexpShape::UnquoteSplice` directly at
        // `UnquoteForm::sexp_shape` instead of routing through
        // `self.to_quote_form().sexp_shape()`) still passes the round-
        // trip sweep below but fails THIS composition pin — the
        // subset's outer-shape vocabulary is no longer derived from
        // the superset's canonical site. Sibling-shape pin to commit
        // 250c001's `unquote_form_marker_routes_through_to_quote_form_prefix_via_composition`
        // and commit 92daace's `unquote_form_wrap_routes_through_to_quote_form_wrap_via_composition`:
        // all three pin the subset's projection through the superset's
        // canonical site via the same typed composition posture, the
        // invariant the subset-to-superset composition was lifted to
        // make load-bearing on the type system rather than on
        // per-callsite discipline.
        for uf in UnquoteForm::ALL {
            let from_shape = uf.sexp_shape();
            let from_composition = uf.to_quote_form().sexp_shape();
            assert_eq!(
                from_shape, from_composition,
                "UnquoteForm::{uf:?}.sexp_shape() drifted from .to_quote_form().sexp_shape() — the subset's outer-shape vocabulary is no longer derived from the superset's canonical site",
            );
        }
    }

    #[test]
    fn unquote_form_sexp_shape_emits_canonical_shape_for_every_marker() {
        // Per-arm truth-table pin of the canonical (UnquoteForm variant,
        // SexpShape variant) mapping: `UnquoteForm::Unquote →
        // SexpShape::Unquote` and `UnquoteForm::Splice →
        // SexpShape::UnquoteSplice` byte-for-byte. A regression that
        // swaps the two arms (a marker/shape swap that still routes
        // through the superset's `sexp_shape`) surfaces here because
        // the composition through `to_quote_form()` picks up the swap
        // at the subset-to-superset projection. Sibling of the outer
        // `Sexp` construct family's
        // `sexp_quote_family_constructors_emit_canonical_tuple_variant_for_every_marker`
        // (commit 38f076b) on the outer-shape axis rather than the
        // tuple-variant axis.
        assert_eq!(
            UnquoteForm::Unquote.sexp_shape(),
            SexpShape::Unquote,
            "UnquoteForm::Unquote.sexp_shape() drifted from SexpShape::Unquote",
        );
        assert_eq!(
            UnquoteForm::Splice.sexp_shape(),
            SexpShape::UnquoteSplice,
            "UnquoteForm::Splice.sexp_shape() drifted from SexpShape::UnquoteSplice",
        );
    }

    #[test]
    fn unquote_form_iac_forge_tag_routes_through_to_quote_form_iac_forge_tag_via_composition() {
        // Post-lift composition pin: for every `uf: UnquoteForm`,
        // `uf.iac_forge_tag()` and `uf.to_quote_form().iac_forge_tag()`
        // agree byte-for-byte — the (subset marker, canonical
        // iac-forge tag) pairing rides through the superset's
        // canonical `QuoteForm::iac_forge_tag` closed-set match rather
        // than through a parallel two-arm inline table on the subset.
        // A regression that re-inlines the two arms as a parallel
        // match-table (e.g. a future edit that spells `Self::Unquote
        // => "unquote"` / `Self::Splice => "unquote-splicing"` directly
        // at `UnquoteForm::iac_forge_tag` instead of routing through
        // `self.to_quote_form().iac_forge_tag()`) still passes the
        // per-arm truth-table pin below but fails THIS composition
        // pin — the subset's canonical interop vocabulary is no
        // longer derived from the superset's canonical site. Sibling-
        // shape pin to commit 250c001's
        // `unquote_form_marker_routes_through_to_quote_form_prefix_via_composition`,
        // commit 92daace's
        // `unquote_form_wrap_routes_through_to_quote_form_wrap_via_composition`,
        // and this run's sibling
        // `unquote_form_sexp_shape_routes_through_to_quote_form_sexp_shape_via_composition`
        // — all four pin the subset's projection through the
        // superset's canonical site via the same typed composition
        // posture, the invariant the subset-to-superset composition
        // was lifted to make load-bearing on the type system rather
        // than on per-callsite discipline.
        for uf in UnquoteForm::ALL {
            let from_tag = uf.iac_forge_tag();
            let from_composition = uf.to_quote_form().iac_forge_tag();
            assert_eq!(
                from_tag, from_composition,
                "UnquoteForm::{uf:?}.iac_forge_tag() drifted from .to_quote_form().iac_forge_tag() — the subset's canonical interop vocabulary is no longer derived from the superset's canonical site",
            );
        }
    }

    #[test]
    fn unquote_form_iac_forge_tag_emits_canonical_cl_tag_for_every_marker() {
        // Per-arm truth-table pin of the canonical (UnquoteForm variant,
        // iac-forge tag) mapping: `UnquoteForm::Unquote → "unquote"`
        // and `UnquoteForm::Splice → "unquote-splicing"` byte-for-byte.
        // The `-splicing` suffix on `Splice` is load-bearing: the
        // Common-Lisp-canonical form REQUIRES `(unquote-splicing x)`
        // rather than `(unquote-splice x)`, and every downstream
        // BLAKE3 attestation key + render-cache shape hashes on the
        // exact tag spelling. A regression that swaps the two arms
        // (a marker/tag swap that still routes through the superset's
        // `iac_forge_tag`) surfaces here because the composition
        // through `to_quote_form()` picks up the swap at the subset-
        // to-superset projection. A regression that drops the
        // `-splicing` suffix and consolidates the tag with the
        // substrate's diagnostic label (`unquote-splice`) also
        // surfaces here. Sibling of the outer `Sexp` construct
        // family's canonical tuple-variant pins on the interop-tag
        // axis rather than the tuple-variant axis.
        assert_eq!(
            UnquoteForm::Unquote.iac_forge_tag(),
            "unquote",
            "UnquoteForm::Unquote.iac_forge_tag() drifted from canonical CL 'unquote' tag",
        );
        assert_eq!(
            UnquoteForm::Splice.iac_forge_tag(),
            "unquote-splicing",
            "UnquoteForm::Splice.iac_forge_tag() drifted from canonical CL 'unquote-splicing' tag \
             — the '-splicing' suffix is load-bearing for iac-forge canonical-form round-trip",
        );
    }

    #[test]
    fn unquote_form_iac_forge_tag_diverges_from_sexp_shape_label_at_splice_arm() {
        // BOUNDARY-DISTINCT CONTRACT (subset peer): the iac-forge
        // canonical tag for `UnquoteForm::Splice` is
        // `"unquote-splicing"` (CL canonical form), distinct from
        // `SexpShape::label` for the corresponding subset shape
        // `SexpShape::UnquoteSplice`, which renders the shorter
        // `"unquote-splice"` (substrate diagnostic surface). Pins the
        // divergence on the substitution-subset carving in lockstep
        // with the superset-side pin
        // `quote_form_iac_forge_tag_diverges_from_sexp_shape_label_for_unquote_splice`
        // in `ast.rs`. On the non-`Splice` arm the two projections
        // MUST agree (both spell `"unquote"` at the substitution-
        // subset's `Unquote` arm) — pin that path-uniformity too so
        // a regression that homogenizes both arms surfaces here.
        // A future "consolidation" PR that renames one side would
        // silently break either the iac-forge canonical-form round-
        // trip OR the operator-facing diagnostic surface at the
        // template-substitution rejection sites.
        assert_eq!(
            UnquoteForm::Unquote.iac_forge_tag(),
            SexpShape::Unquote.label(),
            "the Unquote arm's iac-forge tag AND diagnostic label MUST agree — \
             both spell 'unquote' by CL + substrate convention alike",
        );
        assert_eq!(
            UnquoteForm::Splice.iac_forge_tag(),
            "unquote-splicing",
            "UnquoteForm::Splice.iac_forge_tag() drifted from canonical CL 'unquote-splicing' tag",
        );
        assert_eq!(
            SexpShape::UnquoteSplice.label(),
            "unquote-splice",
            "SexpShape::UnquoteSplice.label() drifted from substrate diagnostic 'unquote-splice' label",
        );
        assert_ne!(
            UnquoteForm::Splice.iac_forge_tag(),
            SexpShape::UnquoteSplice.label(),
            "the two projections MUST disagree at Splice — the CL canonical form \
             requires '-splicing' while the substrate's diagnostic label uses the \
             shorter '-splice'; consolidating them would break either side",
        );
    }

    #[test]
    fn unquote_form_iac_forge_tag_agrees_with_outer_sexp_iac_forge_arm_when_iac_forge_feature_gate_is_on(
    ) {
        // Cross-boundary intent pin: for every `uf: UnquoteForm` and a
        // representative `inner: Sexp`, the tag the outer `From<&Sexp>
        // for iac_forge::SExpr` interop arm emits when it decomposes
        // the wrapper via `expect_quote_form()` and projects through
        // `QuoteForm::iac_forge_tag()` agrees byte-for-byte with the
        // direct `UnquoteForm::iac_forge_tag()` projection on the
        // marker the outer projection would have recovered. Pinned
        // through the composition `qf.iac_forge_tag() ==
        // qf.as_unquote_form().map(UnquoteForm::iac_forge_tag)
        // .unwrap_or_else(|| qf.iac_forge_tag())` — the (QuoteForm,
        // UnquoteForm) tag agreement on the substitution-subset
        // carving is exactly the invariant a future refactor that
        // routes the outer interop arm through THIS subset method
        // (on Unquote/UnquoteSplice) instead of the superset method
        // (on all four) can rely on to stay byte-identical.
        //
        // Feature-gated because the iac-forge feature is off by
        // default in the isolated tatara-lisp build (the actual
        // `From<&Sexp> for iac_forge::SExpr` impl and its tests live
        // behind the same gate); this test pins the invariant that
        // WOULD bind the cross-boundary agreement WITHOUT depending
        // on the feature-gated impl compiling — the composition law
        // holds on the typed algebra regardless.
        for uf in UnquoteForm::ALL {
            let via_subset = uf.iac_forge_tag();
            let via_superset = uf.to_quote_form().iac_forge_tag();
            assert_eq!(
                via_subset, via_superset,
                "UnquoteForm::{uf:?}.iac_forge_tag() drifted from .to_quote_form().iac_forge_tag() — \
                 the outer interop arm's byte-identity on the substitution-subset carving is broken",
            );
        }
    }

    #[test]
    fn unquote_form_iac_forge_tag_specializes_to_matching_arm_of_quote_form_iac_forge_tag() {
        // PER-VARIANT RESTRICTION LAW pin: the subset's tag projection
        // agrees with the superset's tag projection on the
        // substitution-subset carving arm-for-arm. `UnquoteForm::
        // Unquote.iac_forge_tag() == crate::ast::QuoteForm::Unquote
        // .iac_forge_tag()`, and `UnquoteForm::Splice.iac_forge_tag()
        // == crate::ast::QuoteForm::UnquoteSplice.iac_forge_tag()`.
        // The composition through `to_quote_form()` binds this
        // agreement to the SAME closed-set match arm on the
        // superset's `iac_forge_tag` per subset variant — a regression
        // that drifts `to_quote_form`'s arm mapping (e.g. a future
        // edit that pairs `UnquoteForm::Splice` with
        // `QuoteForm::Unquote` on the subset → superset projection)
        // fails BOTH the arm-check here AND the composition pin above,
        // with distinct arm-anchored failure signatures. Sibling of
        // commit 3e92457's `sexp_shape` per-variant restriction pins
        // and commit 92daace's `wrap` per-variant restriction pins
        // on the interop-tag axis.
        use crate::ast::QuoteForm;
        assert_eq!(
            UnquoteForm::Unquote.iac_forge_tag(),
            QuoteForm::Unquote.iac_forge_tag(),
            "UnquoteForm::Unquote.iac_forge_tag() drifted from QuoteForm::Unquote.iac_forge_tag()",
        );
        assert_eq!(
            UnquoteForm::Splice.iac_forge_tag(),
            QuoteForm::UnquoteSplice.iac_forge_tag(),
            "UnquoteForm::Splice.iac_forge_tag() drifted from QuoteForm::UnquoteSplice.iac_forge_tag()",
        );
    }

    #[test]
    fn unquote_form_hash_discriminator_routes_through_to_quote_form_hash_discriminator_via_composition(
    ) {
        // Post-lift composition pin: for every `uf: UnquoteForm`,
        // `uf.hash_discriminator()` and
        // `uf.to_quote_form().hash_discriminator()` agree byte-for-byte
        // — the (subset marker, outer-Sexp cache-key byte) pairing
        // rides through the superset's canonical
        // `QuoteForm::hash_discriminator` closed-set match rather than
        // through a parallel two-arm inline table on the subset. A
        // regression that re-inlines the two arms as a parallel
        // match-table (e.g. a future edit that spells `Self::Unquote
        // => 5` / `Self::Splice => 6` directly at
        // `UnquoteForm::hash_discriminator` instead of routing through
        // `self.to_quote_form().hash_discriminator()`) still passes
        // the per-arm truth-table pin below but fails THIS composition
        // pin — the subset's cache-key vocabulary is no longer derived
        // from the superset's canonical site. Sibling-shape pin to the
        // four prior-lift composition pins on `UnquoteForm`:
        // `unquote_form_marker_routes_through_to_quote_form_prefix_via_composition`,
        // `unquote_form_wrap_routes_through_to_quote_form_wrap_via_composition`,
        // `unquote_form_sexp_shape_routes_through_to_quote_form_sexp_shape_via_composition`,
        // and
        // `unquote_form_iac_forge_tag_routes_through_to_quote_form_iac_forge_tag_via_composition`
        // — all five pin the subset's projection through the
        // superset's canonical site via the same typed composition
        // posture. The FIFTH composition-through-`to_quote_form` axis
        // on the substitution-subset closed set is now load-bearing
        // on the type system rather than on per-callsite discipline.
        for uf in UnquoteForm::ALL {
            let from_disc = uf.hash_discriminator();
            let from_composition = uf.to_quote_form().hash_discriminator();
            assert_eq!(
                from_disc, from_composition,
                "UnquoteForm::{uf:?}.hash_discriminator() drifted from .to_quote_form().hash_discriminator() — the subset's cache-key vocabulary is no longer derived from the superset's canonical site",
            );
        }
    }

    #[test]
    fn unquote_form_hash_discriminator_pins_legacy_cache_key_bytes() {
        // Per-arm truth-table pin of the canonical (UnquoteForm variant,
        // outer-Sexp cache-key byte) mapping: `UnquoteForm::Unquote → 5`
        // and `UnquoteForm::Splice → 6` byte-for-byte. These bytes are
        // load-bearing: the substrate's `Hash for Sexp` body composes
        // `QuoteForm::hash_discriminator` at the Unquote/UnquoteSplice
        // arms and the macro-expansion cache keys on those bytes;
        // changing either arm silently invalidates every cached
        // expansion across the substrate AND risks collision with the
        // reserved bytes the non-substitution carvings' arms use
        // (`{0, 2}` for `StructuralKind`, `1` for the outer `Atom`
        // marker, `{3, 4}` for the non-substitution quote-family arms
        // `Quote`/`Quasiquote`). Sibling of
        // `quote_form_hash_discriminator_pins_legacy_cache_key_bytes`
        // (4-arm superset pin),
        // `structural_kind_hash_discriminator_pins_legacy_cache_key_bytes`
        // (2-arm structural-residual pin),
        // `atom_kind_hash_discriminator_pins_legacy_atom_cache_key_bytes`
        // (6-arm atomic-payload pin), and
        // `sexp_shape_hash_discriminator_pins_legacy_outer_cache_key_bytes`
        // (12-arm shape-level pin) — this 2-arm subset pin joins the
        // family the closed-set typed algebra composes on for outer-
        // Sexp cache-key partition coherence.
        assert_eq!(
            UnquoteForm::Unquote.hash_discriminator(),
            5,
            "UnquoteForm::Unquote.hash_discriminator() drifted from legacy cache-key byte 5",
        );
        assert_eq!(
            UnquoteForm::Splice.hash_discriminator(),
            6,
            "UnquoteForm::Splice.hash_discriminator() drifted from legacy cache-key byte 6",
        );
    }

    #[test]
    fn unquote_form_hash_discriminator_specializes_to_matching_arm_of_quote_form_hash_discriminator(
    ) {
        // PER-VARIANT RESTRICTION LAW pin: the subset's discriminator
        // projection agrees with the superset's discriminator
        // projection on the substitution-subset carving arm-for-arm.
        // `UnquoteForm::Unquote.hash_discriminator() ==
        // QuoteForm::Unquote.hash_discriminator()`, and
        // `UnquoteForm::Splice.hash_discriminator() ==
        // QuoteForm::UnquoteSplice.hash_discriminator()`. The
        // composition through `to_quote_form()` binds this agreement
        // to the SAME closed-set match arm on the superset's
        // `hash_discriminator` per subset variant — a regression that
        // drifts `to_quote_form`'s arm mapping (e.g. a future edit
        // that pairs `UnquoteForm::Splice` with `QuoteForm::Unquote`
        // on the subset → superset projection) fails BOTH the
        // arm-check here AND the composition pin above, with distinct
        // arm-anchored failure signatures. Sibling of the four prior
        // per-variant restriction pins on `UnquoteForm`: `marker`
        // (through `QuoteForm::prefix`), `wrap` (through
        // `QuoteForm::wrap`), `sexp_shape` (through
        // `QuoteForm::sexp_shape`), and `iac_forge_tag` (through
        // `QuoteForm::iac_forge_tag`) — the cache-key axis closes the
        // per-variant restriction family on the substitution subset.
        use crate::ast::QuoteForm;
        assert_eq!(
            UnquoteForm::Unquote.hash_discriminator(),
            QuoteForm::Unquote.hash_discriminator(),
            "UnquoteForm::Unquote.hash_discriminator() drifted from QuoteForm::Unquote.hash_discriminator()",
        );
        assert_eq!(
            UnquoteForm::Splice.hash_discriminator(),
            QuoteForm::UnquoteSplice.hash_discriminator(),
            "UnquoteForm::Splice.hash_discriminator() drifted from QuoteForm::UnquoteSplice.hash_discriminator()",
        );
    }

    #[test]
    fn unquote_form_hash_discriminator_partitions_disjointly_from_non_substitution_carvings() {
        // DISJOINTNESS CONTRACT pin: the substitution-subset
        // discriminator image `{5, 6}` MUST be disjoint from every
        // other outer-Sexp carving's discriminator image — otherwise
        // the substrate's `Hash for Sexp` cache-key partition
        // silently collides and macro-expansion cache hits leak
        // across carvings. The reserved bytes are:
        //   * `StructuralKind::hash_discriminator` image: `{0, 2}`
        //     (Nil=0, List=2)
        //   * outer `Atom` carve marker: `{1}` (single-arm literal
        //     inside `Hash for Sexp`)
        //   * non-substitution `QuoteForm` arms
        //     (Quote/Quasiquote): `{3, 4}` (subset image of
        //     `QuoteForm::hash_discriminator` restricted to the
        //     non-`UnquoteForm` carving)
        // Sibling of the joint outer-Sexp discriminator-partition
        // pin at the shape-level algebra
        // (`sexp_shape_hash_discriminator_partitions_by_three_way_carving_disjointly`)
        // — this test pins the FOURTH carving's partition membership
        // (the 2-of-4 substitution-subset carving of `QuoteForm`)
        // rather than the three top-level carvings of `SexpShape`.
        use crate::ast::QuoteForm;
        use std::collections::HashSet;

        let subset_image: HashSet<u8> = UnquoteForm::ALL
            .iter()
            .map(|uf| uf.hash_discriminator())
            .collect();
        assert_eq!(
            subset_image,
            HashSet::from([5, 6]),
            "UnquoteForm::ALL swept through hash_discriminator MUST cover exactly {{5, 6}} — the substitution-subset cache-key partition",
        );

        let structural_image: HashSet<u8> = StructuralKind::ALL
            .iter()
            .map(|sk| sk.hash_discriminator())
            .collect();
        assert!(
            subset_image.is_disjoint(&structural_image),
            "UnquoteForm hash_discriminator image {subset_image:?} MUST be disjoint from StructuralKind image {structural_image:?} — a cache-key collision would leak macro-expansion hits across the substitution-subset and structural-residual carvings",
        );

        let atom_outer_byte: HashSet<u8> = HashSet::from([1]);
        assert!(
            subset_image.is_disjoint(&atom_outer_byte),
            "UnquoteForm hash_discriminator image {subset_image:?} MUST be disjoint from the outer Atom carve marker {{1}} — a cache-key collision would leak macro-expansion hits across the substitution-subset and atomic-payload carvings",
        );

        let non_substitution_quote_image: HashSet<u8> = [QuoteForm::Quote, QuoteForm::Quasiquote]
            .iter()
            .map(|qf| qf.hash_discriminator())
            .collect();
        assert!(
            subset_image.is_disjoint(&non_substitution_quote_image),
            "UnquoteForm hash_discriminator image {subset_image:?} MUST be disjoint from the non-substitution QuoteForm arms' image {non_substitution_quote_image:?} — a cache-key collision would leak macro-expansion hits across the substitution-subset and non-substitution quote-family carvings",
        );
    }

    #[test]
    fn unquote_form_per_role_hash_discriminators_alias_quote_form_per_role_hash_discriminators_byte_for_byte(
    ) {
        // ALIAS CONTRACT: pin both per-role
        // `pub(crate) const UnquoteForm::*_HASH_DISCRIMINATOR`
        // aliases equal the corresponding
        // `pub(crate) const QuoteForm::*_HASH_DISCRIMINATOR`
        // byte-for-byte — so the UnquoteForm ⊂ QuoteForm outer-`Sexp`
        // cache-key-byte vocabulary containment routes through the
        // typed `pub(crate) const UnquoteForm::V_HASH_DISCRIMINATOR:
        // u8 = QuoteForm::V_HASH_DISCRIMINATOR` alias chain rather
        // than through two independent literal-discipline sites. A
        // regression that renames the QuoteForm side without updating
        // the UnquoteForm alias pointing at it fails-loudly here with
        // the exact axis identified (UNQUOTE / SPLICE); a regression
        // that re-inlines the UnquoteForm constant to a fresh literal
        // still passes this pin but loses the alias-chain typing
        // (which is what
        // `unquote_form_hash_discriminators_align_with_all_by_index`
        // catches in combination).
        //
        // Sibling posture to
        // `unquote_form_per_role_markers_alias_quote_form_per_role_prefixes_byte_for_byte`
        // (commit 3640f76),
        // `unquote_form_per_role_iac_forge_tags_alias_quote_form_per_role_iac_forge_tags_byte_for_byte`
        // (commit 6acab84), and
        // `unquote_form_per_role_labels_alias_quote_form_per_role_labels_byte_for_byte`
        // (commit da68af5): all four pin the invariant that the
        // UnquoteForm subset algebra's per-role bytes are structurally
        // derived from the parent QuoteForm superset's per-role bytes
        // via a `pub const = Parent::CONST` alias rather than through
        // parallel literal tables — the axis there is the three
        // `&'static str` production vocabularies (reader punctuation,
        // iac-forge canonical-form, diagnostic label); the axis here
        // is the `u8` outer-`Sexp` cache-key vocabulary. All four axes
        // span the FOUR production byte-vocabularies the parent
        // [`QuoteForm`] closed set carries per role, and all four
        // bind through the same aliased typed source of truth on
        // this UnquoteForm subset.
        use crate::ast::QuoteForm;
        assert_eq!(
            UnquoteForm::UNQUOTE_HASH_DISCRIMINATOR,
            QuoteForm::UNQUOTE_HASH_DISCRIMINATOR
        );
        assert_eq!(
            UnquoteForm::SPLICE_HASH_DISCRIMINATOR,
            QuoteForm::UNQUOTE_SPLICE_HASH_DISCRIMINATOR
        );
    }

    #[test]
    fn unquote_form_hash_discriminator_arms_route_through_per_role_hash_discriminators_for_every_variant(
    ) {
        // PATH-UNIFORMITY: `UnquoteForm::V.hash_discriminator()` MUST
        // equal the per-role `pub(crate) const
        // UnquoteForm::V_HASH_DISCRIMINATOR` for every
        // `v: UnquoteForm`. Pre-lift the two cache-key bytes were
        // reachable through the two-step composition
        // `uf.to_quote_form().hash_discriminator()` OR through direct
        // `QuoteForm::UNQUOTE_HASH_DISCRIMINATOR` reach-across; post-
        // lift each variant's canonical bytes are reachable through
        // the per-role `UnquoteForm::*_HASH_DISCRIMINATOR` alias AND
        // through the inherent `hash_discriminator()` method too. Pin
        // the byte-equality between the runtime projection and the
        // compile-time alias so a regression that renames the alias
        // without updating the arm (or vice versa) fails-loudly at
        // the exact axis.
        //
        // Sibling-shape pin to
        // `unquote_form_marker_arms_route_through_per_role_markers_for_every_variant`,
        // `unquote_form_iac_forge_tag_arms_route_through_per_role_iac_forge_tags_for_every_variant`,
        // and
        // `unquote_form_label_arms_route_through_per_role_labels_for_every_variant`
        // one vocabulary over on the SAME subset algebra — together
        // the four pins close the subset algebra's
        // `pub const *_MARKER` + `pub const *_IAC_FORGE_TAG` +
        // `pub const *_LABEL` + `pub(crate) const *_HASH_DISCRIMINATOR`
        // surfaces against the runtime projections that feed the four
        // production byte-vocabularies.
        assert_eq!(
            UnquoteForm::Unquote.hash_discriminator(),
            UnquoteForm::UNQUOTE_HASH_DISCRIMINATOR
        );
        assert_eq!(
            UnquoteForm::Splice.hash_discriminator(),
            UnquoteForm::SPLICE_HASH_DISCRIMINATOR
        );
    }

    #[test]
    fn unquote_form_hash_discriminators_has_expected_cardinality() {
        // Cardinality pin: `HASH_DISCRIMINATORS.len() == 2` matches
        // `ALL.len()` so a refactor that loosens the type to `&[u8]`
        // fails HERE (the `[_; 2]` slot cannot be sliced silently),
        // and a variant added to `ALL` without a matching
        // `HASH_DISCRIMINATORS` row fails the pair-arity gate at the
        // array literal itself before this test even runs. Sibling
        // posture to `unquote_form_markers_has_expected_cardinality`,
        // `unquote_form_iac_forge_tags_has_expected_cardinality`, and
        // `unquote_form_labels_has_expected_cardinality` one
        // vocabulary over on the SAME subset algebra.
        assert_eq!(UnquoteForm::HASH_DISCRIMINATORS.len(), 2);
        assert_eq!(
            UnquoteForm::HASH_DISCRIMINATORS.len(),
            UnquoteForm::ALL.len()
        );
    }

    #[test]
    fn unquote_form_hash_discriminators_align_with_all_by_index() {
        // ALIGNMENT PIN: sweep `HASH_DISCRIMINATORS[i] ==
        // ALL[i].hash_discriminator()` so any `zip(ALL,
        // HASH_DISCRIMINATORS)` consumer reads a coherent (variant,
        // cache-key byte) pair off ONE forced-arity array pair. A
        // regression that reorders HASH_DISCRIMINATORS without also
        // reordering ALL (or vice versa) fails-loudly at the exact
        // index that drifted. Sibling of
        // `unquote_form_markers_align_with_all_by_index`,
        // `unquote_form_iac_forge_tags_align_with_all_by_index`, and
        // `unquote_form_labels_align_with_all_by_index` — same
        // alignment contract on the fourth byte-vocabulary axis.
        assert_eq!(
            UnquoteForm::HASH_DISCRIMINATORS.len(),
            UnquoteForm::ALL.len()
        );
        for (i, form) in UnquoteForm::ALL.iter().enumerate() {
            assert_eq!(
                UnquoteForm::HASH_DISCRIMINATORS[i],
                form.hash_discriminator(),
                "UnquoteForm::HASH_DISCRIMINATORS[{i}] `{byte}` drifted \
                 from UnquoteForm::ALL[{i}].hash_discriminator() \
                 `{via_variant}` — the canonical ALL ordering and the \
                 HASH_DISCRIMINATORS ordering must match element-wise",
                byte = UnquoteForm::HASH_DISCRIMINATORS[i],
                via_variant = form.hash_discriminator(),
            );
        }
    }

    #[test]
    fn unquote_form_hash_discriminators_pairwise_distinct() {
        // 2x2 pairwise sweep so a collision between the two cache-
        // key bytes (which would silently degrade two distinct
        // template-substitution markers to the SAME macro-expansion
        // cache key) fails-loudly at the exact pair. Sibling-shape
        // pin to `unquote_form_markers_pairwise_distinct`,
        // `unquote_form_iac_forge_tags_pairwise_distinct`, and
        // `unquote_form_labels_pairwise_distinct` one vocabulary
        // over on the SAME subset algebra.
        for (i, a) in UnquoteForm::HASH_DISCRIMINATORS.iter().enumerate() {
            for (j, b) in UnquoteForm::HASH_DISCRIMINATORS.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "UnquoteForm::HASH_DISCRIMINATORS[{i}] ({a}) collides \
                     with UnquoteForm::HASH_DISCRIMINATORS[{j}] ({b}) — \
                     two distinct template markers cannot share cache-key \
                     bytes",
                );
            }
        }
    }

    #[test]
    fn unquote_form_hash_discriminators_pin_legacy_cache_key_bytes() {
        // Per-arm truth-table pin of each per-role
        // `pub(crate) const UnquoteForm::*_HASH_DISCRIMINATOR` at
        // its exact canonical `u8` byte: `UNQUOTE_HASH_DISCRIMINATOR
        // == 5` and `SPLICE_HASH_DISCRIMINATOR == 6`. Pins each
        // per-role `pub(crate) const` value itself (as opposed to
        // pinning the `hash_discriminator()` projection method's
        // returns, which is
        // `unquote_form_hash_discriminator_pins_legacy_cache_key_bytes`'s
        // job) so a regression that drifts the alias source on the
        // parent [`QuoteForm`] side without updating this subset's
        // aliases (which would require ALSO fixing this test) fails
        // here BEFORE the composition-through-`to_quote_form()`
        // routing masks the drift. Together the two pins close the
        // (per-role const, projection method) pairing on the
        // substitution-subset cache-key axis. Sibling posture to
        // `structural_kind_hash_discriminators_pin_legacy_cache_key_bytes`
        // (2-arm structural-residual),
        // `quote_form_hash_discriminators_pin_legacy_cache_key_bytes`
        // (4-arm quote-family),
        // `atom_kind_hash_discriminators_pin_legacy_atom_cache_key_bytes`
        // (6-arm atomic-payload nested inner), and
        // `sexp_shape_hash_discriminators_pin_legacy_outer_cache_key_bytes`
        // (12-arm outer shape) — this 2-arm subset pin joins the
        // family the closed-set typed algebra composes on for outer-
        // Sexp cache-key partition coherence.
        assert_eq!(
            UnquoteForm::UNQUOTE_HASH_DISCRIMINATOR,
            5,
            "UnquoteForm::UNQUOTE_HASH_DISCRIMINATOR drifted from legacy cache-key byte 5",
        );
        assert_eq!(
            UnquoteForm::SPLICE_HASH_DISCRIMINATOR,
            6,
            "UnquoteForm::SPLICE_HASH_DISCRIMINATOR drifted from legacy cache-key byte 6",
        );
    }

    #[test]
    fn unquote_form_hash_discriminators_align_with_superset_by_projection() {
        // CROSS-ALGEBRA COMPOSITION contract: for every `i in 0..2`,
        // `UnquoteForm::HASH_DISCRIMINATORS[i]` equals the byte the
        // parent superset's projection returns for
        // `UnquoteForm::ALL[i].to_quote_form()` — the outer-subset
        // peer alias equals the superset's canonical byte at rustc-
        // time through the `const` initializer AND at test time
        // through the projection composition. Sibling posture to
        // `sexp_shape_hash_discriminators_align_with_sub_carvings_by_projection`
        // (12-arm SexpShape × 3 sub-carvings composition) — this
        // pin closes the same composition contract at the 2-of-4
        // subset carving level.
        use crate::ast::QuoteForm;
        for (i, uf) in UnquoteForm::ALL.iter().enumerate() {
            let subset_byte = UnquoteForm::HASH_DISCRIMINATORS[i];
            let superset_byte = uf.to_quote_form().hash_discriminator();
            assert_eq!(
                subset_byte, superset_byte,
                "UnquoteForm::HASH_DISCRIMINATORS[{i}] ({subset_byte}) \
                 drifted from ALL[{i}].to_quote_form().hash_discriminator() \
                 ({superset_byte}) — the subset-through-superset composition \
                 no longer agrees with the aliased `pub(crate) const` array",
            );
        }
        // Additionally pin that the subset array is exactly the
        // Unquote/UnquoteSplice slice of the superset's
        // HASH_DISCRIMINATORS. QuoteForm::ALL declaration order is
        // `[Quote, Quasiquote, Unquote, UnquoteSplice]` (indices 2/3
        // are the substitution subset) — the two subset bytes are
        // exactly the `[2..4]` slice of QuoteForm::HASH_DISCRIMINATORS.
        assert_eq!(
            UnquoteForm::HASH_DISCRIMINATORS[0],
            QuoteForm::HASH_DISCRIMINATORS[2]
        );
        assert_eq!(
            UnquoteForm::HASH_DISCRIMINATORS[1],
            QuoteForm::HASH_DISCRIMINATORS[3]
        );
    }

    #[test]
    fn unquote_form_promotions_has_expected_cardinality() {
        // CARDINALITY CONTRACT: `UnquoteForm::PROMOTIONS.len() == 1` —
        // pin the single-arm collapse structurally so a future
        // refactor that switches the array type to `&[(Self, char,
        // Self)]` or extends the triple set doesn't silently loosen
        // the closed-set discipline. Sibling posture to
        // `quote_form_promotions_has_expected_cardinality` on the
        // parent four-arm superset — that pin binds the parent's
        // singleton collapse; this pin binds the same collapse at the
        // substitution-subset level.
        assert_eq!(UnquoteForm::PROMOTIONS.len(), 1);
    }

    #[test]
    fn unquote_form_promotions_pin_legacy_substitution_subset_splice_promotion_triple() {
        // TRIPLE-IDENTITY CONTRACT: pin the singleton entry of
        // `UnquoteForm::PROMOTIONS` at its exact canonical triple
        // `(Self::Unquote, '@', Self::Splice)` — the reader's ONE
        // `,` + `@` → `,@` promotion at the substitution-subset
        // level. A regression that drifts the triple (e.g. flips the
        // head column to `Self::Splice`, drifts the discriminator to
        // a different byte, or promotes to a phantom variant) fails
        // loudly here at rustc-time equality rather than silently at
        // reader tokenizer drift where `,@xs` sequences degrade to
        // the wrong substitution-subset marker. Sibling posture to
        // `quote_form_promotions_pin_legacy_splice_promotion_triple`
        // on the parent four-arm superset — the triple's shape is
        // byte-identical up to the substitution-subset variant
        // renaming (`QuoteForm::Unquote` ↔ `UnquoteForm::Unquote`,
        // `QuoteForm::UnquoteSplice` ↔ `UnquoteForm::Splice`, with
        // the middle discriminator column aliased directly at the
        // constant site).
        let (head, disc, promoted) = UnquoteForm::PROMOTIONS[0];
        assert_eq!(head, UnquoteForm::Unquote);
        assert_eq!(disc, crate::ast::QuoteForm::SPLICE_DISCRIMINATOR);
        assert_eq!(disc, '@');
        assert_eq!(promoted, UnquoteForm::Splice);
    }

    #[test]
    fn unquote_form_promotions_align_with_quote_form_promotions_by_projection() {
        // CROSS-ALGEBRA COMPOSITION contract: for every `i in 0..1`,
        // `(UnquoteForm::PROMOTIONS[i].0.to_quote_form(),
        //   UnquoteForm::PROMOTIONS[i].1,
        //   UnquoteForm::PROMOTIONS[i].2.to_quote_form())`
        // equals `QuoteForm::PROMOTIONS[0]` byte-for-byte — the
        // substitution-subset promotion triple embeds into the parent
        // superset's promotion triple through the pre-existing 2-of-4
        // subset → superset projection `Self::to_quote_form` on the
        // head + promoted endpoints AND identity on the middle
        // discriminator `char` column. Sibling posture to
        // `unquote_form_hash_discriminators_align_with_superset_by_projection`
        // (2-arm subset × 4-arm superset composition on the outer-
        // `Sexp` cache-key axis) — this pin closes the same
        // composition contract on the (head, disc, promoted) triple
        // axis at the substitution-subset carving level.
        use crate::ast::QuoteForm;
        for i in 0..UnquoteForm::PROMOTIONS.len() {
            let (subset_head, subset_disc, subset_promoted) = UnquoteForm::PROMOTIONS[i];
            let projected_head = subset_head.to_quote_form();
            let projected_promoted = subset_promoted.to_quote_form();
            let superset_triple = QuoteForm::PROMOTIONS[i];
            assert_eq!(
                (projected_head, subset_disc, projected_promoted),
                superset_triple,
                "UnquoteForm::PROMOTIONS[{i}] projection through \
                 `to_quote_form()` drifted from \
                 QuoteForm::PROMOTIONS[{i}]",
            );
        }
    }

    #[test]
    fn unquote_form_promotions_head_column_is_unquote_and_promoted_column_is_splice() {
        // CARVING PARTITION CONTRACT (substitution-subset level): on
        // the two-variant substitution-subset lattice, the promotion
        // triple's head column is the ONLY variant with a single-
        // char rendered marker (`Self::Unquote`, marker `,`) and the
        // promoted column is the ONLY variant with a two-char
        // rendered marker (`Self::Splice`, marker `,@`). Pin the
        // (head, promoted) endpoint identity across the closed
        // `UnquoteForm::ALL` set so a regression that flips the
        // endpoints or promotes to a phantom variant fails-loudly
        // here. The two variants of `UnquoteForm` split cleanly along
        // the promotion axis: single-char-marker `Unquote` is the
        // head, two-char-marker `Splice` is the promoted target.
        for (head, _, promoted) in UnquoteForm::PROMOTIONS {
            assert_eq!(
                head,
                UnquoteForm::Unquote,
                "the substitution-subset promotion head must be the \
                 single-char-marker variant `UnquoteForm::Unquote`",
            );
            assert_eq!(
                promoted,
                UnquoteForm::Splice,
                "the substitution-subset promotion target must be \
                 the two-char-marker variant `UnquoteForm::Splice`",
            );
            assert_eq!(
                head.marker(),
                crate::ast::QuoteForm::UNQUOTE_PREFIX,
                "the substitution-subset promotion head's marker \
                 must alias `QuoteForm::UNQUOTE_PREFIX`",
            );
            assert_eq!(
                promoted.marker(),
                crate::ast::QuoteForm::UNQUOTE_SPLICE_PREFIX,
                "the substitution-subset promotion target's marker \
                 must alias `QuoteForm::UNQUOTE_SPLICE_PREFIX`",
            );
        }
    }

    #[test]
    fn unquote_form_promotions_compose_marker_from_head_marker_and_discriminator() {
        // RENDERED-MARKER COMPOSITION LAW (subset-level): for every
        // `(head, disc, promoted)` in `UnquoteForm::PROMOTIONS`,
        // `format!("{}{}", head.marker(), disc) == promoted.marker()`.
        // The subset's rendered-marker composition (head-marker byte
        // + discriminator byte = promoted-marker two-byte string)
        // agrees byte-for-byte with the promoted variant's rendered
        // marker — the reader's peek-then-consume arm's rendered
        // marker identity closes the read↔write duality across the
        // substitution-subset promotion algebra. Sibling posture to
        // `quote_form_promotions_compose_prefix_from_source_prefix_and_discriminator_for_every_entry`
        // on the parent four-arm superset — that pin binds the
        // parent superset's rendered-prefix composition; this pin
        // binds the substitution-subset's rendered-marker
        // composition on the SAME single promotion triple.
        for (head, disc, promoted) in UnquoteForm::PROMOTIONS {
            let composed = format!("{}{}", head.marker(), disc);
            assert_eq!(
                composed,
                promoted.marker(),
                "UnquoteForm::PROMOTIONS `({head:?}, {disc:?}, {promoted:?})` \
                 marker composition drifted — expected \
                 `head.marker() + disc` to equal `promoted.marker()`",
            );
        }
    }

    #[test]
    fn unquote_form_sexp_shape_round_trips_through_as_unquote_form() {
        // The embed/project section law on the substitution-subset
        // carving: `UnquoteForm::sexp_shape(uf).as_unquote_form() ==
        // Some(uf)` for every `uf: UnquoteForm::ALL`. Proves the
        // (embed, project) pair is an `Iso(UnquoteForm, UnquoteShape ⊂
        // SexpShape)` — the section is total on `UnquoteForm`'s carving.
        // Sibling round-trip to
        // `atom_kind_sexp_shape_round_trips_through_as_atom_kind`
        // (on the 6-of-12 atomic-payload carving) and
        // `quote_form_sexp_shape_round_trips_through_as_quote_form`
        // (on the 4-of-12 quote-family carving). Closes the third and
        // final closed-set carving of `SexpShape` (the 2-of-12
        // substitution-subset carving) as a round-trip identity on
        // the typed algebra — pre-lift the pairing only lived in
        // the two-step composition `uf.to_quote_form().sexp_shape()
        // .as_quote_form().and_then(QuoteForm::as_unquote_form)` at
        // callsite; post-lift the pairing rides the typed projection
        // directly so a future regression that drifts the
        // (UnquoteForm variant, SexpShape variant) pairing fails
        // this assertion without depending on the composition
        // chain sitting between the two.
        for uf in UnquoteForm::ALL {
            let shape = uf.sexp_shape();
            let recovered = shape.as_unquote_form();
            assert_eq!(
                recovered,
                Some(uf),
                "UnquoteForm::{uf:?} did NOT round-trip — sexp_shape().as_unquote_form() must recover the typed marker",
            );
        }
    }

    #[test]
    fn unquote_form_per_role_shapes_alias_quote_form_per_role_shapes_byte_for_byte() {
        // ALIAS-CHAIN CONTRACT: each per-role `pub const *_SHAPE` on
        // `UnquoteForm` MUST bind byte-for-byte to the corresponding
        // per-role SHAPE on the parent [`crate::ast::QuoteForm`]
        // superset — the substitution-subset per-role embed targets
        // live at ONE substrate primitive per arm (aliased through
        // QuoteForm's canonical per-role SHAPE constants) rather than
        // at inline `SexpShape::X` literals OR a parallel two-arm
        // match table on this subset. Sibling posture to
        // `unquote_form_per_role_labels_alias_quote_form_per_role_labels_byte_for_byte`
        // on the diagnostic-label axis of the SAME closed set and to
        // `unquote_form_per_role_hash_discriminators_alias_quote_form_per_role_hash_discriminators_byte_for_byte`
        // on the outer-Sexp cache-key byte axis — every per-role
        // sub-vocabulary axis on this substitution subset now closes
        // through the parent's per-role canonical site.
        assert_eq!(
            UnquoteForm::UNQUOTE_SHAPE,
            crate::ast::QuoteForm::UNQUOTE_SHAPE,
        );
        assert_eq!(
            UnquoteForm::SPLICE_SHAPE,
            crate::ast::QuoteForm::UNQUOTE_SPLICE_SHAPE,
        );
    }

    #[test]
    fn unquote_form_per_role_shapes_pin_canonical_sexp_shape_variants() {
        // CANONICAL-SEXP-SHAPE CONTRACT: each per-role `pub const
        // *_SHAPE` on `UnquoteForm` MUST project to the canonical
        // [`SexpShape`] variant — `UNQUOTE_SHAPE = SexpShape::Unquote`,
        // `SPLICE_SHAPE = SexpShape::UnquoteSplice`. A regression that
        // silently renumbers QuoteForm's per-role SHAPE at the parent
        // superset (which this subset aliases) fails-loudly here at
        // the byte-equality level — sibling posture to
        // `quote_form_per_role_shapes_pin_canonical_sexp_shape_variants`
        // on the parent's 4-of-4 quote-family sweep.
        assert_eq!(UnquoteForm::UNQUOTE_SHAPE, SexpShape::Unquote);
        assert_eq!(UnquoteForm::SPLICE_SHAPE, SexpShape::UnquoteSplice);
    }

    #[test]
    fn unquote_form_shapes_has_expected_cardinality() {
        // CARDINALITY CONTRACT: `UnquoteForm::SHAPES.len() == 2 ==
        // UnquoteForm::ALL.len()`. Arity is forced at the declaration
        // site by rustc's `[SexpShape; 2]` check; this runtime pin
        // fails-loud so a future refactor that switches the array
        // type to `&[SexpShape]` doesn't silently loosen the closed-
        // set discipline. Sibling posture to
        // `unquote_form_hash_discriminators_has_expected_cardinality`
        // on the cache-key byte axis of the SAME closed set.
        assert_eq!(
            UnquoteForm::SHAPES.len(),
            2,
            "UnquoteForm::SHAPES cardinality drifted from the two-arm substitution-subset algebra",
        );
        assert_eq!(
            UnquoteForm::SHAPES.len(),
            UnquoteForm::ALL.len(),
            "UnquoteForm::SHAPES cardinality drifted from UnquoteForm::ALL — every family-wide array on this algebra must stay ALL-length in lockstep",
        );
    }

    #[test]
    fn unquote_form_shapes_align_with_all_by_index() {
        // ALIGNMENT CONTRACT: for every `i` in `0..UnquoteForm::ALL.len()`,
        // `UnquoteForm::SHAPES[i] == UnquoteForm::ALL[i].sexp_shape()`
        // — the family-wide array is a projection of the two-arm
        // `sexp_shape` method sweep in declaration order. A regression
        // that reorders ONE array without reordering the other fails-
        // loudly here. Sibling posture to
        // `unquote_form_hash_discriminators_align_with_all_by_index`
        // on the cache-key byte axis of the SAME closed set.
        for (i, uf) in UnquoteForm::ALL.iter().enumerate() {
            let via_variant = uf.sexp_shape();
            let via_array = UnquoteForm::SHAPES[i];
            assert_eq!(
                via_variant, via_array,
                "UnquoteForm::SHAPES[{i}] `{via_array:?}` diverged from UnquoteForm::ALL[{i}].sexp_shape() `{via_variant:?}`",
            );
        }
    }

    #[test]
    fn unquote_form_shapes_align_with_all_by_index_through_as_unquote_form() {
        // ROUND-TRIP CONTRACT: for every `i` in `0..UnquoteForm::ALL.len()`,
        // `UnquoteForm::SHAPES[i].as_unquote_form() ==
        // Some(UnquoteForm::ALL[i])` — closes the (embed, project)
        // section of the `Iso(UnquoteForm, UnquoteShape ⊂ SexpShape)`
        // as a family-wide array-indexed law rather than as a per-
        // variant assertion sweep (which the pre-existing
        // `unquote_form_sexp_shape_round_trips_through_as_unquote_form`
        // pins per-variant). Post-lift the round-trip identity closes
        // at BOTH the per-variant projection and the family-wide array
        // indexing. Sibling posture to
        // `quote_form_shapes_align_with_all_by_index_through_as_quote_form`
        // on the parent's 4-of-4 sweep.
        for (i, uf) in UnquoteForm::ALL.iter().enumerate() {
            let shape = UnquoteForm::SHAPES[i];
            assert_eq!(
                shape.as_unquote_form(),
                Some(*uf),
                "UnquoteForm::SHAPES[{i}] `{shape:?}` did NOT round-trip through SexpShape::as_unquote_form — the (embed, project) family-wide law broke",
            );
        }
    }

    #[test]
    fn unquote_form_shapes_pairwise_distinct() {
        // INJECTIVITY CONTRACT: the two entries of `UnquoteForm::SHAPES`
        // MUST be pairwise distinct — the UnquoteForm ⊂ SexpShape
        // 2-of-12 composed carving is injective (each subset variant
        // embeds into a UNIQUE outer SexpShape variant). A regression
        // that drifts one of the two aliases into the other (e.g. a
        // typo that spells `SPLICE_SHAPE = QuoteForm::UNQUOTE_SHAPE`)
        // fails-loudly here at the array level rather than as a silent
        // round-trip collision at consumer sites. Sibling posture to
        // `quote_form_shapes_pairwise_distinct` on the parent's 4-of-4
        // sweep and to `unquote_form_hash_discriminators_pairwise_distinct`
        // on the cache-key byte axis of the SAME closed set.
        assert_ne!(
            UnquoteForm::SHAPES[0],
            UnquoteForm::SHAPES[1],
            "UnquoteForm::SHAPES[0] `{a:?}` collides with UnquoteForm::SHAPES[1] `{b:?}` — the two-arm carving must be injective",
            a = UnquoteForm::SHAPES[0],
            b = UnquoteForm::SHAPES[1],
        );
    }

    #[test]
    fn unquote_form_shapes_align_with_superset_by_projection() {
        // CROSS-ALGEBRA COMPOSITION CONTRACT: for every `i`,
        // `UnquoteForm::SHAPES[i]` equals the byte the SUPERSET
        // projection returns for the corresponding QuoteForm variant
        // — the substitution-subset per-role embed target equals the
        // parent quote-family superset's canonical SHAPE at rustc-time
        // through the `const` alias AND at test time through the
        // projection composition. Pin the composition-identity across
        // the closed subset so a regression that drifts EITHER the
        // subset alias OR the superset canonical site fails-loudly
        // here. Sibling posture to
        // `unquote_form_hash_discriminators_align_with_superset_by_projection`
        // on the cache-key byte axis of the SAME closed set — that
        // pin binds the subset cache-key byte to the parent's
        // canonical byte; this pin binds the subset embed target to
        // the parent's canonical SHAPE.
        for (i, uf) in UnquoteForm::ALL.iter().enumerate() {
            let via_subset = UnquoteForm::SHAPES[i];
            let via_superset = uf.to_quote_form().sexp_shape();
            assert_eq!(
                via_subset, via_superset,
                "UnquoteForm::SHAPES[{i}] `{via_subset:?}` diverged from UnquoteForm::ALL[{i}].to_quote_form().sexp_shape() `{via_superset:?}` — the composition law across the subset carving broke",
            );
        }
    }

    #[test]
    fn as_unquote_form_projects_each_unquote_shape_to_canonical_unquote_form_and_rejects_non_unquote_shapes(
    ) {
        // Per-variant truth-table sweep across every `SexpShape::ALL`
        // entry — pins each variant's canonical mapping (the two
        // substitution-subset shapes project to the matching
        // `UnquoteForm`; every other shape — `Quote`, `Quasiquote`,
        // `Nil`, `List`, every atomic-payload arm — projects to
        // `None`) byte-for-byte. Sibling sweep to
        // `as_quote_form_projects_each_quote_shape_to_canonical_quote_form_and_rejects_non_quote_shapes`
        // and
        // `as_atom_kind_projects_each_atom_shape_to_canonical_atom_kind_and_rejects_non_atom_shapes`
        // on the substitution-subset carving axis.
        for shape in SexpShape::ALL {
            let projected = shape.as_unquote_form();
            let expected = match shape {
                SexpShape::Unquote => Some(UnquoteForm::Unquote),
                SexpShape::UnquoteSplice => Some(UnquoteForm::Splice),
                SexpShape::Nil
                | SexpShape::List
                | SexpShape::Quote
                | SexpShape::Quasiquote
                | SexpShape::Symbol
                | SexpShape::Keyword
                | SexpShape::String
                | SexpShape::Int
                | SexpShape::Float
                | SexpShape::Bool => None,
            };
            assert_eq!(
                projected, expected,
                "SexpShape::{shape:?}.as_unquote_form() drifted from canonical mapping",
            );
        }
    }

    #[test]
    fn as_unquote_form_routes_through_as_quote_form_and_quote_form_as_unquote_form_via_composition()
    {
        // Post-lift composition pin: for every `shape: SexpShape`,
        // `shape.as_unquote_form()` and `shape.as_quote_form()
        // .and_then(QuoteForm::as_unquote_form)` agree byte-for-byte
        // — the 2-of-12 substitution-subset carving rides through
        // the composition of the 4-of-12 quote-family carving
        // (`SexpShape::as_quote_form`) and the 2-of-4 template-
        // substitution subset gate on the quote-family superset
        // (`QuoteForm::as_unquote_form`), rather than through a
        // parallel twelve-arm inline match table here. A regression
        // that re-inlines the twelve arms as a parallel match-table
        // still passes the round-trip and truth-table sweeps but
        // fails THIS composition pin — the (outer shape, subset
        // marker) pairing is no longer derived from the two existing
        // closed-set matches the substrate already owns. Sibling
        // posture to `unquote_form_sexp_shape_routes_through_to_quote_form_sexp_shape_via_composition`
        // on the retraction direction of the (embed, project) dual.
        for shape in SexpShape::ALL {
            let from_projection = shape.as_unquote_form();
            let from_composition = shape
                .as_quote_form()
                .and_then(crate::ast::QuoteForm::as_unquote_form);
            assert_eq!(
                from_projection, from_composition,
                "SexpShape::{shape:?}.as_unquote_form() drifted from .as_quote_form().and_then(QuoteForm::as_unquote_form) — the retraction is no longer derived from the composition through the quote-family carving",
            );
        }
    }

    #[test]
    fn as_unquote_form_composes_with_marker_via_unquote_form_marker_round_trip() {
        // Cross-projection composition law (substitution-subset sibling
        // of `as_quote_form_composes_with_sexp_shape_via_quote_form_prefix_round_trip`
        // and `as_atom_kind_composes_with_sexp_shape_via_atom_kind_label_round_trip`):
        // for every `uf: UnquoteForm::ALL`, `uf.marker() ==
        // uf.sexp_shape().as_unquote_form().expect("...").marker()`.
        // Pins the (UnquoteForm variant, SexpShape variant) pairing
        // round-trips through the embed/project pair AND preserves
        // each variant's canonical template-substitution punctuation
        // (`","` / `",@"`) — a regression that drifts the round-trip
        // OR drifts the marker surfaces here. The label-coherence
        // binds the diagnostic surface to the typed algebra at BOTH
        // layers, matching the posture the atomic-payload and quote-
        // family cross-projections already carry.
        for uf in UnquoteForm::ALL {
            let via_round_trip = uf
                .sexp_shape()
                .as_unquote_form()
                .expect("every UnquoteForm round-trips through the embed/project pair")
                .marker();
            assert_eq!(
                via_round_trip,
                uf.marker(),
                "UnquoteForm::{uf:?}.marker() drifted from sexp_shape().as_unquote_form().marker() — embed/project must preserve marker coherence",
            );
        }
    }

    // --- MacroDefHead closed-set FromStr + UnknownMacroDefHead lift ---
    //
    // Same posture as `unquote_form_*` / `sexp_shape_*` /
    // `atom_kind_*` / `quote_form_*`: pin the four contract laws of the
    // closed-set (ALL, projection, FromStr, Unknown*) quadruple so the
    // typed surface and the rendered diagnostic literal cannot drift,
    // and the open-by-design `from_keyword` face matches the
    // typed-error `FromStr` face byte-for-byte (the same closed-set
    // sweep, different rejection polarities).

    #[test]
    fn macro_def_head_all_is_unique_and_complete() {
        // Closed-set posture: `ALL` enumerates every reachable variant
        // EXACTLY ONCE — no duplicates, no omissions. The `[Self; 3]`
        // array literal in the declaration forces the arity at compile
        // time; this test catches the orthogonal failure modes — a
        // future variant added at the type without being added to ALL
        // (silently dropped from every consumer's sweep), or a typo
        // that duplicates an entry (silently double-counted). Same
        // truth-table pinning every sibling closed-set lift in the
        // workspace uses (SexpShape::ALL, AtomKind::ALL,
        // QuoteForm::ALL, UnquoteForm::ALL, RequestorKind::ALL,
        // ReceiptKind::ALL, ConditionKind::ALL, …).
        //
        // The `iter+map+collect+sort_unstable` quadruple this test
        // inlined pre-lift now binds at `<MacroDefHead as
        // ClosedSet>::sorted_labels()` — the canonical-ordered
        // candidate-list projection on the trait. Distinctness of the
        // sorted result is covered by
        // `assert_closed_set_well_formed::<MacroDefHead>()`.
        assert_eq!(MacroDefHead::ALL.len(), 3);
        assert_eq!(
            <MacroDefHead as tatara_closed_set::ClosedSet>::sorted_labels(),
            vec!["defcheck", "defmacro", "defpoint-template"],
            "MacroDefHead::ALL must cover all three macro-definition heads"
        );
    }

    #[test]
    fn macro_def_head_keyword_round_trips_through_from_str() {
        // Bidirectional `keyword` ↔ `FromStr` contract: for every
        // variant in ALL, `head.keyword().parse() == Ok(head)`. A
        // regression that drifts the (variant, literal) pairing at
        // ONE arm of `keyword` (e.g. typo `defpoint_template` with an
        // underscore instead of `defpoint-template` with a hyphen) OR
        // at the `FromStr` decode body (off-by-one, missing variant in
        // the sweep) fails-loudly here. The canonical-literal site is
        // singular (`keyword`) so the round-trip is the only way the
        // typed surface and the rendered diagnostic literal can drift
        // apart — pinning it here means they cannot.
        for head in MacroDefHead::ALL {
            let parsed: MacroDefHead = head
                .keyword()
                .parse()
                .expect("every ALL variant's keyword must round-trip through FromStr");
            assert_eq!(
                parsed,
                head,
                "FromStr({}) must round-trip to the same variant",
                head.keyword()
            );
        }
    }

    #[test]
    fn macro_def_head_from_keyword_matches_from_str_for_every_input() {
        // Cross-face contract: the `Option`-faced `from_keyword`
        // projection (`tatara_lisp::ast::Sexp::as_call_to_any`'s
        // decoder slot, signature `Fn(&str) -> Option<T>`) and the
        // typed-error-faced `FromStr` projection are the SAME closed-
        // set sweep with different rejection polarities. After the
        // lift `from_keyword` delegates to `parse().ok()`, so the
        // closed-set sweep lives at ONE site (the `FromStr` impl) and
        // both faces project the same accept/reject decision at every
        // input. Pinning this law means a future refactor that drifts
        // ONE face from the other (e.g., adding a fourth variant to
        // `keyword` but forgetting to bump `Self::ALL`, or branching
        // `from_keyword` against a hand-rolled match arm instead of
        // routing through the typed sweep) fails here.
        let inputs: &[&str] = &[
            // The three canonical heads — both faces accept.
            "defmacro",
            "defpoint-template",
            "defcheck",
            // Non-canonical capitalizations — both faces reject.
            "Defmacro",
            "DEFCHECK",
            "DefpointTemplate",
            // Near misses — both faces reject.
            "defmacroo",
            "defcheckk",
            "defpoint_template",
            "defpoint",
            "defpoint-templates",
            // Sibling authoring surfaces from other closed sets —
            // both faces reject (cross-set disjointness).
            "defmonitor",
            "defnotify",
            "defpoint",
            "defalertpolicy",
            // SexpShape labels (the structural-identity vocabulary on
            // a DIFFERENT axis) — both faces reject.
            "symbol",
            "list",
            "nil",
            // Punctuation from QuoteForm / UnquoteForm vocabularies —
            // both faces reject (closed sets live on disjoint axes).
            ",",
            ",@",
            "'",
            "`",
            // Edge cases — both faces reject.
            "",
            " ",
            " defmacro",
            "defmacro ",
        ];
        for s in inputs {
            let from_kw = MacroDefHead::from_keyword(s);
            let from_str = s.parse::<MacroDefHead>().ok();
            assert_eq!(
                from_kw,
                from_str,
                "`from_keyword` and `FromStr` must agree on {s:?}: from_keyword={from_kw:?}, FromStr={from_str:?}",
            );
        }
    }

    #[test]
    fn unknown_macro_def_head_carries_offending_input_verbatim() {
        // Operator-facing diagnostic contract: the offending input
        // lands in the typed error verbatim — no normalization, no
        // truncation, no whitespace coercion. Pin the exact
        // `#[error(...)]` rendering AND the typed `.0` field
        // projection so a future refactor that normalizes (e.g.
        // `.trim()` / `.to_ascii_lowercase()`) before building the
        // error or that drops the input fails-loudly here. Symmetric
        // to every sibling `Unknown*` carrier in the workspace
        // ([`UnknownSexpShape`], [`crate::ast::UnknownAtomKind`],
        // [`UnknownUnquoteForm`], [`crate::ast::UnknownQuoteForm`],
        // `tatara_process::allocation::UnknownRequestorKind`, …).
        let err: UnknownMacroDefHead = "Defmacro"
            .parse::<MacroDefHead>()
            .expect_err("capitalized `Defmacro` is not a canonical macro-definition head");
        assert_eq!(err.0, "Defmacro");
        assert_eq!(format!("{err}"), "unknown macro definition head: Defmacro");

        let err: UnknownMacroDefHead = "defmacroo"
            .parse::<MacroDefHead>()
            .expect_err("`defmacroo` is not a canonical macro-definition head");
        assert_eq!(err.0, "defmacroo");
        assert_eq!(format!("{err}"), "unknown macro definition head: defmacroo");

        let err: UnknownMacroDefHead = ""
            .parse::<MacroDefHead>()
            .expect_err("empty input must NOT decode to a MacroDefHead");
        assert_eq!(err.0, "");
        assert_eq!(format!("{err}"), "unknown macro definition head: ");

        // Whitespace-padded canonical keyword MUST reject — the
        // typed identity is byte-exact, the offending input is
        // returned verbatim with its padding intact (not trimmed).
        // The rendered diagnostic preserves the leading space, so
        // the bad value reaches the operator unmolested.
        let err: UnknownMacroDefHead = " defmacro"
            .parse::<MacroDefHead>()
            .expect_err("leading-space `defmacro` must reject — typed identity is byte-exact");
        assert_eq!(err.0, " defmacro");
        assert_eq!(
            format!("{err}"),
            "unknown macro definition head:  defmacro",
            "leading whitespace is preserved verbatim in the rendered diagnostic",
        );
    }

    #[test]
    fn macro_def_head_from_str_rejects_cross_axis_vocabularies() {
        // Cross-axis guard: a MacroDefHead is the head keyword of a
        // `(defmacro …)`-shaped form — distinct from every other
        // closed-set vocabulary in this crate. A `FromStr` that
        // silently accepted a SexpShape label, an UnquoteForm marker,
        // a QuoteForm prefix, or an AtomKind label would corrupt the
        // typed identity at the macro-definition-head boundary. Pin
        // BOTH directions: the three canonical keywords decode
        // through MacroDefHead, the sibling closed-set vocabularies
        // do NOT.
        assert_eq!(
            "defmacro".parse::<MacroDefHead>().unwrap(),
            MacroDefHead::Defmacro
        );
        assert_eq!(
            "defpoint-template".parse::<MacroDefHead>().unwrap(),
            MacroDefHead::DefpointTemplate
        );
        assert_eq!(
            "defcheck".parse::<MacroDefHead>().unwrap(),
            MacroDefHead::Defcheck
        );

        // SexpShape labels — the structural-identity vocabulary
        // (twelve outer Sexp shapes) — share NO labels with the
        // macro-definition-head vocabulary. All must reject.
        for shape in SexpShape::ALL {
            assert!(
                shape.label().parse::<MacroDefHead>().is_err(),
                "SexpShape::{shape:?} label `{}` must NOT decode as a MacroDefHead",
                shape.label(),
            );
        }

        // UnquoteForm punctuation markers (`,` / `,@`) belong to the
        // template-marker axis — they MUST reject here because
        // MacroDefHead is on the symbol-keyword axis.
        for form in UnquoteForm::ALL {
            assert!(
                form.marker().parse::<MacroDefHead>().is_err(),
                "UnquoteForm marker `{}` must NOT decode as a MacroDefHead",
                form.marker(),
            );
        }

        // The `defpoint` authoring-surface keyword names a
        // `(defpoint …)` definition form — NOT a definition-template
        // form. The two are intentionally disjoint: `defpoint` is a
        // tatara-process domain authoring head, `defpoint-template`
        // is a parameterized-template head on the same surface.
        // Pinning the rejection here keeps the two from drifting.
        assert!("defpoint".parse::<MacroDefHead>().is_err());
        assert!("defmonitor".parse::<MacroDefHead>().is_err());
        assert!("defnotify".parse::<MacroDefHead>().is_err());
        assert!("defalertpolicy".parse::<MacroDefHead>().is_err());

        // Common-Lisp-style aliases the substrate does NOT admit.
        // Pinning these rejects keeps a future refactor from
        // silently extending the vocabulary without bumping
        // `Self::ALL` first.
        assert!("def-macro".parse::<MacroDefHead>().is_err());
        assert!("defun".parse::<MacroDefHead>().is_err());
        assert!("define-syntax".parse::<MacroDefHead>().is_err());
    }

    #[test]
    fn macro_def_head_is_well_formed_closed_set() {
        // Structural contract: MacroDefHead's three variants are
        // pairwise distinct, round-trip through the trait's `label` ↔
        // `parse_label`, and reject the empty string — the
        // workspace-wide `assert_closed_set_well_formed::<T>()` testkit
        // pinned across every `tatara-process` closed-set implementor
        // AND every prior tatara-lisp retrofit (`AtomKind`, `QuoteForm`).
        // The substrate-level assertion runs on the auto-derived
        // `impl ClosedSet for MacroDefHead` emitted by
        // `#[derive(tatara_closed_set::DeriveClosedSet)]` — a regression
        // that drifts the derive's `make_unknown` delegation, the
        // `via = "keyword"` projection (`"defmacro"` /
        // `"defpoint-template"` / `"defcheck"`), or the variant
        // listing forced through `Self::ALL` fails-loudly here in
        // isolation from the per-variant truth tables above.
        tatara_closed_set::assert_closed_set_well_formed::<MacroDefHead>();
    }

    #[test]
    fn unquote_form_is_well_formed_closed_set() {
        // Structural contract: UnquoteForm's two variants are pairwise
        // distinct, round-trip through the trait's `label` ↔
        // `parse_label`, and reject the empty string. The substrate-
        // level assertion runs on the auto-derived `impl ClosedSet
        // for UnquoteForm` emitted by
        // `#[derive(tatara_closed_set::DeriveClosedSet)]` — a regression
        // that drifts the `via = "marker"` projection (`","` /
        // `",@"`) or conflates the punctuation-axis vocabulary with
        // the structural-axis SexpShape vocabulary
        // (`"unquote"` / `"unquote-splice"`) fails-loudly here. The
        // cross-axis disjointness check stays at
        // `unquote_form_from_str_rejects_sexp_shape_labels_on_template_marker_axis`;
        // THIS test pins the in-axis well-formedness floor.
        tatara_closed_set::assert_closed_set_well_formed::<UnquoteForm>();
    }

    #[test]
    fn kwarg_path_kind_is_well_formed_closed_set() {
        // Structural contract: KwargPathKind's three variants are
        // pairwise distinct, round-trip through the trait's `label` ↔
        // `parse_label`, and reject the empty string. The substrate-
        // level assertion runs on the auto-derived `impl ClosedSet
        // for KwargPathKind` emitted by
        // `#[derive(tatara_closed_set::DeriveClosedSet)]` — a regression
        // that drifts the `via = "label"` projection (`"named"` /
        // `"item"` / `"slot"`) or the variant listing forced through
        // `Self::ALL` fails-loudly here.
        tatara_closed_set::assert_closed_set_well_formed::<KwargPathKind>();
    }

    #[test]
    fn expected_kwarg_shape_is_well_formed_closed_set() {
        // Structural contract: ExpectedKwargShape's seven variants are
        // pairwise distinct, round-trip through the trait's `label` ↔
        // `parse_label`, and reject the empty string. The substrate-
        // level assertion runs on the auto-derived `impl ClosedSet
        // for ExpectedKwargShape` emitted by
        // `#[derive(tatara_closed_set::DeriveClosedSet)]` — a regression
        // that drifts the `via = "label"` projection (`"keyword"` /
        // `"string"` / `"int"` / `"number"` / `"bool"` / `"list"` /
        // `"list of strings"`) fails-loudly here.
        tatara_closed_set::assert_closed_set_well_formed::<ExpectedKwargShape>();
    }

    #[test]
    fn sexp_shape_is_well_formed_closed_set() {
        // Structural contract: SexpShape's twelve variants are
        // pairwise distinct, round-trip through the trait's `label` ↔
        // `parse_label`, and reject the empty string. The substrate-
        // level assertion runs on the auto-derived `impl ClosedSet
        // for SexpShape` emitted by
        // `#[derive(tatara_closed_set::DeriveClosedSet)]` — a regression
        // that drifts the `via = "label"` projection (`"nil"` /
        // `"symbol"` / `"keyword"` / `"string"` / `"int"` / `"float"`
        // / `"bool"` / `"list"` / `"quote"` / `"quasiquote"` /
        // `"unquote"` / `"unquote-splice"`) or the variant listing
        // forced through `Self::ALL` (cardinality 12 = every reachable
        // outer `Sexp` shape) fails-loudly here.
        tatara_closed_set::assert_closed_set_well_formed::<SexpShape>();
    }

    #[test]
    fn compiler_spec_io_stage_is_well_formed_closed_set() {
        // Structural contract: CompilerSpecIoStage's four variants are
        // pairwise distinct, round-trip through the trait's `label` ↔
        // `parse_label`, and reject the empty string. The substrate-
        // level assertion runs on the auto-derived `impl ClosedSet
        // for CompilerSpecIoStage` emitted by
        // `#[derive(tatara_closed_set::DeriveClosedSet)]` — a regression
        // that drifts the `via = "label"` projection (`"serialize"` /
        // `"write"` / `"read"` / `"deserialize"`) or the variant
        // listing forced through `Self::ALL` (cardinality 4 = every
        // reachable disk-persistence (operation, stage) pair) fails-
        // loudly here.
        //
        // Distinct from the sibling closed-set well-formedness assertions
        // above: this enum carries `#[closed_set(no_from_str)]`, so the
        // trait surface's `parse_label` keys on the SINGULAR label
        // (`"read"` → `LoadFromDiskRead`) while the inherent
        // `std::str::FromStr` impl below keys on the COMPOUND key
        // (`"load_from_disk: read"` → `LoadFromDiskRead`). The trait
        // surface's well-formedness floor — non-empty `ALL`, round-trip
        // through `label`, pairwise-distinct labels, empty-string
        // outside the set — STILL holds on the singular projection
        // because the four labels (`"serialize"` / `"write"` /
        // `"read"` / `"deserialize"`) ARE bijective with the four
        // variants by accident of the current closed set; the
        // compound-key shape is what `FromStr` enforces and is what
        // `compiler_spec_io_stage_compound_key_round_trips_through_from_str`
        // pins. The two surfaces are deliberately disjoint — the
        // `no_from_str` axis exists for exactly this case.
        tatara_closed_set::assert_closed_set_well_formed::<CompilerSpecIoStage>();
    }

    #[test]
    fn structural_kind_all_is_unique_and_complete() {
        // Cardinality + uniqueness floor for the structural-residual
        // carving's typed algebra: `StructuralKind::ALL` has exactly
        // TWO entries (`Nil`, `List`) and both are pairwise distinct.
        // Sibling of the substrate-wide `*_all_is_unique_and_complete`
        // truth-table shape carried by every closed-set implementor.
        assert_eq!(
            StructuralKind::ALL.len(),
            2,
            "StructuralKind::ALL must have exactly 2 entries (Nil + List)",
        );
        let mut seen = Vec::new();
        for sk in StructuralKind::ALL {
            assert!(
                !seen.contains(&sk),
                "StructuralKind::{sk:?} repeated in ALL — variants must be pairwise distinct",
            );
            seen.push(sk);
        }
    }

    #[test]
    fn structural_kind_sexp_shape_projects_canonical_variant_for_every_marker() {
        // Per-arm truth-table pin of the canonical (StructuralKind
        // variant, SexpShape variant) mapping: `StructuralKind::Nil →
        // SexpShape::Nil` and `StructuralKind::List → SexpShape::List`
        // byte-for-byte. Sibling of
        // `unquote_form_sexp_shape_emits_canonical_shape_for_every_marker`
        // on the residual-carving axis rather than the substitution-
        // subset axis.
        assert_eq!(
            StructuralKind::Nil.sexp_shape(),
            SexpShape::Nil,
            "StructuralKind::Nil.sexp_shape() drifted from SexpShape::Nil",
        );
        assert_eq!(
            StructuralKind::List.sexp_shape(),
            SexpShape::List,
            "StructuralKind::List.sexp_shape() drifted from SexpShape::List",
        );
    }

    #[test]
    fn structural_kind_sexp_shape_round_trips_through_as_structural_kind() {
        // The embed/project section law on the structural-residual
        // carving: `StructuralKind::sexp_shape(sk).as_structural_kind()
        // == Some(sk)` for every `sk: StructuralKind::ALL`. Proves the
        // (embed, project) pair is an `Iso(StructuralKind,
        // StructuralShape ⊂ SexpShape)` — the section is total on
        // `StructuralKind`'s carving. Sibling round-trip to
        // `atom_kind_sexp_shape_round_trips_through_as_atom_kind`
        // (on the 6-of-12 atomic-payload carving),
        // `quote_form_sexp_shape_round_trips_through_as_quote_form`
        // (on the 4-of-12 quote-family carving), AND
        // `unquote_form_sexp_shape_round_trips_through_as_unquote_form`
        // (on the 2-of-12 substitution-subset carving). Closes the
        // third and final closed-set CARVING of `SexpShape` — the
        // structural-residual — as a round-trip identity on the typed
        // algebra.
        for sk in StructuralKind::ALL {
            let shape = sk.sexp_shape();
            let recovered = shape.as_structural_kind();
            assert_eq!(
                recovered,
                Some(sk),
                "StructuralKind::{sk:?} did NOT round-trip — sexp_shape().as_structural_kind() must recover the typed marker",
            );
        }
    }

    #[test]
    fn as_structural_kind_projects_each_structural_shape_to_canonical_structural_kind_and_rejects_non_structural_shapes(
    ) {
        // Per-variant truth-table sweep across every `SexpShape::ALL`
        // entry — pins each variant's canonical mapping (the two
        // structural-residual shapes project to the matching
        // `StructuralKind`; every other shape — every atomic-payload
        // arm AND every quote-family wrapper — projects to `None`)
        // byte-for-byte. Sibling sweep to
        // `as_atom_kind_projects_each_atom_shape_to_canonical_atom_kind_and_rejects_non_atom_shapes`,
        // `as_quote_form_projects_each_quote_shape_to_canonical_quote_form_and_rejects_non_quote_shapes`,
        // and
        // `as_unquote_form_projects_each_unquote_shape_to_canonical_unquote_form_and_rejects_non_unquote_shapes`
        // on the structural-residual carving axis.
        for shape in SexpShape::ALL {
            let projected = shape.as_structural_kind();
            let expected = match shape {
                SexpShape::Nil => Some(StructuralKind::Nil),
                SexpShape::List => Some(StructuralKind::List),
                SexpShape::Symbol
                | SexpShape::Keyword
                | SexpShape::String
                | SexpShape::Int
                | SexpShape::Float
                | SexpShape::Bool
                | SexpShape::Quote
                | SexpShape::Quasiquote
                | SexpShape::Unquote
                | SexpShape::UnquoteSplice => None,
            };
            assert_eq!(
                projected, expected,
                "SexpShape::{shape:?}.as_structural_kind() drifted from canonical mapping",
            );
        }
    }

    #[test]
    fn structural_kind_hash_discriminator_pins_legacy_cache_key_bytes() {
        // CACHE-KEY CONTRACT: pre-lift `Hash for Sexp` used the literal
        // byte values 0 for `Sexp::Nil` and 2 for `Sexp::List(_)` as
        // the two structural-residual arm discriminators. The
        // macro-expansion cache (`Expander::cache`) keys on Hash;
        // ANY change to a discriminator byte silently invalidates
        // every cached expansion across the substrate AND risks
        // collision with the reserved bytes the two sibling closed-
        // set carvings use (`1u8` for the `Sexp::Atom(_)` outer-carve
        // marker, `3..=6` for the quote-family via
        // `crate::ast::QuoteForm::hash_discriminator`). Pin the two
        // legacy values explicitly so a regression that re-numbers
        // them surfaces immediately — the `StructuralKind` algebra
        // MUST preserve the prior byte mapping bit-for-bit. Sibling
        // posture to
        // `atom_kind_hash_discriminator_pins_legacy_atom_cache_key_bytes`
        // on the atomic-payload axis (nested inner) AND
        // `quote_form_hash_discriminator_pins_legacy_cache_key_bytes`
        // on the quote-family axis (outer `Sexp` level).
        assert_eq!(StructuralKind::Nil.hash_discriminator(), 0);
        assert_eq!(StructuralKind::List.hash_discriminator(), 2);
    }

    #[test]
    fn structural_kind_hash_discriminator_bytes_are_pairwise_disjoint() {
        // Closed-set injectivity: the two discriminator bytes must
        // partition their subset of the outer-`Sexp` discriminator
        // space injectively so `Sexp::Nil` and `Sexp::List(_)` never
        // produce the SAME hash discriminator — a violation here
        // means the cache could conflate the empty-result marker
        // with the empty-list container. Sibling pin to
        // `atom_kind_hash_discriminator_bytes_are_pairwise_disjoint`
        // on the atomic-payload axis.
        let bytes: Vec<u8> = StructuralKind::ALL
            .iter()
            .map(|sk| sk.hash_discriminator())
            .collect();
        let mut sorted = bytes.clone();
        sorted.sort_unstable();
        let mut deduped = sorted.clone();
        deduped.dedup();
        assert_eq!(
            sorted, deduped,
            "StructuralKind hash discriminator bytes must be pairwise disjoint",
        );
        assert_eq!(sorted, vec![0, 2]);
    }

    #[test]
    fn structural_kind_hash_discriminator_disjoint_from_atom_outer_carve_byte_and_quote_form_hash_discriminator_partition(
    ) {
        // JOINT PARTITION CONTRACT: the outer-`Sexp` discriminator
        // space `{0, 1, 2, 3, 4, 5, 6}` MUST partition across the
        // three closed-set carvings AND the atomic-carve outer
        // marker byte with NO overlap — the substrate's cache-key
        // prefix-uniqueness contract binds bit-for-bit against this
        // partition. This test pins the disjointness of
        // `StructuralKind::hash_discriminator`'s `{0, 2}` against the
        // atomic-carve outer marker byte `1u8` (single-arm literal
        // inside `Hash for Sexp`) AND against
        // `crate::ast::QuoteForm::hash_discriminator`'s `{3, 4, 5,
        // 6}`. A regression that drifts ANY of the three carvings'
        // discriminator arms into another's byte space (e.g. a
        // future refactor that re-numbers `StructuralKind::List` to
        // `1u8`) surfaces here — the prefix-uniqueness contract
        // becomes a compile-time-verified theorem across the joint
        // partition, not a per-carving isolated invariant. Companion
        // to the on-axis `structural_kind_hash_discriminator_bytes_are_pairwise_disjoint`
        // pin (which enforces intra-carving injectivity); together
        // they close the three-carving-plus-atom-marker joint
        // disjointness contract.
        // Route the atomic-carve outer marker byte through
        // `crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR` (the typed
        // substrate primitive on the closed-set atomic-payload
        // algebra) rather than through a duplicated local `const
        // ATOM_OUTER_CARVE_BYTE: u8 = 1` fixture — the pre-lift local
        // const named the byte at ONE test site with no algebra
        // provenance, so a rename or renumbering at the algebra
        // required an inline byte drift at every joint-partition
        // fixture. Post-lift the byte lives at ONE
        // `pub(crate) const` on the [`crate::ast::AtomKind`] algebra;
        // this test's disjointness contract binds against the typed
        // constant so a regression that renumbers the primitive
        // fails-loudly at THIS test alongside the shape-level
        // collapse test.
        let structural: Vec<u8> = StructuralKind::ALL
            .iter()
            .map(|sk| sk.hash_discriminator())
            .collect();
        let quote_family: Vec<u8> = crate::ast::QuoteForm::ALL
            .iter()
            .map(|qf| qf.hash_discriminator())
            .collect();
        for byte in &structural {
            assert_ne!(
                *byte,
                crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR,
                "StructuralKind::hash_discriminator collided with the atomic-carve outer marker byte {marker}",
                marker = crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR,
            );
            assert!(
                !quote_family.contains(byte),
                "StructuralKind::hash_discriminator byte {byte} collided with QuoteForm::hash_discriminator partition {quote_family:?}",
            );
        }
        let mut union: Vec<u8> = structural
            .iter()
            .copied()
            .chain(std::iter::once(
                crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR,
            ))
            .chain(quote_family.iter().copied())
            .collect();
        union.sort_unstable();
        let mut deduped = union.clone();
        deduped.dedup();
        assert_eq!(
            union, deduped,
            "the three-carving-plus-atom-marker joint discriminator space {union:?} must partition without overlap",
        );
        assert_eq!(union, vec![0, 1, 2, 3, 4, 5, 6]);
    }

    #[test]
    fn structural_kind_hash_discriminators_pin_legacy_cache_key_bytes() {
        // Pin each per-role `pub(crate) const` at its exact canonical
        // `u8` byte. Sibling of
        // `structural_kind_hash_discriminator_pins_legacy_cache_key_bytes`
        // (which pins the method's projection) — this pin asserts the
        // `pub(crate) const` value itself, so a regression that drifts
        // the constant but leaves the method's arm literal in place
        // (unlikely post-lift but structurally distinct) surfaces
        // here. The cache-key partition `{0, 2}` is load-bearing for
        // the outer [`Hash for Sexp`](crate::ast::Sexp) prefix-
        // uniqueness contract — a `2u8` drift to `1u8` would silently
        // collide `Sexp::List(_)` with the reserved atomic-carve
        // outer marker and mis-hash every List through the Atom
        // arm's cache slot.
        assert_eq!(StructuralKind::NIL_HASH_DISCRIMINATOR, 0);
        assert_eq!(StructuralKind::LIST_HASH_DISCRIMINATOR, 2);
    }

    #[test]
    fn structural_kind_hash_discriminator_routes_through_typed_per_role_constants() {
        // PATH-UNIFORMITY: `Self::hash_discriminator(self)` returns
        // the per-role `pub(crate) const` byte-for-byte per variant,
        // catching a regression that reverts ONE arm to an inline
        // `0` / `2` `u8` literal (or drifts one arm's byte silently).
        // Sibling posture to
        // `atom_kind_hash_discriminator_routes_through_typed_per_role_constants`
        // on the atomic-payload sub-carving AND to
        // `quote_form_hash_discriminator_routes_through_typed_per_role_constants`
        // on the quote-family sub-carving of the SAME outer-`Sexp`
        // Hash body.
        for (kind, expected) in [
            (StructuralKind::Nil, StructuralKind::NIL_HASH_DISCRIMINATOR),
            (
                StructuralKind::List,
                StructuralKind::LIST_HASH_DISCRIMINATOR,
            ),
        ] {
            let actual = kind.hash_discriminator();
            assert_eq!(
                actual, expected,
                "StructuralKind::{kind:?}.hash_discriminator() `{actual}` \
                 drifted from per-role constant `{expected}` — the arm \
                 must route through the typed `pub(crate) const` rather \
                 than an inline `u8` literal",
            );
        }
    }

    #[test]
    fn structural_kind_hash_discriminators_has_expected_cardinality() {
        // Cardinality contract: `Self::HASH_DISCRIMINATORS.len() == 2`
        // — pinned at the declaration site by rustc's forced-arity
        // check on `[u8; 2]`. This test surfaces the arity as a
        // fail-loud runtime pin so a future refactor that switches
        // the array type to `&[u8]` (dropping the compile-time arity
        // forcing) doesn't silently loosen the closed-set discipline
        // the family relies on. Sibling posture to
        // `structural_kind_labels_has_expected_cardinality` on the
        // diagnostic label axis of the SAME closed set, and to
        // `atom_kind_hash_discriminators_has_expected_cardinality` +
        // `quote_form_hash_discriminators_has_expected_cardinality`
        // on the two sibling carvings' cache-key-byte peers.
        assert_eq!(
            StructuralKind::HASH_DISCRIMINATORS.len(),
            2,
            "StructuralKind::HASH_DISCRIMINATORS cardinality drifted \
             from 2 — the closed structural-residual domain admits \
             exactly two kinds by construction; a third extension \
             surfaces here"
        );
    }

    #[test]
    fn structural_kind_hash_discriminators_align_with_all_by_index() {
        // ALIGNMENT CONTRACT: `Self::HASH_DISCRIMINATORS[i] ==
        // Self::ALL[i].hash_discriminator()` element-wise. Pins that
        // the typed variant ALL and the `u8` HASH_DISCRIMINATORS ALL
        // stay in lockstep under any reorder — a regression that
        // reorders ONE array without reordering the other silently
        // misaligns every `zip(ALL, HASH_DISCRIMINATORS)` consumer.
        // Sibling posture to
        // `structural_kind_labels_align_with_all_by_index` on the
        // diagnostic label axis of the SAME closed set.
        for (i, kind) in StructuralKind::ALL.iter().enumerate() {
            assert_eq!(
                StructuralKind::HASH_DISCRIMINATORS[i],
                kind.hash_discriminator(),
                "StructuralKind::HASH_DISCRIMINATORS[{i}] `{disc}` \
                 drifted from StructuralKind::ALL[{i}] ({kind:?}).hash_discriminator() \
                 `{via_variant}` — the canonical declaration order of \
                 the ALL array and the hash_discriminator projection \
                 must match element-wise",
                disc = StructuralKind::HASH_DISCRIMINATORS[i],
                via_variant = kind.hash_discriminator(),
            );
        }
    }

    #[test]
    fn structural_kind_hash_discriminators_pairwise_distinct() {
        // PAIRWISE DISJOINTNESS: every entry of the
        // `HASH_DISCRIMINATORS` array must differ so the outer-`Sexp`
        // Hash body cannot route two structural-residual variants
        // through the same cache-key byte — a collision would
        // silently mis-hash two structurally-distinct residual shapes
        // (`Sexp::Nil` and `Sexp::List(_)`) to the same
        // `Expander::cache` slot. Family-wide sweep over
        // `HASH_DISCRIMINATORS × HASH_DISCRIMINATORS` — supersedes any
        // per-pair pin and picks up new discriminators mechanically.
        // Sibling posture to
        // `structural_kind_hash_discriminator_bytes_are_pairwise_disjoint`
        // (which sweeps via the projection) — this sweep pins the
        // array itself so a regression that lifts a fresh entry with
        // a colliding byte surfaces at the ALL sweep.
        for (i, a) in StructuralKind::HASH_DISCRIMINATORS.iter().enumerate() {
            for (j, b) in StructuralKind::HASH_DISCRIMINATORS.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "StructuralKind::HASH_DISCRIMINATORS[{i}] `{a}` \
                     collides with StructuralKind::HASH_DISCRIMINATORS[{j}] \
                     `{b}` — the outer-Sexp Hash body's cache-key \
                     partition would route two structural-residual \
                     variants through the same slot"
                );
            }
        }
    }

    #[test]
    fn structural_kind_label_matches_sexp_shape_label_via_composition() {
        // Composition-routing pin: for every `sk: StructuralKind`,
        // `sk.label()` and `sk.sexp_shape().label()` agree byte-for-
        // byte AND at the SAME `&'static str` pointer (the
        // composition returns the SAME literal `SexpShape::label`
        // emits, without a parallel arm-table on the subset). A
        // regression that re-inlines the two arms as a parallel
        // match-table (`Self::Nil => "nil"`, `Self::List => "list"`)
        // still passes the label-equality sweep but fails the pointer
        // pin — the residual-carving's label vocabulary is no longer
        // derived from the superset's canonical site. Sibling-shape
        // pin to `atom_kind_label_routes_through_sexp_shape_label_via_sexp_shape_projection`
        // (the 6-of-12 atomic-payload carving) and
        // `unquote_form_marker_routes_through_to_quote_form_prefix_via_composition`
        // (the 2-of-4 substitution-subset carving).
        for sk in StructuralKind::ALL {
            let from_direct = sk.label();
            let from_composition = sk.sexp_shape().label();
            assert_eq!(
                from_direct, from_composition,
                "StructuralKind::{sk:?}.label() drifted from .sexp_shape().label() — the residual carving's label vocabulary is no longer derived from the superset's canonical site",
            );
            assert!(
                std::ptr::eq(from_direct.as_ptr(), from_composition.as_ptr()),
                "StructuralKind::{sk:?}.label() and .sexp_shape().label() must point at the SAME `&'static str` — a parallel inline table has a different pointer",
            );
        }
    }

    #[test]
    fn structural_kind_label_round_trips_through_from_str() {
        // `label` ↔ `FromStr` round-trip pin: for every `sk:
        // StructuralKind::ALL`, `sk.label().parse::<StructuralKind>()
        // == Ok(sk)`. The auto-derived `impl FromStr` (via
        // `#[derive(ClosedSet)]` + the default `parse_label`) sweeps
        // over `Self::ALL` keyed on `self.label()`, so a drift in
        // either direction (a label typo or a variant-set drift)
        // surfaces here. Sibling round-trip to
        // `sexp_shape_label_round_trips_through_from_str` and
        // `atom_kind_label_round_trips_through_from_str`.
        for sk in StructuralKind::ALL {
            let parsed = sk.label().parse::<StructuralKind>();
            assert_eq!(
                parsed,
                Ok(sk),
                "StructuralKind::{sk:?}.label() must round-trip through FromStr",
            );
        }
    }

    #[test]
    fn structural_kind_from_str_rejects_non_structural_sexp_shape_labels() {
        // Cross-axis rejection pin: the `FromStr` decode on
        // StructuralKind MUST reject every `SexpShape` label that lies
        // OUTSIDE the residual carving (the ten `symbol` / `keyword` /
        // `string` / `int` / `float` / `bool` / `quote` / `quasiquote`
        // / `unquote` / `unquote-splice` labels — every atomic-payload
        // AND quote-family label). The two residual labels (`nil`,
        // `list`) accept because they lie INSIDE the carving; every
        // other `SexpShape` label rejects with `Err(UnknownStructuralKind)`.
        // Sibling of
        // `unquote_form_from_str_rejects_sexp_shape_labels_on_template_marker_axis`
        // and
        // `sexp_shape_from_str_accepts_only_canonical_labels` — the
        // pattern the substrate carries at every closed-set-carving
        // boundary.
        let residual_labels: Vec<&'static str> =
            StructuralKind::ALL.iter().map(|sk| sk.label()).collect();
        for shape in SexpShape::ALL {
            let label = shape.label();
            let parsed = label.parse::<StructuralKind>();
            if residual_labels.contains(&label) {
                assert!(
                    parsed.is_ok(),
                    "SexpShape::{shape:?}.label() = {label:?} is a residual label — StructuralKind::from_str must accept",
                );
            } else {
                assert!(
                    parsed.is_err(),
                    "SexpShape::{shape:?}.label() = {label:?} lies outside the residual carving — StructuralKind::from_str must reject",
                );
            }
        }
    }

    #[test]
    fn structural_kind_is_well_formed_closed_set() {
        // Structural contract: StructuralKind's two variants are
        // pairwise distinct, round-trip through the trait's `label` ↔
        // `parse_label`, and reject the empty string — the
        // workspace-wide `assert_closed_set_well_formed::<T>()` testkit
        // pinned across every prior closed-set implementor
        // (`AtomKind`, `QuoteForm`, `UnquoteForm`, `SexpShape`,
        // `MacroDefHead`, `ExpectedKwargShape`, `KwargPathKind`,
        // `CompilerSpecIoStage`). The substrate-level assertion runs
        // on the auto-derived `impl ClosedSet for StructuralKind`
        // emitted by `#[derive(tatara_closed_set::DeriveClosedSet)]` — a
        // regression that drifts the `via = "label"` projection
        // (`"nil"` / `"list"`) or the variant listing forced through
        // `Self::ALL` (cardinality 2 = every structural-residual
        // outer shape) fails-loudly here.
        tatara_closed_set::assert_closed_set_well_formed::<StructuralKind>();
    }

    #[test]
    fn structural_kind_per_role_labels_alias_sexp_shape_per_role_labels_byte_for_byte() {
        // ALIAS CONTRACT: pin every one of the two per-role `pub const
        // StructuralKind::*_LABEL` aliases equals the corresponding
        // `pub const SexpShape::*_LABEL` byte-for-byte — so the
        // StructuralKind ⊂ SexpShape marker-vocabulary containment
        // routes through the typed `pub const StructuralKind::V_LABEL:
        // &'static str = SexpShape::V_LABEL` alias chain rather than
        // through two independent literal-discipline sites. Sibling-
        // shape pin to
        // `atom_kind_per_role_labels_alias_sexp_shape_per_role_labels_byte_for_byte`
        // on the peer 6-of-12 atomic-payload carving — the two pins
        // together bind the two SexpShape sub-carvings' per-role
        // alias chains at the SAME shape (parent's canonical bytes on
        // the RHS, subset's alias on the LHS). A regression that
        // renames the SexpShape side without updating the
        // StructuralKind alias pointing at it fails-loudly here with
        // the exact axis identified (NIL / LIST); a regression that
        // re-inlines the StructuralKind constant to a fresh literal
        // still passes this pin but loses the alias-chain typing
        // (which is what
        // `structural_kind_label_arms_route_through_per_role_labels_for_every_variant`
        // + `structural_kind_labels_align_with_all_by_index` catch in
        // combination).
        assert_eq!(StructuralKind::NIL_LABEL, SexpShape::NIL_LABEL);
        assert_eq!(StructuralKind::LIST_LABEL, SexpShape::LIST_LABEL);
    }

    #[test]
    fn structural_kind_label_arms_route_through_per_role_labels_for_every_variant() {
        // PATH-UNIFORMITY: `StructuralKind::V.label()` MUST equal the
        // per-role `pub const StructuralKind::V_LABEL` for every `v:
        // StructuralKind`. Pre-lift the two structural-residual marker
        // bytes were reachable through `StructuralKind::label` (the
        // composition `self.sexp_shape().label()` — routing into
        // `SexpShape::*_LABEL`) OR through direct
        // `SexpShape::*_LABEL` reach-across; post-lift each variant's
        // canonical bytes are reachable through the per-role
        // `StructuralKind::*_LABEL` alias too. Pin the byte-equality
        // between the runtime projection and the compile-time alias
        // so a regression that renames the alias without updating the
        // arm (or vice versa) fails-loudly at the exact axis.
        //
        // Sibling-shape pin to
        // `atom_kind_label_arms_route_through_per_role_labels_for_every_variant`
        // on the peer 6-of-12 atomic-payload carving — the two pins
        // together bind BOTH SexpShape sub-carvings' per-role alias
        // chains against their respective label projections.
        assert_eq!(StructuralKind::Nil.label(), StructuralKind::NIL_LABEL);
        assert_eq!(StructuralKind::List.label(), StructuralKind::LIST_LABEL);
    }

    #[test]
    fn structural_kind_labels_has_expected_cardinality() {
        // Cardinality pin: `LABELS.len() == 2` matches `ALL.len()` so
        // a refactor that loosens the type to `&'static [&'static
        // str]` fails HERE (the `[_; 2]` slot cannot be sliced
        // silently), and a variant added to `ALL` without a matching
        // `LABELS` row fails the pair-arity gate at the array literal
        // itself before this test even runs. The pin doubles as an
        // operator-visible mark of the family's cardinality across
        // the substrate — two structural-residual markers, matching
        // the two-arm carving of the parent `SexpShape::LABELS` (the
        // residual subset of the twelve canonical outer-shape labels).
        assert_eq!(StructuralKind::LABELS.len(), 2);
        assert_eq!(StructuralKind::LABELS.len(), StructuralKind::ALL.len());
    }

    #[test]
    fn structural_kind_labels_align_with_all_by_index() {
        // ALIGNMENT PIN: sweep `LABELS[i] == ALL[i].label()` so any
        // `zip(ALL, LABELS)` consumer reads a coherent (variant,
        // label) pair off ONE forced-arity array pair. The
        // declaration-order pin makes a family-wide consumer that
        // walks the ALL / LABELS pair in lockstep (an LSP completion
        // bar keyed on `StructuralKind::LABELS`, a Sekiban metric
        // emitter labeling `tatara_lisp_structural_shape_total{kind}`
        // by the per-index label) read one canonical (variant, bytes)
        // pair per slot rather than routing through per-consumer
        // paired-iteration. A regression that reorders LABELS without
        // also reordering ALL (or vice versa) fails-loudly at the
        // exact index that drifted.
        assert_eq!(StructuralKind::LABELS.len(), StructuralKind::ALL.len());
        for (i, kind) in StructuralKind::ALL.iter().enumerate() {
            assert_eq!(
                StructuralKind::LABELS[i],
                kind.label(),
                "StructuralKind::LABELS[{i}] `{lbl}` drifted from \
                 StructuralKind::ALL[{i}].label() `{via_variant}` — \
                 the canonical ALL ordering and the LABELS ordering \
                 must match element-wise",
                lbl = StructuralKind::LABELS[i],
                via_variant = kind.label(),
            );
        }
    }

    #[test]
    fn structural_kind_labels_pairwise_distinct() {
        // 2x2 pairwise sweep so a collision between the two labels
        // (which would silently degrade two distinct structural-
        // residual markers to the SAME diagnostic bytes and violate
        // the closed-set FromStr round-trip) fails-loudly at the
        // exact pair. Distinctness is already enforced structurally
        // by `assert_closed_set_well_formed::<StructuralKind>()`
        // (clause 3), so this pin is a secondary guard focused on
        // the per-role `pub const` surface directly rather than the
        // runtime projection through the trait's default `labels()`.
        for (i, a) in StructuralKind::LABELS.iter().enumerate() {
            for (j, b) in StructuralKind::LABELS.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "StructuralKind::LABELS[{i}] ({a:?}) collides with \
                     StructuralKind::LABELS[{j}] ({b:?}) — two distinct \
                     structural-residual markers cannot share \
                     diagnostic bytes",
                );
            }
        }
    }

    #[test]
    fn structural_kind_labels_match_sexp_shape_labels_element_wise_via_alias_chain() {
        // CROSS-AXIS PIN: sweep `StructuralKind::LABELS[i] ==
        // StructuralKind::ALL[i].sexp_shape().label()` so the ALL
        // array projected through the [`Self::sexp_shape`] embed +
        // [`SexpShape::label`] composition agrees with LABELS byte-
        // for-byte at every index. The pin closes the alias-chain
        // identity at the family-wide array level: the LABELS array
        // is NOT a fresh literal table but the projection of ALL
        // through the composition, materialized once at declaration
        // time through the two per-role `pub const *_LABEL` aliases.
        // A regression that re-inlines LABELS to fresh literals still
        // passes the pairwise-distinct + cardinality + alignment
        // pins but drifts the alias chain — this pin catches that
        // drift by comparing against the composition on the SAME
        // ALL ordering.
        //
        // Sibling-shape pin to the peer 6-of-12 atomic-payload
        // carving's family-wide alias-chain pin (implicit in
        // `atom_kind_labels_align_with_all_by_index` +
        // `atom_kind_per_role_labels_alias_sexp_shape_per_role_labels_byte_for_byte`
        // together); this pin binds the 2-of-12 residual carving's
        // family-wide alias chain in ONE test at the family-wide
        // array level.
        for (i, kind) in StructuralKind::ALL.iter().enumerate() {
            assert_eq!(
                StructuralKind::LABELS[i],
                kind.sexp_shape().label(),
                "StructuralKind::LABELS[{i}] drifted from \
                 StructuralKind::ALL[{i}].sexp_shape().label() — the \
                 LABELS array must project through the sexp_shape + \
                 SexpShape::label composition byte-for-byte",
            );
        }
    }

    #[test]
    fn structural_kind_per_role_shapes_pin_canonical_sexp_shape_variants() {
        // PER-ROLE ALIAS CONTRACT: each `StructuralKind::*_SHAPE` per-
        // role `pub const` binds byte-for-byte to its canonical
        // `SexpShape` variant on the StructuralKind ⊂ SexpShape 2-of-12
        // carving. Pin so a regression that swaps ONE alias (e.g.
        // re-aims `LIST_SHAPE` at `SexpShape::Nil`) surfaces at rustc
        // / test time rather than as a silent operator-facing
        // diagnostic drift at every consumer keyed on the typed embed
        // target. Sibling posture to
        // `structural_kind_per_role_labels_alias_sexp_shape_per_role_labels_byte_for_byte`
        // on the diagnostic label axis of the SAME closed set — this
        // pin is the peer on the `SexpShape` embed-target axis.
        assert_eq!(StructuralKind::NIL_SHAPE, SexpShape::Nil);
        assert_eq!(StructuralKind::LIST_SHAPE, SexpShape::List);
    }

    #[test]
    fn structural_kind_shapes_has_expected_cardinality() {
        // CLOSED-SET CARDINALITY CONTRACT: `StructuralKind::SHAPES`
        // carries exactly TWO entries — one per variant in the
        // closed-set structural-residual carving. Runtime companion to
        // the `[SexpShape; 2]` type annotation's compile-time forced
        // arity. A regression that widens the array without adding a
        // matching per-role `*_SHAPE` alias would fail the
        // `[SexpShape; 2]` type check at rustc time; this runtime pin
        // catches a silent shrink or duplicate-arm coalesce. Sibling
        // posture to `structural_kind_labels_has_expected_cardinality`
        // and `structural_kind_hash_discriminators_has_expected_cardinality`
        // on the other two per-role axes of the SAME closed set.
        assert_eq!(StructuralKind::SHAPES.len(), 2);
        assert_eq!(StructuralKind::SHAPES.len(), StructuralKind::ALL.len());
    }

    #[test]
    fn structural_kind_shapes_align_with_all_by_index() {
        // ALIGNMENT CONTRACT: `Self::SHAPES[i] ==
        // Self::ALL[i].sexp_shape()` element-wise. Pins that the typed
        // variant ALL and the `SexpShape` SHAPES ALL stay in lockstep
        // under any reorder — a regression that reorders ONE array
        // without reordering the other silently misaligns every
        // `zip(ALL, SHAPES)` consumer that wants to project each
        // structural-residual variant to its canonical outer-shape
        // identity (LSP completion, `tatara-check` predicate over the
        // structural ⊂ outer partition, Sekiban audit-trail metric
        // jointly labeled by the embed target). Sibling posture to
        // `structural_kind_labels_align_with_all_by_index` and
        // `structural_kind_hash_discriminators_align_with_all_by_index`
        // on the other two per-role axes of the SAME closed set.
        for (i, kind) in StructuralKind::ALL.iter().enumerate() {
            assert_eq!(
                StructuralKind::SHAPES[i],
                kind.sexp_shape(),
                "StructuralKind::SHAPES[{i}] `{shape:?}` drifted from \
                 StructuralKind::ALL[{i}] ({kind:?}).sexp_shape() \
                 `{via_variant:?}` — the canonical declaration order \
                 of the ALL array and the sexp_shape projection must \
                 match element-wise",
                shape = StructuralKind::SHAPES[i],
                via_variant = kind.sexp_shape(),
            );
        }
    }

    #[test]
    fn structural_kind_shapes_align_with_all_by_index_through_as_structural_kind() {
        // ROUND-TRIP CONTRACT: `Self::SHAPES[i].as_structural_kind() ==
        // Some(Self::ALL[i])` element-wise. Pins the embed / project
        // section of the (`StructuralKind::sexp_shape`,
        // `SexpShape::as_structural_kind`) `Iso(StructuralKind,
        // StructuralShape ⊂ SexpShape)` as a family-wide array-indexed
        // law rather than as a per-variant assertion sweep. A
        // regression that drifts EITHER the `SHAPES` array entries OR
        // the peer inverse `as_structural_kind` arms silently breaks
        // the (embed, project) section — this pin catches both
        // directions at ONCE. Sibling posture to
        // `atom_kind_shapes_align_with_all_by_index_through_as_atom_kind`
        // on the peer 6-of-12 atomic-payload carving and
        // `quote_form_shapes_align_with_all_by_index_through_as_quote_form`
        // on the peer 4-of-12 quote-family carving — this pin closes
        // the third and final peer round-trip.
        for (i, kind) in StructuralKind::ALL.iter().enumerate() {
            assert_eq!(
                StructuralKind::SHAPES[i].as_structural_kind(),
                Some(*kind),
                "StructuralKind::SHAPES[{i}] `{shape:?}`.as_structural_kind() = \
                 {actual:?} drifted from Some(StructuralKind::ALL[{i}]) = \
                 Some({expected:?}) — the (SHAPES entry, ALL variant) \
                 round-trip through the peer inverse \
                 SexpShape::as_structural_kind must hold element-wise",
                shape = StructuralKind::SHAPES[i],
                actual = StructuralKind::SHAPES[i].as_structural_kind(),
                expected = kind,
            );
        }
    }

    #[test]
    fn structural_kind_sexp_shape_routes_through_typed_per_role_constants() {
        // ROUTING CONTRACT: `StructuralKind::sexp_shape()`'s two arms
        // bind through the per-role `pub const *_SHAPE` aliases rather
        // than through inline `SexpShape::X` literals. Pin so a
        // regression that re-inlines the two literals here (and gains
        // its own drift surface separate from the canonical per-role
        // alias site) surfaces immediately at variant equality.
        // Sibling posture to
        // `structural_kind_label_arms_route_through_per_role_labels_for_every_variant`
        // (which pins label routing through the per-role LABEL aliases)
        // and `atom_kind_sexp_shape_routes_through_typed_per_role_constants`
        // / `quote_form_sexp_shape_routes_through_typed_per_role_constants`
        // on the peer 6-of-12 atomic-payload and 4-of-12 quote-family
        // carvings.
        assert_eq!(StructuralKind::Nil.sexp_shape(), StructuralKind::NIL_SHAPE);
        assert_eq!(
            StructuralKind::List.sexp_shape(),
            StructuralKind::LIST_SHAPE
        );
    }

    #[test]
    fn structural_kind_shapes_pairwise_distinct() {
        // PAIRWISE DISJOINTNESS: every entry of the `SHAPES` array
        // must differ so the (StructuralKind variant, SexpShape embed
        // target) mapping stays injective — a collision would silently
        // route two distinct StructuralKind variants through the SAME
        // outer-shape identity, breaking the StructuralKind ⊂
        // SexpShape 2-of-12 carving. Family-wide sweep over `SHAPES ×
        // SHAPES` — supersedes any per-pair pin and picks up new embed
        // targets mechanically. Sibling posture to
        // `atom_kind_shapes_pairwise_distinct` and
        // `quote_form_shapes_pairwise_distinct` on the peer 6-of-12
        // atomic-payload and 4-of-12 quote-family carvings — this pin
        // closes the third and final peer pairwise-distinct sweep.
        for (i, a) in StructuralKind::SHAPES.iter().enumerate() {
            for (j, b) in StructuralKind::SHAPES.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "StructuralKind::SHAPES[{i}] `{a:?}` collides with \
                     StructuralKind::SHAPES[{j}] `{b:?}` — the \
                     StructuralKind ⊂ SexpShape 2-of-12 carving would \
                     route two structural-residual variants through the \
                     same outer-shape identity"
                );
            }
        }
    }

    #[test]
    fn sexp_shape_hash_discriminator_pins_legacy_outer_cache_key_bytes() {
        // CACHE-KEY CONTRACT (shape-level peer): the shape-level
        // `SexpShape::hash_discriminator` MUST project each of the twelve
        // outer-shape arms to the SAME outer cache-key byte the
        // corresponding `Sexp` variant surfaces through
        // `crate::ast::Sexp::hash_discriminator`. Pin the twelve-arm →
        // seven-byte collapse: Nil→0, {Symbol/Keyword/String/Int/Float/
        // Bool}→1 (the outer Atom marker byte; the per-atom-kind inner
        // byte lives INSIDE `Hash for Atom` via
        // `AtomKind::hash_discriminator`'s `{0..=5}`, NOT surfaced
        // through this shape-level method), List→2, Quote→3,
        // Quasiquote→4, Unquote→5, UnquoteSplice→6. Any regression that
        // renumbers a byte here silently drifts the outer-`Sexp` cache-
        // key partition since `Sexp::hash_discriminator` composes
        // through `self.shape().hash_discriminator()` post-lift.
        // Sibling posture to
        // `structural_kind_hash_discriminator_pins_legacy_cache_key_bytes`
        // on the 2-arm sub-carving, `crate::ast::AtomKind`'s
        // `atom_kind_hash_discriminator_pins_legacy_atom_cache_key_bytes`
        // on the 6-arm sub-carving, and
        // `crate::ast::QuoteForm`'s
        // `quote_form_hash_discriminator_pins_legacy_cache_key_bytes`
        // on the 4-arm sub-carving.
        assert_eq!(SexpShape::Nil.hash_discriminator(), 0);
        assert_eq!(SexpShape::Symbol.hash_discriminator(), 1);
        assert_eq!(SexpShape::Keyword.hash_discriminator(), 1);
        assert_eq!(SexpShape::String.hash_discriminator(), 1);
        assert_eq!(SexpShape::Int.hash_discriminator(), 1);
        assert_eq!(SexpShape::Float.hash_discriminator(), 1);
        assert_eq!(SexpShape::Bool.hash_discriminator(), 1);
        assert_eq!(SexpShape::List.hash_discriminator(), 2);
        assert_eq!(SexpShape::Quote.hash_discriminator(), 3);
        assert_eq!(SexpShape::Quasiquote.hash_discriminator(), 4);
        assert_eq!(SexpShape::Unquote.hash_discriminator(), 5);
        assert_eq!(SexpShape::UnquoteSplice.hash_discriminator(), 6);
    }

    #[test]
    fn sexp_shape_hash_discriminator_covers_outer_partition_zero_through_six() {
        // PARTITION-COMPLETENESS CONTRACT (shape-level peer): the
        // 12-arm sweep of `SexpShape::ALL` through
        // `SexpShape::hash_discriminator` MUST cover exactly the outer
        // cache-key partition `{0..=6}` — no byte outside the outer
        // partition, no byte inside missing. The projection is
        // surjective onto `{0..=6}` (every outer byte reached by at
        // least one shape arm) with the atomic-shape collapse
        // ({Symbol/Keyword/String/Int/Float/Bool} → 1) covering the
        // outer Atom marker byte. Sibling posture to
        // `sexp_hash_discriminator_partitions_the_full_outer_discriminator_space_zero_through_six`
        // on the outer-`Sexp` algebra — that pin binds the outer-Sexp
        // partition; this pin binds the shape-level partition. Post-
        // lift the two partitions coincide byte-for-byte through
        // `Sexp::hash_discriminator` = `self.shape().hash_discriminator()`.
        let outer_bytes: std::collections::BTreeSet<u8> = SexpShape::ALL
            .iter()
            .map(|shape| shape.hash_discriminator())
            .collect();
        let expected: std::collections::BTreeSet<u8> = (0u8..=6u8).collect();
        assert_eq!(
            outer_bytes, expected,
            "SexpShape::hash_discriminator must cover exactly the outer discriminator space {{0..=6}}",
        );
    }

    #[test]
    fn sexp_shape_hash_discriminator_atomic_arms_collapse_to_outer_atom_marker() {
        // OUTER-CARVING CONTRACT (shape-level atomic arm): every
        // `SexpShape` variant whose `as_atom_kind()` projection returns
        // `Some(_)` MUST project through `SexpShape::hash_discriminator`
        // to the SAME outer discriminator byte `1u8` — the atomic outer
        // arm is a single-byte marker on the outer partition, with the
        // per-atom-kind inner byte
        // (`crate::ast::AtomKind::hash_discriminator`'s `{0..=5}`)
        // nested INSIDE `Hash for Atom` — NOT surfaced through this
        // shape-level method. Pin the six-way collapse so a regression
        // that drifts ONE atomic-shape arm's outer routing (e.g. routes
        // `SexpShape::Int` to `7u8` inline) surfaces here immediately.
        // Sibling posture to
        // `sexp_hash_discriminator_atom_arm_collapses_over_every_atom_kind`
        // on the outer-`Sexp` algebra — that pin binds the outer-Sexp
        // atom-arm collapse; this pin binds the shape-level atomic-arm
        // collapse. Post-lift the two collapses coincide byte-for-byte
        // through `Sexp::hash_discriminator` =
        // `self.shape().hash_discriminator()`.
        for shape in SexpShape::ALL {
            if shape.as_atom_kind().is_some() {
                assert_eq!(
                    shape.hash_discriminator(),
                    crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR,
                    "SexpShape::{shape:?} is an atomic-payload shape but did not collapse to outer byte {marker}",
                    marker = crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR,
                );
            }
        }
    }

    #[test]
    fn sexp_shape_hash_discriminator_atomic_arms_route_through_atom_kind_outer_hash_discriminator()
    {
        // PATH-UNIFORMITY (shape-level atomic-carve outer marker):
        // for every `SexpShape` variant whose `as_atom_kind()`
        // projection returns `Some(_)`, `SexpShape::hash_discriminator`
        // MUST bind byte-for-byte to
        // `crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR` — the
        // atomic-carve outer marker binds through the typed
        // substrate primitive rather than through an inline `1u8`
        // literal (which is what pre-lift wrote at the six-arm
        // atomic collapse arm). Pin the routing-identity across the
        // closed set so a regression that reverts the atomic
        // collapse to `Self::Symbol | ... | Self::Bool => 1` (or
        // drifts the routing byte silently while leaving the const
        // in place) fails-loudly here. Sibling posture to
        // `sexp_shape_hash_discriminator_structural_arms_route_through_structural_kind`
        // on the structural-residual sub-carving AND
        // `sexp_shape_hash_discriminator_quote_family_arms_route_through_quote_form`
        // on the quote-family sub-carving — every one of the three
        // shape-level carvings' six-plus-two-plus-four arms routes
        // through the typed substrate primitive on its owning
        // closed-set algebra rather than an inline `u8` literal
        // scattered across `SexpShape::hash_discriminator`. Together
        // with the two pre-existing companion pins this pin closes
        // the shape-level projection's TWELVE-ARM routing across the
        // FOUR typed byte primitives (three sub-algebra methods +
        // the outer-Atom scalar) at ONE byte-equality contract per
        // arm.
        //
        // The atomic-carve outer marker is a SCALAR (single byte),
        // NOT an ALL-array sweep like the other two carvings —
        // reflected in the assertion body: all six atomic-payload
        // shapes assert against the SAME
        // `AtomKind::OUTER_HASH_DISCRIMINATOR` constant rather than
        // zip against a `HASH_DISCRIMINATORS` array. This scalar-vs-
        // array asymmetry is intrinsic to the carve semantics: all
        // six atomic-payload arms of `SexpShape` COLLAPSE to the
        // SAME outer byte (the outer-Sexp distinguisher is
        // variant-level: `Sexp::Atom(_)` vs the six sibling `Sexp`
        // variants); per-atom-kind specialisation lives at the
        // NESTED INNER `AtomKind::HASH_DISCRIMINATORS` carve inside
        // `Hash for Atom`.
        for shape in SexpShape::ALL {
            if shape.as_atom_kind().is_some() {
                assert_eq!(
                    shape.hash_discriminator(),
                    crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR,
                    "SexpShape::{shape:?} atomic arm must route \
                     through the typed `AtomKind::OUTER_HASH_DISCRIMINATOR` \
                     rather than an inline `1u8` literal — the arm's \
                     projection `{proj}` diverged from the typed \
                     primitive `{expected}`",
                    proj = shape.hash_discriminator(),
                    expected = crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR,
                );
            }
        }
    }

    #[test]
    fn atom_kind_outer_hash_discriminator_closes_outer_sexp_partition_with_structural_and_quote_form(
    ) {
        // JOINT PARTITION CONTRACT (four-way typed closure): the
        // outer-`Sexp` cache-key partition `{0..=6}` MUST close
        // exactly under the FOUR typed byte primitives — scalar
        // `AtomKind::OUTER_HASH_DISCRIMINATOR` (`{1}`), array
        // `StructuralKind::HASH_DISCRIMINATORS` (`{0, 2}`), array
        // `QuoteForm::HASH_DISCRIMINATORS` (`{3..=6}`). The union
        // covers exactly `{0..=6}` with NO overlap. Pre-lift the
        // partition closure was pinned INDIRECTLY through the
        // `structural_kind_hash_discriminator_disjoint_from_atom_outer_carve_byte_and_quote_form_hash_discriminator_partition`
        // sweep which used a duplicated local `const
        // ATOM_OUTER_CARVE_BYTE: u8 = 1` fixture for the atom side;
        // post-lift THIS pin binds the four-way closure DIRECTLY
        // through the typed substrate primitives. A regression that
        // renumbers `AtomKind::OUTER_HASH_DISCRIMINATOR` into
        // `{0, 2}` (StructuralKind's space) or `{3..=6}`
        // (QuoteForm's space) fails-loudly at THIS test as a
        // partition-collision rather than at a downstream cache
        // mis-hash. Sibling posture to
        // `structural_kind_hash_discriminator_disjoint_from_atom_outer_carve_byte_and_quote_form_hash_discriminator_partition`
        // — that pin sweeps the three-carving-plus-atom-marker
        // union bottom-up from `StructuralKind`; this pin closes
        // the same partition top-down from `AtomKind`'s outer scalar
        // as the sole SCALAR entry alongside the two ARRAY entries.
        // Together the two pins bind the four-way closure at BOTH
        // directions.
        let atomic: std::collections::BTreeSet<u8> =
            std::iter::once(crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR).collect();
        let structural: std::collections::BTreeSet<u8> = StructuralKind::HASH_DISCRIMINATORS
            .iter()
            .copied()
            .collect();
        let quote_family: std::collections::BTreeSet<u8> =
            crate::ast::QuoteForm::HASH_DISCRIMINATORS
                .iter()
                .copied()
                .collect();
        assert!(
            atomic.is_disjoint(&structural),
            "atomic-carve outer marker `{atomic:?}` and structural-carve \
             partition `{structural:?}` MUST be disjoint on the outer-Sexp \
             cache-key space `{{0..=6}}`",
        );
        assert!(
            atomic.is_disjoint(&quote_family),
            "atomic-carve outer marker `{atomic:?}` and quote-family carve \
             partition `{quote_family:?}` MUST be disjoint on the outer-Sexp \
             cache-key space `{{0..=6}}`",
        );
        assert!(
            structural.is_disjoint(&quote_family),
            "structural-carve partition `{structural:?}` and quote-family \
             carve partition `{quote_family:?}` MUST be disjoint on the \
             outer-Sexp cache-key space `{{0..=6}}`",
        );
        let union: std::collections::BTreeSet<u8> = atomic
            .iter()
            .chain(structural.iter())
            .chain(quote_family.iter())
            .copied()
            .collect();
        let expected: std::collections::BTreeSet<u8> = (0u8..=6u8).collect();
        assert_eq!(
            union, expected,
            "the four-way typed closure `atomic ∪ structural ∪ quote_family` \
             = `{union:?}` MUST equal exactly the outer-Sexp cache-key \
             partition `{{0..=6}}` — a regression that drifts ANY of the four \
             primitives into an outer byte outside `{{0..=6}}` OR leaves \
             ANY outer byte unclaimed fails-loudly here",
        );
    }

    #[test]
    fn sexp_shape_hash_discriminator_structural_arms_route_through_structural_kind() {
        // COMPOSITION-ROUTING CONTRACT (shape-level structural-residual
        // arm): for every `SexpShape` variant whose `as_structural_kind()`
        // projection returns `Some(sk)`, `SexpShape::hash_discriminator`
        // MUST agree byte-for-byte with `sk.hash_discriminator()` — the
        // two structural-residual arms (`Nil`, `List`) DELEGATE to the
        // typed sub-carving rather than inline two byte literals. Pin
        // the delegation-identity across the closed set so a regression
        // that inlines a byte at ONE arm (e.g. routes `SexpShape::Nil`
        // to `7u8` inline instead of through
        // `StructuralKind::Nil.hash_discriminator()`) fails-loudly here
        // — it would type-check but silently drift if the sub-algebra's
        // byte is renumbered. Sibling posture to the outer-`Sexp` axis
        // where `Sexp::Nil` / `Sexp::List(_)` also compose through
        // `StructuralKind::hash_discriminator` (pre-lift on that axis;
        // post-lift the same composition emerges through `self.shape()`
        // routing).
        for shape in SexpShape::ALL {
            if let Some(sk) = shape.as_structural_kind() {
                assert_eq!(
                    shape.hash_discriminator(),
                    sk.hash_discriminator(),
                    "SexpShape::{shape:?} structural arm must delegate to StructuralKind::{sk:?}.hash_discriminator()",
                );
            }
        }
    }

    #[test]
    fn sexp_shape_hash_discriminator_quote_family_arms_route_through_quote_form() {
        // COMPOSITION-ROUTING CONTRACT (shape-level quote-family arm):
        // for every `SexpShape` variant whose `as_quote_form()`
        // projection returns `Some(qf)`, `SexpShape::hash_discriminator`
        // MUST agree byte-for-byte with `qf.hash_discriminator()` — the
        // four quote-family arms DELEGATE to the sub-algebra's
        // discriminator method rather than inline four literals. Pin the
        // delegation-identity across the closed set so a regression that
        // inlines a byte at ONE arm (e.g. routes
        // `SexpShape::UnquoteSplice` to `6u8` inline instead of through
        // `QuoteForm::UnquoteSplice.hash_discriminator()`) fails-loudly
        // here — it would type-check but silently drift if the sub-
        // algebra's byte is renumbered. Sibling posture to
        // `sexp_hash_discriminator_quote_arm_delegates_to_quote_form_hash_discriminator`
        // on the outer-`Sexp` algebra — that pin binds the outer-Sexp
        // quote-arm delegation; this pin binds the shape-level quote-
        // family delegation.
        for shape in SexpShape::ALL {
            if let Some(qf) = shape.as_quote_form() {
                assert_eq!(
                    shape.hash_discriminator(),
                    qf.hash_discriminator(),
                    "SexpShape::{shape:?} quote-family arm must delegate to QuoteForm::{qf:?}.hash_discriminator()",
                );
            }
        }
    }

    #[test]
    fn sexp_shape_hash_discriminator_partitions_by_three_way_carving_disjointly() {
        // THREE-WAY CARVING PARTITION CONTRACT: for every `SexpShape`
        // variant, EXACTLY ONE of the three closed-set carvings
        // (`as_atom_kind`, `as_quote_form`, `as_structural_kind`)
        // projects to `Some(_)`, AND the outer discriminator byte the
        // shape-level `hash_discriminator` returns partitions across
        // the three carvings' image spaces: atomic → `{1}` (outer Atom
        // marker), quote-family → `{3, 4, 5, 6}`, structural → `{0, 2}`.
        // A regression that drifts a carving assignment (e.g. routes
        // `SexpShape::Nil` through `as_atom_kind()` due to a bogus
        // typed-shape lattice edit) fails-loudly here — the partition
        // completeness is a compile-time-verified theorem across the
        // three carvings via rustc's exhaustiveness on each carving's
        // `match`. Sibling posture to
        // `structural_kind_hash_discriminator_disjoint_from_atom_outer_carve_byte_and_quote_form_hash_discriminator_partition`
        // — that pin binds the sub-carving byte-space disjointness;
        // this pin binds the shape-level three-way carving assignment
        // AND its image-space partition.
        let atomic_image: std::collections::BTreeSet<u8> = SexpShape::ALL
            .iter()
            .filter(|s| s.as_atom_kind().is_some())
            .map(|s| s.hash_discriminator())
            .collect();
        let quote_image: std::collections::BTreeSet<u8> = SexpShape::ALL
            .iter()
            .filter(|s| s.as_quote_form().is_some())
            .map(|s| s.hash_discriminator())
            .collect();
        let structural_image: std::collections::BTreeSet<u8> = SexpShape::ALL
            .iter()
            .filter(|s| s.as_structural_kind().is_some())
            .map(|s| s.hash_discriminator())
            .collect();
        let expected_atomic: std::collections::BTreeSet<u8> =
            std::iter::once(crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR).collect();
        let expected_quote: std::collections::BTreeSet<u8> = (3u8..=6u8).collect();
        let expected_structural: std::collections::BTreeSet<u8> = [0u8, 2u8].into_iter().collect();
        assert_eq!(
            atomic_image, expected_atomic,
            "the atomic-shape carving's `hash_discriminator` image must be {{1}} (the outer Atom marker byte)",
        );
        assert_eq!(
            quote_image, expected_quote,
            "the quote-family carving's `hash_discriminator` image must be {{3, 4, 5, 6}}",
        );
        assert_eq!(
            structural_image, expected_structural,
            "the structural-residual carving's `hash_discriminator` image must be {{0, 2}}",
        );
        assert!(
            atomic_image.is_disjoint(&quote_image),
            "atomic and quote-family carvings' `hash_discriminator` images must be disjoint",
        );
        assert!(
            atomic_image.is_disjoint(&structural_image),
            "atomic and structural-residual carvings' `hash_discriminator` images must be disjoint",
        );
        assert!(
            quote_image.is_disjoint(&structural_image),
            "quote-family and structural-residual carvings' `hash_discriminator` images must be disjoint",
        );
        let mut union: std::collections::BTreeSet<u8> = atomic_image;
        union.extend(&quote_image);
        union.extend(&structural_image);
        let full_outer: std::collections::BTreeSet<u8> = (0u8..=6u8).collect();
        assert_eq!(
            union, full_outer,
            "the three-carving `hash_discriminator` image union must exactly cover {{0..=6}}",
        );
    }

    #[test]
    fn sexp_shape_hash_discriminators_pin_legacy_outer_cache_key_bytes() {
        // Pin each per-role `pub(crate) const *_HASH_DISCRIMINATOR` on
        // `SexpShape` at its exact canonical outer-`Sexp` cache-key byte
        // — sibling of the pre-existing
        // `sexp_shape_hash_discriminator_pins_legacy_outer_cache_key_bytes`
        // (which pins the projection method's returns). Together the two
        // pins close the (per-role const, projection method) pairing on
        // the outer-shape algebra. Post-lift the twelve per-role bytes
        // live at ONE `pub(crate) const` per role on the `SexpShape`
        // algebra rather than at twelve inline `u8` literals scattered
        // across the projection method's match arms.
        assert_eq!(SexpShape::NIL_HASH_DISCRIMINATOR, 0);
        assert_eq!(SexpShape::SYMBOL_HASH_DISCRIMINATOR, 1);
        assert_eq!(SexpShape::KEYWORD_HASH_DISCRIMINATOR, 1);
        assert_eq!(SexpShape::STRING_HASH_DISCRIMINATOR, 1);
        assert_eq!(SexpShape::INT_HASH_DISCRIMINATOR, 1);
        assert_eq!(SexpShape::FLOAT_HASH_DISCRIMINATOR, 1);
        assert_eq!(SexpShape::BOOL_HASH_DISCRIMINATOR, 1);
        assert_eq!(SexpShape::LIST_HASH_DISCRIMINATOR, 2);
        assert_eq!(SexpShape::QUOTE_HASH_DISCRIMINATOR, 3);
        assert_eq!(SexpShape::QUASIQUOTE_HASH_DISCRIMINATOR, 4);
        assert_eq!(SexpShape::UNQUOTE_HASH_DISCRIMINATOR, 5);
        assert_eq!(SexpShape::UNQUOTE_SPLICE_HASH_DISCRIMINATOR, 6);
    }

    #[test]
    fn sexp_shape_hash_discriminator_routes_through_typed_per_role_constants() {
        // PATH-UNIFORMITY (shape-level per-role): each of the twelve arms
        // of `SexpShape::hash_discriminator` MUST return the corresponding
        // `SexpShape::*_HASH_DISCRIMINATOR` byte-for-byte — catches a
        // regression that reverts ONE arm to an inline `u8` literal OR
        // to a `.hash_discriminator()` runtime dispatch through a sub-
        // carving variant (both of which type-check but bypass the typed
        // per-role primitive). Sibling posture to
        // `atom_kind_hash_discriminator_routes_through_typed_per_role_constants`,
        // `quote_form_hash_discriminator_routes_through_typed_per_role_constants`,
        // and `structural_kind_hash_discriminator_routes_through_typed_per_role_constants`
        // on the three sub-carvings — this pin closes the same routing
        // contract at the outer twelve-arm shape level.
        let pairs = [
            (SexpShape::Nil, SexpShape::NIL_HASH_DISCRIMINATOR),
            (SexpShape::Symbol, SexpShape::SYMBOL_HASH_DISCRIMINATOR),
            (SexpShape::Keyword, SexpShape::KEYWORD_HASH_DISCRIMINATOR),
            (SexpShape::String, SexpShape::STRING_HASH_DISCRIMINATOR),
            (SexpShape::Int, SexpShape::INT_HASH_DISCRIMINATOR),
            (SexpShape::Float, SexpShape::FLOAT_HASH_DISCRIMINATOR),
            (SexpShape::Bool, SexpShape::BOOL_HASH_DISCRIMINATOR),
            (SexpShape::List, SexpShape::LIST_HASH_DISCRIMINATOR),
            (SexpShape::Quote, SexpShape::QUOTE_HASH_DISCRIMINATOR),
            (
                SexpShape::Quasiquote,
                SexpShape::QUASIQUOTE_HASH_DISCRIMINATOR,
            ),
            (SexpShape::Unquote, SexpShape::UNQUOTE_HASH_DISCRIMINATOR),
            (
                SexpShape::UnquoteSplice,
                SexpShape::UNQUOTE_SPLICE_HASH_DISCRIMINATOR,
            ),
        ];
        for (shape, expected) in pairs {
            assert_eq!(
                shape.hash_discriminator(),
                expected,
                "SexpShape::hash_discriminator arm for {shape:?} must route through the typed \
                 `pub(crate) const` per-role byte",
            );
        }
    }

    #[test]
    fn sexp_shape_hash_discriminators_has_expected_cardinality() {
        // Cardinality contract: `Self::HASH_DISCRIMINATORS.len() == 12`
        // matching `Self::ALL.len() == 12`. Arity is forced at the
        // declaration site by rustc's `[u8; 12]` check; this runtime pin
        // fails-loud so a future refactor that switches the array type
        // to `&[u8]` doesn't silently loosen the closed-set discipline.
        // Sibling posture to `sexp_shape_labels_has_expected_cardinality`
        // on the diagnostic-label axis of the same twelve-variant closed
        // set.
        assert_eq!(SexpShape::HASH_DISCRIMINATORS.len(), 12);
        assert_eq!(
            SexpShape::HASH_DISCRIMINATORS.len(),
            SexpShape::ALL.len(),
            "SexpShape::HASH_DISCRIMINATORS cardinality drifted from SexpShape::ALL",
        );
    }

    #[test]
    fn sexp_shape_hash_discriminators_align_with_all_by_index() {
        // ALIGNMENT CONTRACT: `Self::HASH_DISCRIMINATORS[i] ==
        // Self::ALL[i].hash_discriminator()` element-wise — the ALL
        // array's variant order MUST align with the HASH_DISCRIMINATORS
        // array's byte order. A regression that reorders ONE array
        // without reordering the other silently misaligns every
        // `zip(ALL, HASH_DISCRIMINATORS)` consumer. Sibling posture to
        // `structural_kind_hash_discriminators_align_with_all_by_index`,
        // `quote_form_hash_discriminators_align_with_all_by_index`, and
        // `atom_kind_hash_discriminators_align_with_all_by_index` on the
        // three sub-carvings — this pin closes the same alignment
        // contract at the outer twelve-arm shape level.
        for (i, shape) in SexpShape::ALL.iter().copied().enumerate() {
            let disc = shape.hash_discriminator();
            assert_eq!(
                SexpShape::HASH_DISCRIMINATORS[i],
                disc,
                "SexpShape::HASH_DISCRIMINATORS[{i}] `{disc}` != \
                 SexpShape::ALL[{i}].hash_discriminator() `{disc}` — array-vs-projection drift",
            );
        }
    }

    #[test]
    fn sexp_shape_hash_discriminators_cover_outer_partition_zero_through_six() {
        // PARTITION-COMPLETENESS CONTRACT (array level): the twelve-byte
        // set of `Self::HASH_DISCRIMINATORS` MUST cover exactly the
        // outer cache-key partition `{0..=6}` — no byte outside, no byte
        // inside missing. Sibling to
        // `sexp_shape_hash_discriminator_covers_outer_partition_zero_through_six`
        // (which closes the same partition through the projection method)
        // — this pin closes it at the ARRAY level so a regression that
        // drifts the array's contents without changing the method
        // surfaces here rather than only through the projection sweep.
        let bytes: std::collections::BTreeSet<u8> =
            SexpShape::HASH_DISCRIMINATORS.iter().copied().collect();
        let expected: std::collections::BTreeSet<u8> = (0u8..=6u8).collect();
        assert_eq!(
            bytes, expected,
            "SexpShape::HASH_DISCRIMINATORS must cover exactly the outer discriminator space {{0..=6}}",
        );
    }

    #[test]
    fn sexp_shape_hash_discriminators_align_with_typed_per_role_constants_by_index() {
        // PER-ROLE ROUTING CONTRACT (family-wide array level): for every
        // `i in 0..12`, `SexpShape::HASH_DISCRIMINATORS[i]` MUST equal the
        // corresponding twelve-arm `SexpShape::*_HASH_DISCRIMINATOR`
        // per-role `pub(crate) const` at the SAME position in
        // `SexpShape::ALL`. Catches a regression that inlines byte
        // LITERALS in the `HASH_DISCRIMINATORS` array definition (e.g.
        // rewrites `[Self::NIL_HASH_DISCRIMINATOR, Self::SYMBOL_HASH_DISCRIMINATOR,
        // ...]` to `[0u8, 1u8, ...]`) — that regression would still
        // byte-equal the outer partition `{0..=6}`, still byte-equal the
        // sub-carving projections, and still byte-equal
        // `SexpShape::ALL[i].hash_discriminator()`, so every existing pin
        // (`_pin_legacy_outer_cache_key_bytes`, `_align_with_all_by_index`,
        // `_cover_outer_partition_zero_through_six`,
        // `_align_with_sub_carvings_by_projection`) would still PASS while
        // the FAMILY-WIDE array silently DRIFTED from the per-role
        // primitives it aliases through. Pin the alias-identity across
        // the twelve positions so the outer-shape ALL-array binds to the
        // per-role sources of truth at rustc-time PLUS runtime by ONE
        // typed pairing per position.
        //
        // Sibling posture to `sexp_shape_hash_discriminator_routes_through_typed_per_role_constants`
        // on the METHOD-side per-role routing axis — that pin binds the
        // twelve-arm projection method's per-role routing; this pin binds
        // the twelve-position family-wide array's per-role routing. Together
        // the two pins close the per-role routing contract at BOTH the
        // METHOD-side and the ARRAY-side of the shape algebra, in the SAME
        // shape as the sibling `SexpShape::LABELS` axis's
        // `sexp_shape_labels_align_with_all_by_index` pin (via
        // `SexpShape::ALL[i].label()`) — both axes now pin BOTH sides of
        // the (method, array) pair to the SAME per-role source of truth.
        let per_role = [
            SexpShape::NIL_HASH_DISCRIMINATOR,
            SexpShape::SYMBOL_HASH_DISCRIMINATOR,
            SexpShape::KEYWORD_HASH_DISCRIMINATOR,
            SexpShape::STRING_HASH_DISCRIMINATOR,
            SexpShape::INT_HASH_DISCRIMINATOR,
            SexpShape::FLOAT_HASH_DISCRIMINATOR,
            SexpShape::BOOL_HASH_DISCRIMINATOR,
            SexpShape::LIST_HASH_DISCRIMINATOR,
            SexpShape::QUOTE_HASH_DISCRIMINATOR,
            SexpShape::QUASIQUOTE_HASH_DISCRIMINATOR,
            SexpShape::UNQUOTE_HASH_DISCRIMINATOR,
            SexpShape::UNQUOTE_SPLICE_HASH_DISCRIMINATOR,
        ];
        assert_eq!(
            per_role.len(),
            SexpShape::HASH_DISCRIMINATORS.len(),
            "the twelve per-role SexpShape::*_HASH_DISCRIMINATOR constants \
             must cover the same cardinality as SexpShape::HASH_DISCRIMINATORS",
        );
        for (i, expected) in per_role.iter().copied().enumerate() {
            assert_eq!(
                SexpShape::HASH_DISCRIMINATORS[i],
                expected,
                "SexpShape::HASH_DISCRIMINATORS[{i}] `{actual}` drifted from \
                 the per-role SexpShape::*_HASH_DISCRIMINATOR constant `{expected}` \
                 for {shape:?} — the family-wide array MUST alias through the \
                 per-role source of truth rather than inline a byte literal",
                actual = SexpShape::HASH_DISCRIMINATORS[i],
                shape = SexpShape::ALL[i],
            );
        }
    }

    #[test]
    fn sexp_shape_hash_discriminators_align_with_sub_carvings_by_projection() {
        // CROSS-ALGEBRA COMPOSITION CONTRACT: for every `i in 0..12`,
        // `Self::HASH_DISCRIMINATORS[i]` MUST equal the byte the SUB-
        // CARVING projection returns for `Self::ALL[i]` — i.e. the
        // outer-shape ALL-array byte at every position is byte-identical
        // to (a) `AtomKind::OUTER_HASH_DISCRIMINATOR` on the atomic-
        // payload variants, (b) `StructuralKind::HASH_DISCRIMINATORS`'s
        // byte on structural-residual variants (routed via
        // `as_structural_kind`), and (c)
        // `QuoteForm::HASH_DISCRIMINATORS`'s byte on quote-family
        // variants (routed via `as_quote_form`). Closes the load-
        // bearing invariant that the outer-shape peer alias equals the
        // sub-carving's canonical byte at rustc-time through the `const`
        // initializer. A regression that drifts ONE sub-carving's byte
        // without updating the outer-shape peer alias fails to compile
        // (the `const` initializer references the same primitive); a
        // regression that drifts the OUTER alias byte-order in the
        // array fails-loudly here.
        for (i, shape) in SexpShape::ALL.iter().copied().enumerate() {
            let expected = if shape.as_atom_kind().is_some() {
                crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR
            } else if let Some(sk) = shape.as_structural_kind() {
                sk.hash_discriminator()
            } else if let Some(qf) = shape.as_quote_form() {
                qf.hash_discriminator()
            } else {
                unreachable!(
                    "SexpShape::{shape:?} lies outside all three sub-carvings — \
                     the three-carving partition (Atom + Structural + Quote) is not exhaustive",
                );
            };
            assert_eq!(
                SexpShape::HASH_DISCRIMINATORS[i], expected,
                "SexpShape::HASH_DISCRIMINATORS[{i}] must equal the sub-carving projection for {shape:?}",
            );
        }
    }

    #[test]
    fn sexp_shape_iac_forge_tag_pins_canonical_cl_tags_for_every_quote_family_arm() {
        // CANONICAL-TAG CONTRACT (shape-level peer): the shape-level
        // `SexpShape::iac_forge_tag` MUST project each of the four
        // quote-family arms to the SAME canonical Common-Lisp tag
        // string `crate::ast::QuoteForm::iac_forge_tag` projects at the
        // sub-carving level — `Quote → "quote"`, `Quasiquote →
        // "quasiquote"`, `Unquote → "unquote"`, `UnquoteSplice →
        // "unquote-splicing"`. A regression that inlines a byte-drifted
        // spelling here (e.g. `SexpShape::UnquoteSplice → Some(
        // "unquote-splice")` conflating the substrate's shorter
        // diagnostic label with the CL canonical form) silently breaks
        // every cross-crate iac-forge consumer keyed on `(unquote-
        // splicing ...)`. Sibling posture to
        // `quote_form_iac_forge_tag_pins_canonical_lisp_tag_strings_for_every_variant`
        // (in `crate::ast`) on the 4-arm sub-carving — that pin binds
        // the sub-carving's canonical tag surface; this pin binds the
        // shape-level projection's canonical tag surface AND its
        // Option-partial shape.
        assert_eq!(SexpShape::Quote.iac_forge_tag(), Some("quote"));
        assert_eq!(SexpShape::Quasiquote.iac_forge_tag(), Some("quasiquote"));
        assert_eq!(SexpShape::Unquote.iac_forge_tag(), Some("unquote"));
        assert_eq!(
            SexpShape::UnquoteSplice.iac_forge_tag(),
            Some("unquote-splicing"),
        );
    }

    #[test]
    fn sexp_shape_iac_forge_tag_returns_none_on_every_non_quote_family_shape() {
        // PARTIAL-PROJECTION KERNEL CONTRACT (shape-level peer): every
        // `SexpShape` variant OUTSIDE the four-arm quote-family carving
        // MUST project through `SexpShape::iac_forge_tag` to `None` —
        // the eight-shape kernel coincides byte-for-byte with the
        // kernel of `SexpShape::as_quote_form`. Pin the eight-shape
        // sweep (six atomic-payload variants + `Nil` + `List`) so a
        // regression that surfaces a bogus tag for a non-quote-family
        // arm (e.g. `SexpShape::List → Some("list")` conflating the
        // outer-shape diagnostic label with the quote-family canonical
        // form) fails-loudly here. Sibling posture to the projection's
        // parent-carving `sexp_shape_as_quote_form` returning `None`
        // on the eight-shape kernel.
        assert_eq!(SexpShape::Nil.iac_forge_tag(), None);
        assert_eq!(SexpShape::Symbol.iac_forge_tag(), None);
        assert_eq!(SexpShape::Keyword.iac_forge_tag(), None);
        assert_eq!(SexpShape::String.iac_forge_tag(), None);
        assert_eq!(SexpShape::Int.iac_forge_tag(), None);
        assert_eq!(SexpShape::Float.iac_forge_tag(), None);
        assert_eq!(SexpShape::Bool.iac_forge_tag(), None);
        assert_eq!(SexpShape::List.iac_forge_tag(), None);
    }

    #[test]
    fn sexp_shape_iac_forge_tag_composes_through_as_quote_form_for_every_variant() {
        // COMPOSITION-LAW CONTRACT (shape-level peer):
        // `SexpShape::iac_forge_tag() ==
        // SexpShape::as_quote_form().map(QuoteForm::iac_forge_tag)` for
        // every variant in `SexpShape::ALL`. The (outer shape, canonical
        // iac-forge tag) pairing binds through the pre-existing quote-
        // family carving composed with the closed-set tag projection
        // rather than at a parallel four-arm inline match — this pin
        // enforces the composition-identity across the closed twelve-arm
        // sweep so a regression that drifts ONE arm's inline projection
        // from the composition (e.g. re-inlining `SexpShape::Quote →
        // Some("quote-old")` without updating `QuoteForm::iac_forge_tag`)
        // fails-loudly here. Sibling posture to
        // `sexp_shape_hash_discriminator_quote_family_arms_route_through_quote_form`
        // (delegation-identity on the byte-discriminator surface) — that
        // pin binds the sub-carving byte routing; this pin binds the
        // sub-carving tag routing.
        for shape in SexpShape::ALL {
            let via_method = shape.iac_forge_tag();
            let via_composition = shape
                .as_quote_form()
                .map(crate::ast::QuoteForm::iac_forge_tag);
            assert_eq!(
                via_method, via_composition,
                "SexpShape::{shape:?}.iac_forge_tag() drifted from \
                 .as_quote_form().map(QuoteForm::iac_forge_tag) — the shape-level tag projection is no longer derived from the sub-carving's canonical site",
            );
        }
    }

    #[test]
    fn sexp_shape_iac_forge_tag_partitions_quote_family_and_kernel_disjointly() {
        // IMAGE-PARTITION CONTRACT (shape-level peer): sweeping
        // `SexpShape::ALL` through `SexpShape::iac_forge_tag` MUST
        // partition into EXACTLY the four-arm quote-family image (four
        // distinct canonical CL tag strings — the pre-image of `Some(_)`)
        // AND the eight-shape kernel (all `None` — six atomic-payload
        // variants + `Nil` + `List`). The image's `is_some()` count
        // MUST be four (surjective onto the four-tag closed set), the
        // kernel's `is_none()` count MUST be eight, and the sum MUST
        // hit `SexpShape::ALL.len()` (twelve) — a regression that leaks
        // a bogus `Some(_)` from a non-quote-family arm or drops a
        // `Some(_)` from a quote-family arm fails-loudly here on the
        // partition-cardinality axis before any downstream iac-forge
        // consumer would surface the drift. Sibling posture to the
        // three-way carving `sexp_shape_hash_discriminator_partitions_by_three_way_carving_disjointly`
        // pinning the byte-image partition; this pin binds the shape-
        // level tag-image partition on the four-arm quote-family
        // carving.
        let tag_image: std::collections::BTreeSet<&'static str> = SexpShape::ALL
            .iter()
            .filter_map(|shape| shape.iac_forge_tag())
            .collect();
        let expected_tag_image: std::collections::BTreeSet<&'static str> =
            ["quote", "quasiquote", "unquote", "unquote-splicing"]
                .into_iter()
                .collect();
        assert_eq!(
            tag_image, expected_tag_image,
            "SexpShape::iac_forge_tag image must exactly cover the four canonical CL quote-family tags",
        );
        let some_count = SexpShape::ALL
            .iter()
            .filter(|shape| shape.iac_forge_tag().is_some())
            .count();
        assert_eq!(
            some_count, 4,
            "SexpShape::iac_forge_tag must return `Some(_)` on exactly the four-arm quote-family carving",
        );
        let none_count = SexpShape::ALL
            .iter()
            .filter(|shape| shape.iac_forge_tag().is_none())
            .count();
        assert_eq!(
            none_count, 8,
            "SexpShape::iac_forge_tag must return `None` on exactly the eight-shape non-quote-family kernel",
        );
        assert_eq!(
            some_count + none_count,
            SexpShape::ALL.len(),
            "SexpShape::iac_forge_tag's image + kernel must partition SexpShape::ALL exactly",
        );
    }

    #[test]
    fn sexp_shape_prefix_pins_canonical_reader_prefixes_for_every_quote_family_arm() {
        // CANONICAL-PREFIX CONTRACT (shape-level peer): the shape-level
        // `SexpShape::prefix` MUST project each of the four quote-family
        // arms to the SAME canonical reader-punctuation string
        // `crate::ast::QuoteForm::prefix` projects at the sub-carving
        // level — `Quote → "'"`, `Quasiquote → "`"`, `Unquote → ","`,
        // `UnquoteSplice → ",@"`. A regression that inlines a byte-
        // drifted spelling here (e.g. `SexpShape::Quote → Some("`")`
        // swapping the single-quote and backtick prefixes, or
        // `SexpShape::UnquoteSplice → Some("@,")` swapping the two-byte
        // splice prefix's byte order) silently breaks every reader /
        // LSP / REPL consumer keyed on the source-punctuation
        // vocabulary. Sibling posture to
        // `sexp_shape_iac_forge_tag_pins_canonical_cl_tags_for_every_quote_family_arm`
        // on the cross-crate canonical-form axis — that pin binds the
        // iac-forge tag surface; this pin binds the reader-punctuation
        // prefix surface AND its Option-partial shape.
        assert_eq!(SexpShape::Quote.prefix(), Some("'"));
        assert_eq!(SexpShape::Quasiquote.prefix(), Some("`"));
        assert_eq!(SexpShape::Unquote.prefix(), Some(","));
        assert_eq!(SexpShape::UnquoteSplice.prefix(), Some(",@"));
    }

    #[test]
    fn sexp_shape_prefix_returns_none_on_every_non_quote_family_shape() {
        // PARTIAL-PROJECTION KERNEL CONTRACT (shape-level peer): every
        // `SexpShape` variant OUTSIDE the four-arm quote-family carving
        // MUST project through `SexpShape::prefix` to `None` — the
        // eight-shape kernel coincides byte-for-byte with the kernel of
        // `SexpShape::as_quote_form` AND `SexpShape::iac_forge_tag`
        // (there is NO homoiconic reader-punctuation prefix for the
        // atomic-payload variants `Symbol`/`Keyword`/`String`/`Int`/
        // `Float`/`Bool` — those render via their own atomic syntax —
        // nor for the structural residuals `Nil`/`List` which render as
        // `nil`/`(...)` respectively, neither via a prefix character).
        // Pin the eight-shape sweep so a regression that surfaces a
        // bogus prefix for a non-quote-family arm (e.g. `SexpShape::Nil
        // → Some("()")` conflating the structural-residual Display with
        // the reader-punctuation vocabulary) fails-loudly here. Sibling
        // posture to
        // `sexp_shape_iac_forge_tag_returns_none_on_every_non_quote_family_shape`
        // one vocabulary axis over.
        assert_eq!(SexpShape::Nil.prefix(), None);
        assert_eq!(SexpShape::Symbol.prefix(), None);
        assert_eq!(SexpShape::Keyword.prefix(), None);
        assert_eq!(SexpShape::String.prefix(), None);
        assert_eq!(SexpShape::Int.prefix(), None);
        assert_eq!(SexpShape::Float.prefix(), None);
        assert_eq!(SexpShape::Bool.prefix(), None);
        assert_eq!(SexpShape::List.prefix(), None);
    }

    #[test]
    fn sexp_shape_prefix_composes_through_as_quote_form_for_every_variant() {
        // COMPOSITION-LAW CONTRACT (shape-level peer): `SexpShape::prefix()
        // == SexpShape::as_quote_form().map(QuoteForm::prefix)` for every
        // variant in `SexpShape::ALL`. The (outer shape, reader-
        // punctuation prefix) pairing binds through the pre-existing
        // quote-family carving composed with the closed-set prefix
        // projection rather than at a parallel four-arm inline match —
        // this pin enforces the composition-identity across the closed
        // twelve-arm sweep so a regression that drifts ONE arm's inline
        // projection from the composition (e.g. re-inlining
        // `SexpShape::Quote → Some("’")` — a fancy-quote look-alike —
        // without updating `QuoteForm::prefix`) fails-loudly here.
        // Sibling posture to
        // `sexp_shape_iac_forge_tag_composes_through_as_quote_form_for_every_variant`
        // one vocabulary axis over.
        for shape in SexpShape::ALL {
            let via_method = shape.prefix();
            let via_composition = shape.as_quote_form().map(crate::ast::QuoteForm::prefix);
            assert_eq!(
                via_method, via_composition,
                "SexpShape::{shape:?}.prefix() drifted from \
                 .as_quote_form().map(QuoteForm::prefix) — the shape-level prefix projection is no longer derived from the sub-carving's canonical site",
            );
        }
    }

    #[test]
    fn sexp_shape_prefix_partitions_quote_family_and_kernel_disjointly() {
        // IMAGE-PARTITION CONTRACT (shape-level peer): sweeping
        // `SexpShape::ALL` through `SexpShape::prefix` MUST partition
        // into EXACTLY the four-arm quote-family image (four distinct
        // canonical reader-punctuation strings — the pre-image of
        // `Some(_)`) AND the eight-shape kernel (all `None` — six
        // atomic-payload variants + `Nil` + `List`). The image's
        // `is_some()` count MUST be four (surjective onto the four-
        // prefix closed set), the kernel's `is_none()` count MUST be
        // eight, and the sum MUST hit `SexpShape::ALL.len()` (twelve)
        // — a regression that leaks a bogus `Some(_)` from a non-
        // quote-family arm or drops a `Some(_)` from a quote-family
        // arm fails-loudly here on the partition-cardinality axis
        // before any downstream reader / LSP / REPL consumer would
        // surface the drift. Sibling posture to
        // `sexp_shape_iac_forge_tag_partitions_quote_family_and_kernel_disjointly`
        // pinning the tag-image partition; this pin binds the shape-
        // level prefix-image partition on the four-arm quote-family
        // carving. Disjoint vocabulary from the iac-forge partition
        // (`"'"` / `"`"` / `","` / `",@"` vs. `"quote"` / `"quasiquote"`
        // / `"unquote"` / `"unquote-splicing"`) — the same closed twelve-
        // arm shape algebra carries THREE distinct `&'static str`
        // vocabularies keyed on the same four-arm quote-family carving,
        // and a regression that conflates any two lands here.
        let prefix_image: std::collections::BTreeSet<&'static str> = SexpShape::ALL
            .iter()
            .filter_map(|shape| shape.prefix())
            .collect();
        let expected_prefix_image: std::collections::BTreeSet<&'static str> =
            ["'", "`", ",", ",@"].into_iter().collect();
        assert_eq!(
            prefix_image, expected_prefix_image,
            "SexpShape::prefix image must exactly cover the four canonical reader-punctuation quote-family prefixes",
        );
        let some_count = SexpShape::ALL
            .iter()
            .filter(|shape| shape.prefix().is_some())
            .count();
        assert_eq!(
            some_count, 4,
            "SexpShape::prefix must return `Some(_)` on exactly the four-arm quote-family carving",
        );
        let none_count = SexpShape::ALL
            .iter()
            .filter(|shape| shape.prefix().is_none())
            .count();
        assert_eq!(
            none_count, 8,
            "SexpShape::prefix must return `None` on exactly the eight-shape non-quote-family kernel",
        );
        assert_eq!(
            some_count + none_count,
            SexpShape::ALL.len(),
            "SexpShape::prefix's image + kernel must partition SexpShape::ALL exactly",
        );
    }

    /// Runtime cross-check for the 13 module-level `const _: () =
    /// crate::ast::assert_str_array_pairwise_distinct(&…)` witnesses
    /// declared at the top of `error.rs`. Runs the same const-fn
    /// helper on every family-wide `[&'static str; N]` array on this
    /// module's closed-set diagnostic / classification algebras at
    /// `cargo test` time — the runtime path pairs the compile-time
    /// path so a build that runs tests catches the regression a
    /// second time as a safety net if the const-eval sweep is ever
    /// silently dropped.
    ///
    /// Sibling to
    /// `assert_str_array_pairwise_distinct_accepts_every_family_
    /// wide_substrate_array` on `ast.rs`'s tests module — that
    /// pair covers the FIVE family-wide `[&'static str; N]` arrays
    /// on `ast.rs`'s closed-set outer algebras (`Atom::BOOL_LITERALS`,
    /// `AtomKind::LABELS`, `QuoteForm::PREFIXES`,
    /// `QuoteForm::IAC_FORGE_TAGS`, `QuoteForm::LABELS`); this test
    /// covers the THIRTEEN peer arrays on `error.rs`'s closed-set
    /// diagnostic / classification algebras. Together the two tests
    /// runtime-verify every ONE of the workspace-wide EIGHTEEN
    /// pairwise-distinct family-wide `[&'static str; N]` arrays
    /// through the SAME `assert_str_array_pairwise_distinct` const-
    /// fn primitive.
    ///
    /// `CompilerSpecIoStage::OPERATIONS` (`[&'static str; 4]`) is
    /// intentionally omitted — it is a variant-aligned projection
    /// with two-fold duplicated entries (`[REALIZE_TO_DISK,
    /// REALIZE_TO_DISK, LOAD_FROM_DISK, LOAD_FROM_DISK]`), so
    /// enrolling it here would panic; the intended invariant on
    /// `OPERATIONS` is "variant-index alignment with
    /// `CompilerSpecIoStage::ALL`", a distinct theorem covered by
    /// its own tests.
    #[test]
    fn assert_str_array_pairwise_distinct_accepts_every_family_wide_error_module_array() {
        use crate::ast::assert_str_array_pairwise_distinct;
        assert_str_array_pairwise_distinct(&CompilerSpecIoStage::LABELS);
        assert_str_array_pairwise_distinct(&TemplateInvariantKind::STATIC_MESSAGES);
        assert_str_array_pairwise_distinct(&TemplateInvariantKind::DYNAMIC_DESCRIPTORS);
        assert_str_array_pairwise_distinct(&MacroDefHead::KEYWORDS);
        assert_str_array_pairwise_distinct(&OptionalParamMalformedReason::STATIC_LABELS);
        assert_str_array_pairwise_distinct(&OptionalParamMalformedReason::DYNAMIC_DESCRIPTORS);
        assert_str_array_pairwise_distinct(&UnquoteForm::MARKERS);
        assert_str_array_pairwise_distinct(&UnquoteForm::IAC_FORGE_TAGS);
        assert_str_array_pairwise_distinct(&UnquoteForm::LABELS);
        assert_str_array_pairwise_distinct(&KwargPathKind::LABELS);
        assert_str_array_pairwise_distinct(&ExpectedKwargShape::LABELS);
        assert_str_array_pairwise_distinct(&SexpShape::LABELS);
        assert_str_array_pairwise_distinct(&StructuralKind::LABELS);
    }

    /// Runtime cross-check that the SAME thirteen family-wide
    /// `[&'static str; N]` arrays declared under this module that
    /// the compile-time `const _: () = crate::ast::
    /// assert_str_array_all_ascii(&…)` witness block above pins at
    /// `cargo check` time are all-ASCII at runtime too. Sibling to
    /// `assert_str_array_pairwise_distinct_accepts_every_family_
    /// wide_error_module_array` on the (contract-shape) column —
    /// the two together pin BOTH the INJECTIVITY axis AND the
    /// ASCII-BYTE-RANGE axis on the SAME thirteen arrays, at TWO
    /// stages of the toolchain (compile-time `const _` line + this
    /// runtime safety-net). Includes `CompilerSpecIoStage::
    /// OPERATIONS` — which is DELIBERATELY excluded from the
    /// pairwise-distinct sibling because its four entries are
    /// intentionally-collapsed onto two per-operation labels but
    /// is enrolled here because its two distinct entries
    /// (`"realize_to_disk"`, `"load_from_disk"`) are ASCII by
    /// construction.
    #[test]
    fn assert_str_array_all_ascii_accepts_every_family_wide_error_module_array() {
        use crate::ast::assert_str_array_all_ascii;
        assert_str_array_all_ascii(&CompilerSpecIoStage::LABELS);
        assert_str_array_all_ascii(&CompilerSpecIoStage::OPERATIONS);
        assert_str_array_all_ascii(&TemplateInvariantKind::STATIC_MESSAGES);
        assert_str_array_all_ascii(&TemplateInvariantKind::DYNAMIC_DESCRIPTORS);
        assert_str_array_all_ascii(&MacroDefHead::KEYWORDS);
        assert_str_array_all_ascii(&OptionalParamMalformedReason::STATIC_LABELS);
        assert_str_array_all_ascii(&OptionalParamMalformedReason::DYNAMIC_DESCRIPTORS);
        assert_str_array_all_ascii(&UnquoteForm::MARKERS);
        assert_str_array_all_ascii(&UnquoteForm::IAC_FORGE_TAGS);
        assert_str_array_all_ascii(&UnquoteForm::LABELS);
        assert_str_array_all_ascii(&KwargPathKind::LABELS);
        assert_str_array_all_ascii(&ExpectedKwargShape::LABELS);
        assert_str_array_all_ascii(&SexpShape::LABELS);
        assert_str_array_all_ascii(&StructuralKind::LABELS);
    }

    /// Confirm `CompilerSpecIoStage::OPERATIONS` — the ONE family-
    /// wide `[&'static str; N]` array on this module that is
    /// DELIBERATELY excluded from the compile-time pairwise-
    /// distinctness witness block above — panics on the same helper
    /// (`crate::ast::assert_str_array_pairwise_distinct`) at
    /// runtime. Two positional pairs collide byte-for-byte on this
    /// array by design: positions 0+1 (both
    /// `Self::REALIZE_TO_DISK_OPERATION` = `"realize_to_disk"`) AND
    /// positions 2+3 (both `Self::LOAD_FROM_DISK_OPERATION` =
    /// `"load_from_disk"`), and the array's intended invariant is
    /// variant-index alignment with `Self::ALL`, not injectivity.
    ///
    /// This test doubles as a documented boundary marker — if a
    /// future refactor DID sharpen `OPERATIONS` to a distinct set
    /// (e.g. by carving the two-per-operation collapse into a
    /// separate `[&'static str; 2]` array), enrolling the sharpened
    /// array in the `const _` block above would then be legal, and
    /// this test would need updating to match. Pinning the "is
    /// intentionally non-distinct" property here surfaces that
    /// refactor at test time rather than leaving it as a silent
    /// module-level tribal-knowledge assumption.
    #[test]
    #[should_panic(expected = "assert_str_array_pairwise_distinct")]
    fn assert_str_array_pairwise_distinct_panics_on_compiler_spec_io_stage_operations() {
        use crate::ast::assert_str_array_pairwise_distinct;
        assert_str_array_pairwise_distinct(&CompilerSpecIoStage::OPERATIONS);
    }

    /// Runtime cross-check that the TWO
    /// (`_`, `StructuralKind::LABELS`) disjointness pairs the
    /// module-level `const _: () = crate::ast::assert_str_arrays_
    /// disjoint::<N, 2>(...)` witnesses pin at COMPILE time are
    /// proper DISJOINTNESS embeddings at runtime too. Peer to
    /// `assert_str_arrays_disjoint_accepts_each_family_wide_
    /// substrate_pair` in `ast.rs` (which sweeps the FOUR pairs
    /// whose two hosts both live in `ast.rs`): together the two
    /// tests sweep all SIX substrate-pinned `&'static str`
    /// disjointness pairs (`ast.rs` × 4 + `error.rs` × 2 = 6) at
    /// runtime as a safety net. The compile-time `const _` sweep
    /// fires FIRST at `cargo check`; this test catches drift again
    /// at `cargo test` if the const-eval sweep is ever silently
    /// dropped.
    ///
    /// Composed with the ast.rs-pinned
    /// (`AtomKind::LABELS`, `QuoteForm::LABELS`) pair — the third
    /// pair on the three-element sub-vocabulary triple — these two
    /// checks close the DISJOINT-UNION theorem
    /// `SexpShape::LABELS ≡ AtomKind::LABELS ⊕ QuoteForm::LABELS ⊕
    /// StructuralKind::LABELS` at runtime as the sibling proof to
    /// the three subset-embedding witnesses on the same triple.
    #[test]
    fn assert_str_arrays_disjoint_accepts_each_structural_kind_partition_pair() {
        use crate::ast::assert_str_arrays_disjoint;
        assert_str_arrays_disjoint::<6, 2>(&crate::ast::AtomKind::LABELS, &StructuralKind::LABELS);
        assert_str_arrays_disjoint::<4, 2>(&crate::ast::QuoteForm::LABELS, &StructuralKind::LABELS);
    }

    /// Runtime safety-net sibling of the module-level compile-time
    /// STR-DISJOINTNESS witnesses on the STATIC ⊕ DYNAMIC 2-of-2 face
    /// of the substrate's TWO peer diagnostic algebras
    /// (`TemplateInvariantKind` at 2 ⊕ 2 asymmetric widths;
    /// `OptionalParamMalformedReason` at 3 ⊕ 1 asymmetric widths).
    /// Re-runs each `const _: () = crate::ast::assert_str_arrays_
    /// disjoint::<N, M>(&<algebra>::STATIC_*, &<algebra>::DYNAMIC_
    /// DESCRIPTORS)` witness pinned above the `LispError` enum at
    /// runtime as a safety net so a build that skips `cargo check`'s
    /// const-eval sweep still catches drift here. Peer to
    /// `assert_str_arrays_disjoint_accepts_each_structural_kind_partition_pair`
    /// above (which sweeps the SexpShape 3-way sub-vocabulary triple's
    /// two `error.rs`-hosted disjointness pairs); together the two
    /// tests sweep all FOUR `error.rs`-hosted `assert_str_arrays_
    /// disjoint` witnesses at runtime. The compile-time `const _`
    /// sweep at the top of this module fires FIRST at `cargo check`;
    /// this test catches drift again at `cargo test` if the const-
    /// eval sweep is ever silently dropped.
    #[test]
    fn assert_str_arrays_disjoint_accepts_each_static_dynamic_carving_pair() {
        use crate::ast::assert_str_arrays_disjoint;
        assert_str_arrays_disjoint::<2, 2>(
            &TemplateInvariantKind::STATIC_MESSAGES,
            &TemplateInvariantKind::DYNAMIC_DESCRIPTORS,
        );
        assert_str_arrays_disjoint::<3, 1>(
            &OptionalParamMalformedReason::STATIC_LABELS,
            &OptionalParamMalformedReason::DYNAMIC_DESCRIPTORS,
        );
    }

    /// Runtime safety-net sibling of the module-level compile-time
    /// STR-BLOCK-CONSTANCY witness on the MANY-TO-ONE variant →
    /// canonical-projection surface at
    /// `CompilerSpecIoStage::OPERATIONS`. Re-runs the `const _: () =
    /// crate::ast::assert_str_array_is_concatenation_of_two_scalar_
    /// replicas::<4, 2>(&OPERATIONS, REALIZE_TO_DISK_OPERATION,
    /// LOAD_FROM_DISK_OPERATION)` witness pinned above the
    /// `LispError` enum at runtime as a safety net so a build that
    /// skips `cargo check`'s const-eval sweep still catches the
    /// block-constant drift here. Peer to
    /// `compiler_spec_io_stage_operations_align_with_all_by_index`
    /// (which pins per-position projection equality through
    /// `stage.operation()`) and to
    /// `compiler_spec_io_stage_operations_partition_all_two_ways`
    /// (which pins the two operation-label multiplicities) — the
    /// three tests jointly sweep the block-constant partition at
    /// THREE distinct runtime angles (per-position equality with
    /// ALL, multiplicity count of each block scalar, ARRAY-LEVEL
    /// block-constancy structural pattern) while the compile-time
    /// witness above binds the ARRAY-LEVEL structural pattern at
    /// `cargo check` time as the FIRST-firing arm.
    #[test]
    fn assert_str_array_is_concatenation_of_two_scalar_replicas_accepts_compiler_spec_io_stage_operations(
    ) {
        use crate::ast::assert_str_array_is_concatenation_of_two_scalar_replicas;
        assert_str_array_is_concatenation_of_two_scalar_replicas::<4, 2>(
            &CompilerSpecIoStage::OPERATIONS,
            CompilerSpecIoStage::REALIZE_TO_DISK_OPERATION,
            CompilerSpecIoStage::LOAD_FROM_DISK_OPERATION,
        );
    }

    /// Runtime cross-check that the SAME five (str)-row FULL-ARRAY
    /// LITERAL witnesses covered at COMPILE time by the module-level
    /// `const _: () = crate::ast::assert_str_array_slice_equals_str_
    /// array::<N, N, 0>(&…, &[literal strs; N])` cluster immediately
    /// below the `assert_str_array_is_concatenation_of_two_scalar_
    /// replicas::<4, 2>(&CompilerSpecIoStage::OPERATIONS, …)` block
    /// witness — pinning `ExpectedKwargShape::LABELS`,
    /// `KwargPathKind::LABELS`, `MacroDefHead::KEYWORDS`,
    /// `CompilerSpecIoStage::LABELS`, and `StructuralKind::LABELS`
    /// against their canonical literal-str listings — also hold when
    /// exercised at runtime. A regression that removes ONE of the
    /// const witnesses would still leave THIS runtime pin as a
    /// safety net; the const witness fires FIRST at `cargo check`,
    /// this runtime pin catches the positionwise drift at `cargo
    /// test`. The pair enforces the theorem at TWO stages of the
    /// toolchain.
    ///
    /// Sibling posture to
    /// `assert_str_array_slice_equals_str_array_accepts_every_family_wide_substrate_array_full_array_literal_listing`
    /// in `ast.rs` (the ast-side (str)-row cluster's runtime peer
    /// on `Atom::BOOL_LITERALS` / `AtomKind::LABELS` /
    /// `QuoteForm::PREFIXES` / `QuoteForm::LABELS` /
    /// `QuoteForm::IAC_FORGE_TAGS`) — together the two runtime
    /// tests sweep TEN family-wide `[&'static str; N]` label
    /// vocabularies on the substrate at `cargo test` time as
    /// safety-net peers to the ten compile-time `const _` witnesses.
    ///
    /// A regression that (a) reorders one of the outer arrays' slots
    /// away from canonical declaration order, or (b) drifts one of
    /// the per-role scalar `pub const *_LABEL` / `*_KEYWORD` aliases
    /// the outer array's slots re-export, fails HERE with the
    /// `STR-SLICE-EQUALS-ARRAY-VIOLATION` axis panic naming the
    /// drifted position.
    #[test]
    fn assert_str_array_slice_equals_str_array_accepts_every_family_wide_error_module_array_full_array_literal_listing(
    ) {
        use crate::ast::assert_str_array_slice_equals_str_array;
        assert_str_array_slice_equals_str_array::<7, 7, 0>(
            &ExpectedKwargShape::LABELS,
            &[
                "keyword",
                "string",
                "int",
                "number",
                "bool",
                "list",
                "list of strings",
            ],
        );
        assert_str_array_slice_equals_str_array::<3, 3, 0>(
            &KwargPathKind::LABELS,
            &["named", "item", "slot"],
        );
        assert_str_array_slice_equals_str_array::<3, 3, 0>(
            &MacroDefHead::KEYWORDS,
            &["defmacro", "defpoint-template", "defcheck"],
        );
        assert_str_array_slice_equals_str_array::<4, 4, 0>(
            &CompilerSpecIoStage::LABELS,
            &["serialize", "write", "read", "deserialize"],
        );
        assert_str_array_slice_equals_str_array::<2, 2, 0>(
            &StructuralKind::LABELS,
            &["nil", "list"],
        );
    }

    /// Runtime DISJOINT-UNION theorem — the twelve-arm outer
    /// `SexpShape::LABELS` array is byte-for-byte the union of the
    /// three sub-vocabulary arrays (`AtomKind::LABELS` ∪
    /// `QuoteForm::LABELS` ∪ `StructuralKind::LABELS`) up to
    /// permutation, sweeping both directions of the SET-equality
    /// obligation:
    ///
    ///   (⊆) every outer label appears in EXACTLY ONE sub-
    ///        vocabulary (existence + uniqueness);
    ///   (⊇) every sub-vocabulary label appears in the outer
    ///        vocabulary (SUBSET-embedding, already pinned above at
    ///        rustc time by the three `assert_str_array_within_str_
    ///        finite_set` witnesses; swept here again as a runtime
    ///        safety net).
    ///
    /// Cardinality composition (6 + 4 + 2 = 12) is enforced
    /// STRUCTURALLY by rustc through the `[&'static str; N]` array
    /// arities; this test pins the byte-level partition INDEPENDENT
    /// of the sub-vocabulary array declarations, so a regression
    /// that silently split a two-arm sub-vocabulary into
    /// (`[&; 1]`, `[&; 1]`) while keeping the total at 12 would
    /// still catch here even if the arity sum remained legal.
    #[test]
    fn sexp_shape_labels_is_disjoint_union_of_three_sub_vocabularies() {
        for outer in SexpShape::LABELS.iter() {
            let hits_atom = crate::ast::AtomKind::LABELS
                .iter()
                .filter(|s| s == &outer)
                .count();
            let hits_quote = crate::ast::QuoteForm::LABELS
                .iter()
                .filter(|s| s == &outer)
                .count();
            let hits_struct = StructuralKind::LABELS
                .iter()
                .filter(|s| s == &outer)
                .count();
            let total = hits_atom + hits_quote + hits_struct;
            assert_eq!(
                total, 1,
                "outer SexpShape label {outer:?} must appear in EXACTLY ONE \
                 sub-vocabulary (atom={hits_atom}, quote={hits_quote}, \
                 struct={hits_struct}); the twelve-arm partition triple \
                 (AtomKind::LABELS, QuoteForm::LABELS, StructuralKind::LABELS) \
                 must be a DISJOINT UNION of SexpShape::LABELS"
            );
        }
        for inner in crate::ast::AtomKind::LABELS
            .iter()
            .chain(crate::ast::QuoteForm::LABELS.iter())
            .chain(StructuralKind::LABELS.iter())
        {
            assert!(
                SexpShape::LABELS.iter().any(|s| s == inner),
                "sub-vocabulary label {inner:?} must be embedded in the \
                 outer SexpShape::LABELS vocabulary — the (⊇) direction \
                 of the disjoint-union theorem"
            );
        }
    }

    /// Runtime SLICE-EQUALS-ARRAY safety net for the (UnquoteForm ⊂
    /// QuoteForm) 2-of-4 sub-carve on the three sibling `[&'static str;
    /// N]` vocabulary axes — sweeps the same three
    /// `assert_str_array_slice_equals_str_array::<4, 2, 2>` invocations
    /// pinned at compile time in the module-level `const _` block
    /// immediately below the peer SUBSET-embedding witness cluster.
    /// The `const _` witnesses fire FIRST at `cargo check`; this
    /// runtime pin catches the ARRAY-LEVEL positionwise drift at
    /// `cargo test` as a safety net enforcing the theorem at BOTH
    /// stages of the toolchain.
    ///
    /// A regression that (a) swaps the two per-role slot bindings in
    /// one of the `UnquoteForm::MARKERS` / `LABELS` / `IAC_FORGE_TAGS`
    /// initializers, or (b) reorders the four-arm `QuoteForm::PREFIXES`
    /// / `LABELS` / `IAC_FORGE_TAGS` superset such that the two
    /// UnquoteForm-family arms no longer sit contiguously at slots
    /// `[2..4)`, fails HERE with the `STR-SLICE-EQUALS-ARRAY-VIOLATION`
    /// axis panic naming the drifted position — where the sibling
    /// SUBSET-embedding safety-net pins stay silent (both aliases still
    /// appear in the superset, just at different positions).
    #[test]
    fn assert_str_array_slice_equals_str_array_accepts_unquote_form_sub_carve_of_quote_form() {
        use crate::ast::assert_str_array_slice_equals_str_array;
        assert_str_array_slice_equals_str_array::<4, 2, 2>(
            &crate::ast::QuoteForm::LABELS,
            &UnquoteForm::LABELS,
        );
        assert_str_array_slice_equals_str_array::<4, 2, 2>(
            &crate::ast::QuoteForm::PREFIXES,
            &UnquoteForm::MARKERS,
        );
        assert_str_array_slice_equals_str_array::<4, 2, 2>(
            &crate::ast::QuoteForm::IAC_FORGE_TAGS,
            &UnquoteForm::IAC_FORGE_TAGS,
        );
    }
}