tatara_lisp/

ast.rs

//! S-expression AST.

use crate::error::{SexpShape, SexpWitness, StructuralKind, UnquoteForm};
use std::fmt;
// Bring `fmt::Write` into scope so `f.write_char(Self::LIST_OPEN)` at
// [`fmt::Display for Sexp`] resolves — the outer-structural delimiter
// arms of the `Self::Nil` / `Self::List` rendering routes through
// [`Sexp::LIST_OPEN`] / [`Sexp::LIST_CLOSE`] via `fmt::Write::write_char`
// rather than through the format! machinery (`write!(f, "{}", '(')`)
// so the (typed delimiter, formatter emission) pair binds directly on
// the closed-set outer-algebra without a per-char formatting round-trip.
// The `as _` alias imports the trait's methods without adding a name to
// the ast.rs namespace, matching the Rust idiom for extension-trait
// import hygiene.
use std::fmt::Write as _;
use std::hash::{Hash, Hasher};

/// Compile-time contract verifier — panics at const evaluation time if
/// any two entries of `arr` alias byte-for-byte.
///
/// Lifts the "each family-wide `[char; N]` on the substrate's reader-
/// boundary vocabulary is pairwise distinct" invariant from a runtime
/// pin-per-array (`sexp_non_whitespace_bare_atom_terminators_are_
/// pairwise_distinct`, `sexp_list_delimiters_pairwise_distinct`,
/// `sexp_comment_delimiters_pairwise_distinct`, `quote_form_leads_
/// pairwise_distinct`, `atom_self_escape_table_pairwise_distinct`,
/// `atom_escape_sources_pairwise_distinct`, `atom_escape_decoded_
/// pairwise_distinct`) into a COMPILE-TIME theorem the substrate
/// carries at every array declaration via a co-located `const _: () =
/// assert_char_array_pairwise_distinct(&Self::FOO_ARRAY);` witness.
///
/// The invariant is load-bearing for every consumer that pattern-
/// matches the array's entries as DISJOINT arms — the reader's outer-
/// dispatch cascade in `crate::reader::tokenize` matches on the four
/// [`Sexp::LIST_OPEN`] / [`Sexp::LIST_CLOSE`] / [`Atom::STR_DELIMITER`]
/// / [`Sexp::COMMENT_LEAD`] arms (a duplicate here would break the
/// `match c { … }` exhaustiveness); [`Atom::decode_str_escape`]'s
/// escape table matches on the FIVE [`Atom::ESCAPE_SOURCES`] arms
/// (a duplicate here would silently shadow the second arm);
/// [`QuoteForm::from_lead_char`] matches on the THREE [`QuoteForm::LEADS`]
/// arms (a duplicate here would break the three-way outer-dispatch);
/// and every future family-wide `[char; N]` on the substrate that
/// participates in a `match`-arm partition benefits from the SAME
/// compile-time guarantee via one `const _` line.
///
/// Pre-lift each array carried its pairwise-distinctness contract at
/// ONE runtime test (`cargo test`-triggered): a regression that
/// silently collided two entries would compile cleanly and fail only
/// at test run. Post-lift the contract binds at `cargo check` time —
/// the const-eval panic surfaces the collision at COMPILE time, one
/// invocation stage earlier, catching regressions on `cargo build` /
/// `cargo clippy` runs that skip the test suite.
///
/// Adding a new family-wide `[char; N]` array to the substrate: pair
/// the declaration with `const _: () = assert_char_array_pairwise_
/// distinct(&Self::FOO_ARRAY);` co-located immediately after the
/// array's declaration and the distinctness contract is enforced at
/// compile time. The rustc-forced arity `[char; N]` composes with
/// this const-eval sweep so BOTH cardinality AND injectivity are
/// compile-time theorems on the SAME array.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — e.g. a REPL / LSP tokenizer
/// that constructs a `[char; N]` at runtime and wants to verify
/// pairwise distinctness before consuming it — and the panic surfaces
/// normally in that path (pinned by `assert_char_array_pairwise_
/// distinct_panics_at_runtime_on_collision`).
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the family-wide distinctness
///   contract becomes a TYPE-LEVEL theorem the substrate carries per
///   array declaration rather than a runtime test the developer must
///   remember to write per array.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   sweep IS the generative shape. Every new closed-set char array
///   adds ONE `const _` line to get the distinctness theorem rather
///   than re-deriving a `HashSet::insert` loop test per array.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs; the
///   distinctness proof at declaration site AND the outer-dispatch
///   match-arm exhaustiveness the consumer relies on regenerate
///   through the SAME `const _` witness.
pub const fn assert_char_array_pairwise_distinct<const N: usize>(arr: &[char; N]) {
    let mut i = 0;
    while i < N {
        let mut j = i + 1;
        while j < N {
            if arr[i] as u32 == arr[j] as u32 {
                panic!(
                    "assert_char_array_pairwise_distinct: family-wide \
                     char array carries a duplicate entry across two \
                     positions — the substrate's pairwise-distinctness \
                     contract on the array is broken; every consumer \
                     that pattern-matches the array's entries as \
                     DISJOINT arms (reader outer-dispatch, escape-table \
                     decode, quote-family lead dispatch) relies on this \
                     invariant"
                );
            }
            j += 1;
        }
        i += 1;
    }
}

// Compile-time pairwise-distinctness witnesses — one `const _: () =
// assert_char_array_pairwise_distinct(&…)` per family-wide `[char; N]`
// char array on the substrate's reader-boundary vocabulary. Each
// invocation is const-evaluated at `cargo check` time; a regression
// that silently collides two entries fails the build rather than the
// test suite. Sibling to the runtime `_pairwise_distinct` tests at
// `ast.rs`'s tests module — the two enforce the same theorem at TWO
// stages of the toolchain, so a build that skips tests still catches
// the regression here, and a build that runs tests catches it a
// second time as a safety net if the const-eval sweep is ever
// silently dropped.
const _: () = assert_char_array_pairwise_distinct(&Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS);
const _: () = assert_char_array_pairwise_distinct(&Sexp::LIST_DELIMITERS);
const _: () = assert_char_array_pairwise_distinct(&Sexp::COMMENT_DELIMITERS);
const _: () = assert_char_array_pairwise_distinct(&QuoteForm::LEADS);
const _: () = assert_char_array_pairwise_distinct(&Atom::SELF_ESCAPE_TABLE);
const _: () = assert_char_array_pairwise_distinct(&Atom::ESCAPE_SOURCES);
const _: () = assert_char_array_pairwise_distinct(&Atom::ESCAPE_DECODED);

/// Compile-time contract verifier — panics at const evaluation time if
/// any entry of `arr` carries a Unicode scalar value outside the
/// seven-bit ASCII range (`> 0x7F`).
///
/// Element-type row-dual peer to [`assert_str_array_all_ascii`] on the
/// (element-type) axis of the (element-type × contract-shape) matrix at
/// the (per-entry, ASCII) column: where the (`&'static str`) sibling
/// closes the ASCII-BYTE-RANGE per-entry corner on the substrate's
/// closed-set outer algebras' family-wide `[&'static str; N]` label
/// vocabularies, this (`char`) sibling closes the SAME per-entry
/// contract-shape corner on the substrate's reader-boundary `[char; N]`
/// scalar vocabularies. The two helpers close the (element-type ∈
/// {char, `&'static str`} × contract-shape ∈ {ASCII}) 2-corner row of
/// the per-entry ASCII column at ONE peer const-fn helper per element-
/// type. Contract-orthogonal peer to
/// [`assert_char_array_pairwise_distinct`] on the (INJECTIVITY, ASCII)
/// axis of the (per-entry × set-level) column on the SAME (`char`) row:
/// where the pairwise-distinctness sibling binds SET-LEVEL `∀ i ≠ j :
/// arr[i] ≠ arr[j]`, this ASCII sibling binds PER-ENTRY `∀ i : (arr[i]
/// as u32) <= 0x7F` — the two together give every `[char; N]` sub-
/// vocabulary on the substrate BOTH set-level injectivity AND per-
/// entry byte-range containment at compile time. Note the (per-entry,
/// NONEMPTY) corner from the (`&'static str`) row is intentionally
/// absent here: a `char` is a single Unicode scalar value and carries
/// no length dimension, so the NONEMPTY per-entry gate degenerates to
/// a vacuous tautology on the (`char`) row and needs no peer.
///
/// The invariant is load-bearing for every consumer that ships an
/// array entry through a downstream surface whose canonical form is
/// seven-bit-clean — the reader's `matches!(c, LIST_OPEN | LIST_CLOSE
/// | …)` outer-dispatch on [`Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS`]
/// entries; the tokenizer's byte-level scan on [`Sexp::LIST_DELIMITERS`]
/// / [`Sexp::COMMENT_DELIMITERS`] / [`QuoteForm::LEADS`] entries; the
/// atom-payload escape-decode dispatch on [`Atom::SELF_ESCAPE_TABLE`] /
/// [`Atom::ESCAPE_SOURCES`] / [`Atom::ESCAPE_DECODED`] entries. Every
/// consumer treats each entry as a single seven-bit-clean ASCII scalar;
/// a regression that silently re-inlined `LIST_OPEN = '（'` (fullwidth
/// U+FF08) or `QUOTE_LEAD = '‘'` (U+2018) — lookalike scalars that
/// would parse as a Rust `char` literal but ship a multi-byte UTF-8
/// sequence at every reader-boundary byte comparison — fails at `cargo
/// check` BEFORE any test scheduler runs.
///
/// Adding a new family-wide `[char; N]` reader-boundary scalar
/// vocabulary whose canonical spelling is seven-bit-clean: pair the
/// declaration with `const _: () = assert_char_array_all_ascii
/// (&Self::FOO_ARRAY);` co-located after the array's declaration and
/// the ASCII-SCALAR-RANGE contract binds at compile time. The rustc-
/// forced arity `[char; N]` composes with this const-eval sweep so
/// BOTH cardinality AND per-entry ASCII are compile-time theorems on
/// the SAME array declaration.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — pinned by
/// `assert_char_array_all_ascii_panics_at_runtime_on_head_non_ascii` /
/// `_interior_non_ascii` / `_tail_non_ascii` and
/// `assert_char_array_all_ascii_panic_message_names_the_helper_and_axis`.
/// The panic site carries the `"CHAR-NON-ASCII-SCALAR"` axis-
/// provenance string chosen DISTINCT from every sibling helper's axis
/// vocabulary (`"duplicate"` on the pairwise-distinct sibling;
/// `"CHAR-SUBSET-VIOLATION"` on the within-finite-set sibling;
/// `"CHAR-DISJOINTNESS-VIOLATION"` on the arrays-disjoint sibling;
/// `"STR-NON-ASCII-ENTRY"` on the (`&'static str`) row-dual ASCII
/// sibling) so a diagnostic that names the failed axis routes
/// UNAMBIGUOUSLY to THIS specific (`char`)-row ASCII helper. The
/// `"CHAR-"` prefix disambiguates from the (`&'static str`) row-dual
/// ASCII sibling; the shared `"-NON-ASCII-"` infix lets callers grep
/// any row's ASCII sibling by `"NON-ASCII"` alone.
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the family-wide per-entry
///   ASCII-scalar-range contract on the substrate's reader-boundary
///   `char` vocabulary becomes a TYPE-LEVEL theorem the substrate
///   carries per array declaration rather than a runtime test the
///   developer must remember to write per scalar constant.
/// - THEORY.md §II.1 invariant 1 — typed entry; a reader-boundary
///   scalar's `char` projection IS the entry-point discriminator into
///   the tokenizer's outer dispatch, and a non-ASCII scalar in that
///   projection silently escapes the byte-level assumption every
///   downstream parser encodes into its own byte-position arithmetic.
/// - THEORY.md §III — the typescape; the (element-type × contract-
///   shape) matrix now carries the ASCII per-entry corner on TWO rows
///   ({`char`, `&'static str`}) at ONE peer const-fn helper per row.
///   The (element-type ∈ {char, `&'static str`}) × (contract-shape ∈
///   {per-entry ASCII}) 2-corner row of the per-entry ASCII column is
///   now closed at TWO peer const-fn helpers.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   scalar-range sweep IS the generative shape. Every new closed-set
///   reader-boundary scalar array adds ONE `const _` line to get the
///   ASCII theorem rather than re-deriving a per-array runtime iterator
///   sweep at each call site.
///
/// Frontier inspiration: Lean 4's `List.all` unfolded to `∀ i : arr[i]
/// ∈ ascii` at the concrete `[char; N]` monomorphic realisation, where
/// `ascii := { c : Char // c.toNat ≤ 0x7F }`. The (`char`, `&'static
/// str`) row-dual pair mirrors Lean's element-polymorphic `List α`
/// realised at the two concrete element-type instantiations the
/// substrate closes at compile time.
pub const fn assert_char_array_all_ascii<const N: usize>(arr: &[char; N]) {
    let mut i = 0;
    while i < N {
        if arr[i] as u32 > 0x7F {
            panic!(
                "assert_char_array_all_ascii: CHAR-NON-ASCII-SCALAR — \
                 the family-wide char array carries an entry with a \
                 Unicode scalar value outside the seven-bit ASCII \
                 range (> 0x7F) at some position — the substrate's \
                 ASCII-SCALAR-RANGE contract on the array is broken; \
                 every consumer that ships an entry through a seven-\
                 bit-clean reader-boundary surface (the reader's \
                 `matches!(c, LIST_OPEN | ...)` outer-dispatch on \
                 NON_WHITESPACE_BARE_ATOM_TERMINATORS entries; the \
                 tokenizer's byte-level scan on LIST_DELIMITERS / \
                 COMMENT_DELIMITERS / QuoteForm::LEADS entries; the \
                 atom-payload escape-decode dispatch on SELF_ESCAPE_\
                 TABLE / ESCAPE_SOURCES / ESCAPE_DECODED entries) \
                 treats each entry as a single seven-bit-clean ASCII \
                 scalar — a non-ASCII scalar silently invites lookalike-\
                 char collisions (fullwidth U+FF08 `（` vs ASCII U+0028 \
                 `(`) and multi-byte UTF-8 drift that byte-position \
                 arithmetic cannot detect. Fix at the ARRAY-DECLARATION \
                 site by re-inlining the offending scalar constant to \
                 its seven-bit-clean canonical spelling"
            );
        }
        i += 1;
    }
}

// Compile-time ASCII-SCALAR-RANGE witnesses — one `const _: () =
// assert_char_array_all_ascii(&…)` per family-wide `[char; N]` char
// array on the substrate's reader-boundary vocabulary. Each invocation
// is const-evaluated at `cargo check` time; a regression that silently
// re-inlined one scalar constant to a lookalike non-ASCII scalar
// (fullwidth U+FF08 `（`, curly-quote U+2018 `‘`, etc.) fails the
// build rather than deferring to a per-consumer byte-parse
// misbehavior at runtime. Sibling to the pairwise-distinctness
// witnesses above — those pin SET-LEVEL INJECTIVITY on each array,
// these pin the strictly-orthogonal PER-ENTRY byte-range gate on the
// SAME arrays. The two contracts compose orthogonally on every reader-
// boundary `[char; N]` scalar vocabulary. The seven arrays covered
// here mirror the seven arrays already pinned by the
// `_pairwise_distinct` witnesses above — the (per-entry × set-level)
// coverage matrix on the (`char`) row of this file now holds at TWO
// corners {INJECTIVITY (set-level), ASCII (per-entry)} for the seven
// reader-boundary arrays declared here.
const _: () = assert_char_array_all_ascii(&Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS);
const _: () = assert_char_array_all_ascii(&Sexp::LIST_DELIMITERS);
const _: () = assert_char_array_all_ascii(&Sexp::COMMENT_DELIMITERS);
const _: () = assert_char_array_all_ascii(&QuoteForm::LEADS);
const _: () = assert_char_array_all_ascii(&Atom::SELF_ESCAPE_TABLE);
const _: () = assert_char_array_all_ascii(&Atom::ESCAPE_SOURCES);
const _: () = assert_char_array_all_ascii(&Atom::ESCAPE_DECODED);

/// Compile-time contract verifier — panics at const evaluation time if
/// the distinct-values set of `arr` is not a subset of the distinct-
/// values set of `set` on the substrate's reader-boundary `char`
/// vocabulary. Binds ONE conjunct clause: CHAR-SUBSET-VIOLATION —
/// every entry in `arr` MUST also appear as an entry in `set`.
///
/// Element-type column-dual peer to
/// [`assert_u8_array_within_u8_finite_set`] on the (element-type) axis:
/// where the `u8` sibling closes the SUBSET-EMBEDDING corner on the
/// outer-`Sexp` cache-key `u8` vocabulary, this `char` sibling closes
/// the SAME corner on the reader-boundary `char` vocabulary. The two
/// helpers close the SUBSET-EMBEDDING × non-contiguous-target-set
/// corner of the (element-type × contract-shape) matrix at ONE
/// primitive per element-type row rather than at a per-embedding
/// runtime iterator sweep per call site. Contract-strength peer to
/// (the future-lift) `assert_char_array_covers_char_finite_set` on the
/// (equality-vs-subset) axis: this helper binds ONLY arr ⊆ set (the
/// SUBSET-VIOLATION arm read in isolation without the SET-CHAR-MISSING
/// full-coverage clause) — a strictly WEAKER contract for arrays that
/// intentionally cover only a PROPER SUBSET of the target partition.
///
/// SET-side well-formedness delegation: [`assert_char_array_pairwise_distinct`]
/// is called on `set` at the top of the helper as the SET-side well-
/// formedness gate. Placed FIRST so drift on the CALLER'S TARGET-SET
/// SPEC (e.g. `['a', 'a', 'b']` fed as `set`) routes to the SET-side
/// well-formedness axis (via the sibling's `"assert_char_array_
/// pairwise_distinct"` panic-name prefix) rather than to a downstream
/// CHAR-SUBSET-VIOLATION symptom on `arr`. Delegates to the SAME
/// helper the ARRAY-side pairwise-distinctness pin uses rather than to
/// a bespoke `assert_char_finite_set_pairwise_distinct` alias because
/// the char row does NOT yet carry a sibling `_covers_char_finite_set`
/// / `_permutes_char_finite_set` helper that would benefit from a
/// distinct SET-side axis-provenance vocabulary across three call
/// sites — the (u8) row's separate `assert_u8_finite_set_pairwise_distinct`
/// alias exists exactly because the finite-set-family compound helpers
/// (`_within_u8_finite_set`, `_covers_u8_finite_set`,
/// `_permutes_u8_finite_set`) all delegate to it. When the char row
/// grows its second finite-set-family compound helper, a future run
/// lifts the SET-side alias then; today the delegation reuses the
/// ARRAY-side helper directly. A well-formed `set` passes this arm as
/// a no-op — const-eval-elidable at rustc-time on the substrate call
/// site.
///
/// The invariant is load-bearing for three intentionally-closed
/// SUBSET-embedding relations on the substrate's reader-boundary
/// `char` vocabulary that pre-lift lived only as prose in the
/// [`Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS`] docstring's
/// four-category composition rule (LIST_DELIMITERS + QuoteForm::LEADS +
/// {STR_DELIMITER} + {COMMENT_LEAD}):
///
///   1. [`Sexp::LIST_DELIMITERS`] (`[char; 2]` = `[LIST_OPEN,
///      LIST_CLOSE]` — the outer-structural paired-delimiter arm-set)
///      MUST be a SUBSET of
///      [`Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS`] (`[char; 7]`
///      — the reader outer-dispatch category-leading char ALL array).
///      A drift that dropped `LIST_OPEN` (or `LIST_CLOSE`) from
///      `NON_WHITESPACE_BARE_ATOM_TERMINATORS` while it stayed in
///      `LIST_DELIMITERS` (or vice versa: a drift that re-inlined
///      `LIST_DELIMITERS` to a fresh char not in the terminator ALL
///      array) would silently break the four-category composition
///      rule. Post-lift the SUBSET embedding binds at rustc time.
///
///   2. [`QuoteForm::LEADS`] (`[char; 3]` = `[QUOTE_LEAD,
///      QUASIQUOTE_LEAD, UNQUOTE_LEAD]` — the quote-family lead-char
///      sub-vocabulary) MUST be a SUBSET of
///      [`Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS`]. Same argument
///      as above on the three quote-lead category of the four-category
///      composition rule.
///
///   3. [`Atom::SELF_ESCAPE_TABLE`] (`[char; 2]` = `[STR_DELIMITER,
///      STR_ESCAPE_LEAD]` — the pattern-EQUALS-value sub-vocabulary of
///      the escape arm-set) MUST be a SUBSET of
///      [`Atom::ESCAPE_SOURCES`] (`[char; 5]` — the SOURCE-column
///      SPAN of all five non-passthrough escape arms). A drift that
///      re-inlined a SELF entry to a fresh char not in the SOURCE-
///      column SPAN would silently violate the composition law
///      `ESCAPE_SOURCES == [NAMED[0].0, NAMED[1].0, NAMED[2].0,
///      SELF[0], SELF[1]]` at the SELF-slot suffix. Post-lift the
///      SUBSET embedding binds at rustc time.
///
/// Every future family-wide `[char; N]` typed-subset carving on the
/// substrate's reader-boundary vocabulary participates in the SAME
/// compile-time guarantee via one `const _` line.
///
/// Adding a new family-wide `[char; N]` subset-embedded array to the
/// substrate: pair the declaration with `const _: () =
/// assert_char_array_within_char_finite_set::<N, M>(&Self::FOO_ARRAY,
/// &Other::SUPERSET_ARRAY);` co-located after the array's declaration
/// and the SUBSET contract binds at compile time. The rustc-forced
/// arities `[char; N]` and `[char; M]` compose with this const-eval
/// sweep so BOTH cardinality-pair AND every-entry-in-superset are
/// compile-time theorems on the SAME (subset, superset) char-array
/// pair.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — pinned by
/// `assert_char_array_within_char_finite_set_panics_at_runtime_on_out_of_set_entry`
/// and
/// `assert_char_array_within_char_finite_set_panic_message_names_the_helper_and_char_subset_violation_axis`.
/// The panic site carries the `"CHAR-SUBSET-VIOLATION"` axis-
/// provenance string chosen DISTINCT from every sibling helper's axis
/// vocabulary (`"duplicate"` on the ARRAY-side pairwise-distinct
/// sibling; `"SUBSET-VIOLATION"` on the (u8) finite-set SUBSET-only
/// sibling; `"RANGE-SUBSET-VIOLATION"` on the (u8) range SUBSET-only
/// sibling; `"OUT-OF-SET"` / `"SET-BYTE-MISSING"` on the (u8) covers-
/// finite-set sibling; `"OUT-OF-RANGE"` / `"MISSING"` on the (u8)
/// covers-inclusive-range sibling; `"ARITY-MISMATCH"` on both (u8)
/// `_permutes_*` compound helpers; `"SET-NOT-PAIRWISE-DISTINCT"` on
/// the (u8) SET-side well-formedness sibling) so a diagnostic that
/// names the failed axis routes UNAMBIGUOUSLY to THIS specific char
/// SUBSET-embedding helper. The `"CHAR-"` prefix disambiguates from
/// the (u8) SUBSET-only helper's bare `"SUBSET-VIOLATION"`; the shared
/// `"-VIOLATION"` suffix lets callers grep either SUBSET-embedding
/// sibling by `"VIOLATION"` alone or route to the specific element-
/// type row by the disambiguator prefix.
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the family-wide subset-
///   embedding contract on the reader-boundary `char` vocabulary
///   becomes a TYPE-LEVEL theorem the substrate carries per (subset,
///   superset) array pair rather than a runtime test the developer
///   must remember to write per embedding. The three witness sites
///   above (`LIST_DELIMITERS ⊆ NON_WHITESPACE_BARE_ATOM_TERMINATORS`,
///   `QuoteForm::LEADS ⊆ NON_WHITESPACE_BARE_ATOM_TERMINATORS`,
///   `SELF_ESCAPE_TABLE ⊆ ESCAPE_SOURCES`) previously lived only as
///   prose in their parent arrays' composition-rule docstrings.
/// - THEORY.md §III — the typescape; the (element-type × contract-
///   shape) matrix now carries the SUBSET-EMBEDDING corner at BOTH
///   the `u8` row and the `char` row, closing the element-type column
///   on the SUBSET-corner face at two peer const-fn helpers rather
///   than at one primitive with a runtime cast per element-type.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   set-membership sweep IS the generative shape. Every new closed-
///   set `char` sub-vocabulary array whose distinct-value set is an
///   intentional SUBSET of another substrate `char` array adds ONE
///   `const _` line to get the subset-embedding theorem rather than
///   re-deriving a per-embedding runtime iterator sweep at each call
///   site.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs; the
///   SUBSET-embedding proof at declaration site AND the reader outer-
///   dispatch cascade's four-category exhaustiveness contract (which
///   assumes LIST_DELIMITERS + QuoteForm::LEADS + STR_DELIMITER +
///   COMMENT_LEAD partition the NON_WHITESPACE_BARE_ATOM_TERMINATORS
///   ALL array) regenerate through the SAME `const _` witnesses at
///   the ARRAY level.
///
/// Frontier inspiration: Lean 4's `Finset.instHasSubsetFinset :
/// (⊆) : Finset α → Finset α → Prop` as a decidable relation on
/// `Finset α` combined with `Finset.subset_iff` unfolding the relation
/// to per-element membership — the substrate primitive here embeds
/// the same subset relation as a rustc const-eval-time proof
/// obligation at every `assert_char_array_within_char_finite_set`
/// call site rather than as a Lean tactic invocation deferred to
/// `elab_command`. The element-type generalization from `u8` to `char`
/// mirrors Lean's polymorphism over the `α` type parameter on
/// `Finset`; the substrate binds the two concrete instantiations
/// (`u8` at [`assert_u8_array_within_u8_finite_set`], `char` here)
/// as separate `pub const fn`s because Rust's const-generic system
/// does not yet admit polymorphism over element type through a
/// custom trait bound at const-eval time. Each element-type row is a
/// monomorphic realisation of the SAME subset-embedding contract
/// shape.
pub const fn assert_char_array_within_char_finite_set<const N: usize, const M: usize>(
    arr: &[char; N],
    set: &[char; M],
) {
    // Delegate target-set well-formedness to the sibling ARRAY-side
    // pairwise-distinctness helper FIRST. Placed BEFORE the CHAR-
    // SUBSET-VIOLATION sweep below because a malformed `set` (e.g.
    // `['a', 'a', 'b']`) is not a well-formed finite set of
    // cardinality `M` and silently mis-verifies the intended subset
    // contract on any `arr` embedded in the DISTINCT-value subset.
    // Routes drift on the CALLER'S TARGET-SET SPEC to the SET-side
    // well-formedness axis (via the sibling's own panic-name prefix)
    // rather than to a downstream CHAR-SUBSET-VIOLATION symptom on
    // `arr`. A well-formed `set` passes this arm as a no-op — the
    // sweep is const-eval-elidable and costs zero at rustc-time on
    // the substrate call sites.
    assert_char_array_pairwise_distinct(set);
    let mut i = 0;
    while i < N {
        let mut j = 0;
        let mut found = false;
        while j < M {
            if arr[i] as u32 == set[j] as u32 {
                found = true;
                break;
            }
            j += 1;
        }
        if !found {
            panic!(
                "assert_char_array_within_char_finite_set: CHAR-\
                 SUBSET-VIOLATION — the family-wide char array `arr` \
                 carries an entry at some position whose char is NOT \
                 a member of the target finite superset partition \
                 `set`. The substrate's SUBSET-EMBEDDING contract on \
                 the array is broken; every consumer that expects the \
                 array's distinct-value set to be a subset of the \
                 target finite partition (`Sexp::LIST_DELIMITERS ⊂ \
                 Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS` on the \
                 outer-structural paired-delimiter axis of the reader \
                 outer-dispatch terminator ALL array; \
                 `QuoteForm::LEADS ⊂ \
                 Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS` on the \
                 quote-family lead-char axis of the SAME terminator \
                 ALL array; `Atom::SELF_ESCAPE_TABLE ⊂ \
                 Atom::ESCAPE_SOURCES` on the pattern-EQUALS-value \
                 sub-vocabulary axis of the escape-arm SOURCE-column \
                 SPAN; any future typed-subset embedding on the \
                 substrate's reader-boundary char algebras) relies on \
                 every array entry staying within the target \
                 superset. Fix at the ARRAY-DECLARATION site (the \
                 `arr` under verification, NOT the `set` argument \
                 specifying the target superset) by dropping the \
                 offending entry OR by extending `set` to cover it — \
                 the choice depends on whether the drift is an \
                 unintended overshoot outside the parent superset or \
                 an intentional extension of the superset vocabulary"
            );
        }
        i += 1;
    }
}

// Compile-time SUBSET-embedding witnesses — the THREE family-wide
// `[char; N]` intentionally-closed PROPER-SUBSET carvings on the
// substrate's reader-boundary vocabulary whose distinct-value set is
// a subset of another family-wide `[char; M]` array's distinct-value
// set. Pre-lift the three subset relations lived only as prose in the
// parent arrays' composition-rule docstrings (the four-category
// composition rule on `NON_WHITESPACE_BARE_ATOM_TERMINATORS`, the
// pattern-EQUALS-value sub-vocabulary partition on `ESCAPE_SOURCES`).
// Post-lift the three ARRAY-LEVEL subset embeddings bind at rustc
// time — a regression that re-inlined either the SUBSET or the
// SUPERSET side of any relation to a fresh char breaking the subset
// containment (e.g. dropping `Sexp::LIST_OPEN` from
// `NON_WHITESPACE_BARE_ATOM_TERMINATORS` while it stayed in
// `LIST_DELIMITERS`; drifting `QuoteForm::QUOTE_LEAD` to a fresh
// char not in the terminator ALL array; re-shuffling `ESCAPE_SOURCES`
// to swap its SELF-slot suffix bytes with unrelated NAMED-slot bytes)
// fails at `cargo check` BEFORE any test scheduler runs. Sibling to
// the pairwise-distinctness witnesses above — those pin INJECTIVITY
// on each individual array, these pin SUBSET containment across
// PAIRS of arrays.
const _: () = assert_char_array_within_char_finite_set::<2, 7>(
    &Sexp::LIST_DELIMITERS,
    &Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS,
);
const _: () = assert_char_array_within_char_finite_set::<3, 7>(
    &QuoteForm::LEADS,
    &Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS,
);
const _: () = assert_char_array_within_char_finite_set::<2, 5>(
    &Atom::SELF_ESCAPE_TABLE,
    &Atom::ESCAPE_SOURCES,
);

/// Compile-time contract verifier — panics at const evaluation time if
/// the distinct-values sets of `a` and `b` share any char on the
/// substrate's reader-boundary `char` vocabulary. Binds ONE conjunct
/// clause: CHAR-DISJOINTNESS-VIOLATION — no entry in `a` may appear as
/// an entry in `b` (symmetric across the two array arguments).
///
/// Contract-orthogonal peer to [`assert_char_array_within_char_finite_set`]
/// on the (subset-vs-disjointness) axis of the (contract-shape) axis:
/// where the SUBSET-EMBEDDING helper binds `arr ⊆ set` at compile time
/// on the (char) row, this DISJOINTNESS helper binds `a ∩ b = ∅` at
/// compile time on the SAME element-type row. Together the two helpers
/// close the (subset, disjointness) 2-corner face on the (char)
/// contract-shape column at ONE primitive per corner rather than at a
/// per-pair runtime iterator sweep per call site. The disjointness
/// relation is SYMMETRIC (unlike the SUBSET-EMBEDDING relation, which
/// distinguishes `arr` from `set`) so the two arguments carry NO axis-
/// provenance role split — either drift site (a char in `a` that
/// aliases a char in `b`, OR a char in `b` that aliases a char in `a`)
/// surfaces at the CHAR-DISJOINTNESS-VIOLATION panic with the OFFENDING
/// arm named by BOTH position indices (`a[i]` AND `b[j]`) rather than
/// by only one side of the pair.
///
/// SYMMETRY IN THE NESTED SWEEP: the inner `while j < M` sweep visits
/// every position of `b` per outer `i` and panics at the FIRST cross-
/// array collision (`a[i] == b[j]`). Because the relation is symmetric
/// and the two-loop sweep visits every `(i, j) ∈ [0, N) × [0, M)` pair,
/// swapping `a` and `b` at the call site produces the SAME verdict —
/// the helper does NOT gratuitously depend on argument order. A future
/// call site that intends to name a SPECIFIC drift side can still route
/// its own preferred first-mention by picking the argument order that
/// serves its diagnostic story; the helper itself carries no such
/// preference.
///
/// The invariant is load-bearing for the reader's outer-dispatch
/// cascade at [`crate::reader::tokenize`]: the SIX outer-dispatch
/// category-leading char families the tokenizer specialises on
/// ([`Sexp::LIST_OPEN`] / [`Sexp::LIST_CLOSE`] arm; every
/// [`QuoteForm::lead_char`] arm; [`Atom::STR_DELIMITER`] arm;
/// [`Sexp::COMMENT_LEAD`] arm; whitespace arm) MUST route to DISJOINT
/// arms — otherwise a shared byte would silently reclassify at the
/// same-position outer dispatch (e.g. a `(` that aliased `,` would
/// silently promote a list-open byte through the quote-family arm, or
/// vice versa). Post-lift the disjointness of the substrate's pinned
/// arm-set pairs binds at rustc time via one `const _` line per pair.
///
/// The invariant is ALSO load-bearing for the Str-payload escape-arm
/// dispatch at [`Atom::decode_str_escape`]: the FIVE non-passthrough
/// escape arms partition into the [`Atom::SELF_ESCAPE_TABLE`] (2 rows,
/// pattern-EQUALS-value) and [`Atom::NAMED_ESCAPE_TABLE`] (3 rows,
/// pattern-DISTINCT-from-value) sub-vocabularies whose entries MUST
/// remain disjoint at the CHAR level from every other reader-boundary
/// sub-vocabulary — otherwise a Str-escape byte would silently
/// promote through the outer-dispatch cascade instead of staying inside
/// the Str-payload boundary.
///
/// Pre-lift the substrate carried these disjointness relations at ONE
/// runtime test per pair (`sexp_comment_delimiters_disjoint_from_list_delimiters`,
/// `sexp_list_delimiters_disjoint_from_comment_lead`, etc.); post-lift
/// the ARRAY-LEVEL disjointness binds at rustc time via one `const _`
/// line per pair. A regression that silently drifted `Sexp::LIST_OPEN`
/// to `';'` (colliding with `Sexp::COMMENT_LEAD`), or drifted
/// `QuoteForm::QUOTE_LEAD` to `'('` (colliding with `Sexp::LIST_OPEN`),
/// fails at `cargo check` BEFORE any test scheduler runs.
///
/// Adding a new family-wide `[char; N]` sub-vocabulary whose distinct-
/// values set must remain disjoint from another substrate `[char; M]`
/// array's distinct-values set: pair the declaration with `const _: ()
/// = assert_char_arrays_disjoint::<N, M>(&Self::FOO_ARRAY,
/// &Other::BAR_ARRAY);` co-located after the array's declaration and
/// the DISJOINTNESS contract binds at compile time. The rustc-forced
/// arities `[char; N]` and `[char; M]` compose with this const-eval
/// sweep so BOTH cardinality-pair AND cross-array disjointness are
/// compile-time theorems on the SAME (a, b) char-array pair.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — pinned by
/// `assert_char_arrays_disjoint_panics_at_runtime_on_collision` and
/// `assert_char_arrays_disjoint_panic_message_names_the_helper_and_char_disjointness_violation_axis`.
/// The panic site carries the `"CHAR-DISJOINTNESS-VIOLATION"` axis-
/// provenance string chosen DISTINCT from every sibling helper's axis
/// vocabulary (`"duplicate"` on the ARRAY-side pairwise-distinct
/// sibling; `"CHAR-SUBSET-VIOLATION"` on the (char) SUBSET-embedding
/// sibling; `"SUBSET-VIOLATION"` on the (u8) finite-set SUBSET-only
/// sibling; `"RANGE-SUBSET-VIOLATION"` on the (u8) range SUBSET-only
/// sibling; `"OUT-OF-SET"` / `"SET-BYTE-MISSING"` on the (u8) covers-
/// finite-set sibling; `"OUT-OF-RANGE"` / `"MISSING"` on the (u8)
/// covers-inclusive-range sibling; `"ARITY-MISMATCH"` on both (u8)
/// `_permutes_*` compound helpers; `"SET-NOT-PAIRWISE-DISTINCT"` on
/// the (u8) SET-side well-formedness sibling) so a diagnostic that
/// names the failed axis routes UNAMBIGUOUSLY to THIS specific
/// disjointness helper. The `"CHAR-"` prefix disambiguates from a
/// future-lift (u8) disjointness sibling; the `"-VIOLATION"` suffix
/// lets callers grep either DISJOINTNESS or SUBSET-embedding sibling
/// by `"VIOLATION"` alone or route to the specific contract-shape by
/// the axis stem (`"DISJOINTNESS"` vs `"SUBSET"`).
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the family-wide cross-array
///   disjointness contract on the reader-boundary `char` vocabulary
///   becomes a TYPE-LEVEL theorem the substrate carries per (a, b)
///   char-array pair rather than a runtime test the developer must
///   remember to write per pair.
/// - THEORY.md §III — the typescape; the (element-type × contract-
///   shape) matrix now carries the DISJOINTNESS corner on the (char)
///   row at ONE peer const-fn helper rather than at a per-pair runtime
///   iterator sweep. The (subset, disjointness) 2-corner face on the
///   (char) row is now closed at TWO peer const-fn helpers —
///   [`assert_char_array_within_char_finite_set`] on the SUBSET corner
///   and this helper on the DISJOINTNESS corner.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   cross-array membership sweep IS the generative shape. Every new
///   closed-set `char` sub-vocabulary array whose distinct-values set
///   is an intentionally-disjoint peer of another substrate `char`
///   array adds ONE `const _` line to get the disjointness theorem
///   rather than re-deriving a per-pair runtime iterator sweep at
///   each call site.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs; the
///   DISJOINTNESS proof at declaration site AND the reader outer-
///   dispatch cascade's arm-set partition contract regenerate through
///   the SAME `const _` witnesses at the ARRAY level.
///
/// Frontier inspiration: Lean 4's `Finset.Disjoint : Finset α →
/// Finset α → Prop` as a decidable relation on `Finset α` combined
/// with `Finset.disjoint_iff` unfolding the relation to negated
/// per-element membership — the substrate primitive here embeds the
/// same disjointness relation as a rustc const-eval-time proof
/// obligation at every `assert_char_arrays_disjoint` call site rather
/// than as a Lean tactic invocation deferred to `elab_command`. The
/// symmetric nested sweep mirrors Lean's `Finset.disjoint_iff_ne`
/// characterisation `∀ a ∈ s, ∀ b ∈ t, a ≠ b` at the concrete
/// two-array `[char; N] × [char; M]` monomorphic realisation.
pub const fn assert_char_arrays_disjoint<const N: usize, const M: usize>(
    a: &[char; N],
    b: &[char; M],
) {
    let mut i = 0;
    while i < N {
        let mut j = 0;
        while j < M {
            if a[i] as u32 == b[j] as u32 {
                panic!(
                    "assert_char_arrays_disjoint: CHAR-DISJOINTNESS-\
                     VIOLATION — the two family-wide char arrays `a` \
                     and `b` share an entry at some (i, j) position \
                     pair. The substrate's CROSS-ARRAY DISJOINTNESS \
                     contract on the pair is broken; every consumer \
                     that partitions the two arrays' distinct-values \
                     sets into disjoint sub-vocabularies of the reader-\
                     boundary char algebra (the reader outer-dispatch \
                     cascade's SIX category-leading char arm-set \
                     partition through `Sexp::LIST_DELIMITERS`, \
                     `QuoteForm::LEADS`, `Sexp::COMMENT_DELIMITERS`, \
                     `Atom::STR_DELIMITER`; the Str-payload escape-arm \
                     dispatch cascade through `Atom::SELF_ESCAPE_TABLE`, \
                     `Atom::NAMED_ESCAPE_TABLE`; any future typed-\
                     disjointness pair on the substrate's reader-\
                     boundary char algebras) relies on the two arrays' \
                     distinct-values sets NOT sharing a byte. Fix at \
                     WHICHEVER ARRAY-DECLARATION site drifted (the \
                     symmetric disjointness relation carries no built-\
                     in axis-provenance role split between `a` and `b`) \
                     by dropping the offending entry from one array OR \
                     re-shaping the partition to route the shared \
                     entry to a single sub-vocabulary"
                );
            }
            j += 1;
        }
        i += 1;
    }
}

// Compile-time DISJOINTNESS witnesses — the FIVE substrate-pinned
// (a, b) `[char; N] × [char; M]` pairs whose distinct-values sets are
// intentionally-closed disjoint sub-vocabularies of the reader-boundary
// char algebra. Pre-lift the five disjointness relations lived only as
// runtime tests (`sexp_comment_delimiters_disjoint_from_list_delimiters`
// on pair 1; `sexp_list_delimiters_disjoint_from_comment_lead` +
// `sexp_list_delimiters_disjoint_from_str_delimiter` +
// `sexp_comment_delimiters_disjoint_from_str_delimiter` as scalar-vs-
// array runtime pins peer to pairs 1–5; the implicit disjointness
// arms of `NON_WHITESPACE_BARE_ATOM_TERMINATORS`'s four-category
// composition rule between LIST_DELIMITERS + LEADS + {STR_DELIMITER,
// COMMENT_LEAD}); post-lift the ARRAY-LEVEL disjointness of the six
// pinned pairs binds at rustc time via one `const _` line per pair.
// A regression that silently drifted one of the eight arm-set-leading
// chars into another arm (e.g. `Sexp::LIST_OPEN` to `';'`, colliding
// with `Sexp::COMMENT_LEAD`; `QuoteForm::QUOTE_LEAD` to `'('`,
// colliding with `Sexp::LIST_OPEN`; `Atom::STR_DELIMITER` to `';'`,
// colliding with `Sexp::COMMENT_LEAD`; `Atom::STR_ESCAPE_LEAD` to
// `'\n'`, colliding with `Sexp::COMMENT_TERM`) fails at `cargo check`
// BEFORE any test scheduler runs. Sibling to the pairwise-distinctness
// witnesses above — those pin INJECTIVITY on each individual array,
// these pin DISJOINTNESS across PAIRS of arrays.
//
// The six pinned pairs jointly close the C(4, 2) = 6 pairwise-
// disjoint face on the four-array reader-boundary set
// `{Sexp::LIST_DELIMITERS, Sexp::COMMENT_DELIMITERS, QuoteForm::LEADS,
// Atom::SELF_ESCAPE_TABLE}` EXHAUSTIVELY — the same closure shape as
// the three-way `SexpShape::LABELS` partition proof in `error.rs`
// (which pins C(3, 2) = 3 pairs on the `AtomKind::LABELS`,
// `QuoteForm::LABELS`, `StructuralKind::LABELS` sub-vocabulary triple)
// scaled up to the four-array reader-boundary partition. Composed
// with the six ARRAY-side pairwise-distinctness `const _:` witnesses
// above, the substrate carries a full DISJOINT-UNION theorem on the
// reader-boundary partition
//   `LIST_DELIMITERS ⊕ COMMENT_DELIMITERS ⊕ QuoteForm::LEADS ⊕
//    Atom::SELF_ESCAPE_TABLE`
// (with cardinality 2 + 2 + 3 + 2 = 9) as a rustc-time proof
// obligation, closing the eight-arm reader-boundary vocabulary
// partition at compile time.
const _: () =
    assert_char_arrays_disjoint::<2, 2>(&Sexp::LIST_DELIMITERS, &Sexp::COMMENT_DELIMITERS);
const _: () = assert_char_arrays_disjoint::<2, 3>(&Sexp::LIST_DELIMITERS, &QuoteForm::LEADS);
const _: () = assert_char_arrays_disjoint::<2, 3>(&Sexp::COMMENT_DELIMITERS, &QuoteForm::LEADS);
const _: () = assert_char_arrays_disjoint::<2, 2>(&Sexp::LIST_DELIMITERS, &Atom::SELF_ESCAPE_TABLE);
const _: () = assert_char_arrays_disjoint::<3, 2>(&QuoteForm::LEADS, &Atom::SELF_ESCAPE_TABLE);
// The sixth (Sexp::COMMENT_DELIMITERS × Atom::SELF_ESCAPE_TABLE) pair
// pins that the comment-boundary vocabulary `{COMMENT_LEAD (`;`),
// COMMENT_TERM (`\n`)}` and the string self-escape vocabulary
// `{STR_DELIMITER (`"`), STR_ESCAPE_LEAD (`\\`)}` remain byte-
// disjoint. Load-bearing because a regression that renamed
// `Sexp::COMMENT_LEAD` from `';'` to `'"'` would make `'"'` both a
// string opener AND a comment starter (silently swallowing every
// string literal into a comment run at the reader's outer dispatch
// cascade), and a regression that renamed `Atom::STR_ESCAPE_LEAD`
// from `'\\'` to `'\n'` would silently mis-terminate every string
// literal at the first newline (drifting the reader-boundary
// vocabulary into overlap with the comment-boundary vocabulary).
// Closes the sixth (C, S) corner of the C(4, 2) = 6-pair
// pairwise-disjoint face on the four-array reader-boundary set
// EXHAUSTIVELY.
const _: () =
    assert_char_arrays_disjoint::<2, 2>(&Sexp::COMMENT_DELIMITERS, &Atom::SELF_ESCAPE_TABLE);

/// Compile-time contract verifier — panics at const evaluation time if
/// the sub-slice `full[START..START + M)` does NOT byte-equal the peer
/// sub-array `sub[..]` positionwise (char-by-char).
///
/// Row-dual peer of [`assert_u8_array_slice_equals_u8_array`] on the
/// (element-type) axis: where the `u8` sibling closes the outer-`Sexp`
/// cache-key discriminator sub-carving vocabulary at compile time, this
/// closes the substrate's reader-boundary `[char; N]` scalar-composed
/// vocabulary at compile time. Opens the SUB-SLICE ARRAY-image column
/// on the (char) row of the (element-type × contract-shape) matrix peer
/// to the u8-row sibling's SUB-SLICE ARRAY-image column — the two
/// helpers together lift EVERY positionwise-composition contract
/// `arr[START..START + M) == sub[..]` on scalar-family-wide substrate
/// arrays into a COMPILE-TIME theorem.
///
/// The FULL-ARRAY corner (`M == N`, `START == 0`) collapses to the
/// pointwise identity `arr == [c_0, c_1, …, c_{N-1}]` binding BOTH
/// (a) the per-position ORDER of the outer array's declaration (the
/// CANONICAL variant-declaration order every reader-outer-dispatch
/// consumer depends on) AND (b) each per-role `pub const *_LEAD` /
/// `*_DELIMITER` / `*_ESCAPE_LEAD` / `*_ESCAPE_SOURCE` /
/// `*_ESCAPE_DECODED` alias's canonical `char` value the outer
/// array's slots re-export. Strictly STRONGER on the (contract-
/// strength) axis than the sibling `_pairwise_distinct` witnesses at
/// [`assert_char_array_pairwise_distinct`]: those bind each array's
/// IMAGE SET via INJECTIVITY but are SILENT on which SLOT each char
/// lands at — a regression that swapped [`Sexp::LIST_OPEN`] (`'('`) and
/// [`Sexp::LIST_CLOSE`] (`')'`) (drifting [`Sexp::LIST_DELIMITERS`]
/// from `['(', ')']` to `[')', '(']`) preserves the pairwise-
/// distinctness witness (both chars still distinct) but silently
/// misaligns every consumer indexing `LIST_DELIMITERS[0]` for the
/// reader-open dispatch. THIS helper binds each slot's LITERAL char
/// value at rustc time.
///
/// Consumer sites this helper closes at the FULL-ARRAY corner:
/// * [`Sexp::LIST_DELIMITERS`] `== ['(', ')']` — the reader-outer-
///   dispatch list-delimiter pair whose ordering matches
///   [`Sexp::LIST_OPEN`] / [`Sexp::LIST_CLOSE`] declaration order.
/// * [`Sexp::COMMENT_DELIMITERS`] `== [';', '\n']` — the outer-`Sexp`
///   comment-boundary pair.
/// * [`Atom::SELF_ESCAPE_TABLE`] `== ['"', '\\']` — the pattern-
///   equals-value sub-vocabulary of the Str-escape closed set.
/// * [`Atom::ESCAPE_SOURCES`] `== ['n', 't', 'r', '"', '\\']` — the
///   FIVE non-passthrough SOURCE-column chars of
///   [`Atom::decode_str_escape`] in canonical declaration order.
/// * [`Atom::ESCAPE_DECODED`] `== ['\n', '\t', '\r', '"', '\\']` —
///   the FIVE column-dual DECODED-column chars.
/// * [`Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS`] `== ['(', ')',
///   '\'', '`', ',', '"', ';']` — the SEVEN category-leading chars
///   the reader's outer-dispatch cascade specialises on, spanning
///   THREE type namespaces ([`Sexp`], [`Atom`], [`QuoteForm`]) in
///   canonical outer-dispatch order.
/// * [`QuoteForm::LEADS`] `== ['\'', '`', ',']` — the three quote-
///   family reader-lead-chars in canonical variant-declaration order.
/// * [`crate::error::UnquoteForm::LEADS`] `== [',']` — the shared-
///   lead-char collapse of the two-of-four substitution subset (both
///   `Unquote` and `UnquoteSplice` share the `,` lead byte and
///   disambiguate on the peek-then-consume `@` second char).
///
/// Pre-lift each identity lived ONLY at the array's DECLARATION site
/// (the per-slot initializer's identifier references resolve at
/// substitution to the LITERAL char values); a regression that
/// renamed [`Sexp::LIST_OPEN`] from `'('` to `'['` (a hypothetical
/// Racket-compat port) would compile silently — the array's slot
/// inherits the drifted char, every consumer indexing into
/// `LIST_DELIMITERS[0]` continues to work with the drifted value, and
/// only test-surface references to the LITERAL char `'('` would
/// catch the drift at test runtime rather than at `cargo check` time.
/// Post-lift the per-slot LITERAL char value binds at rustc time via
/// ONE `const _` witness per array; the drift fails at `cargo check`
/// BEFORE any test scheduler runs. Sibling to the pairwise-
/// distinctness witnesses above [`assert_char_array_pairwise_distinct`]
/// — those pin INJECTIVITY on each array; these pin per-slot ORDER
/// against the CANONICAL literal-char listing.
///
/// The three axis-partitioned panic messages (`START-OUT-OF-BOUNDS`,
/// `SLICE-LENGTH-OUT-OF-BOUNDS`, `CHAR-SLICE-EQUALS-ARRAY-VIOLATION`)
/// mirror the u8 sibling's message vocabulary with the `CHAR-` prefix
/// on the CONTENT-drift axis so callers grep either the (u8) row's
/// plain `SLICE-EQUALS-ARRAY-VIOLATION` or the (char) row's
/// `CHAR-SLICE-EQUALS-ARRAY-VIOLATION` axis-prefix by element-type.
///
/// Adding a new family-wide `[char; N]` array to the substrate whose
/// declaration is a positionwise composition against named per-role
/// `pub const` `char` constants: pair the declaration with `const _:
/// () = assert_char_array_slice_equals_char_array::<N, N, 0>(
/// &Self::FOO_ARRAY, &[literal chars; N]);` co-located after the
/// array's declaration and the per-slot ORDER contract binds at
/// compile time. The rustc-forced arity `[char; N]` composes with
/// this const-eval sweep so BOTH cardinality AND per-slot canonical-
/// char-value are compile-time theorems on the SAME array.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — e.g. a REPL / LSP
/// tokenizer that constructs a `[char; N]` at runtime and wants to
/// verify positionwise composition against a peer sub-array before
/// consuming it — and the panic surfaces normally in that path
/// (pinned by
/// `assert_char_array_slice_equals_char_array_panics_at_runtime_on_positionwise_drift`,
/// `assert_char_array_slice_equals_char_array_panics_at_runtime_on_start_out_of_bounds`,
/// `assert_char_array_slice_equals_char_array_panics_at_runtime_on_slice_length_out_of_bounds`,
/// AND
/// `assert_char_array_slice_equals_char_array_panic_message_names_the_helper_and_char_slice_equals_array_violation_axis`).
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the family-wide per-position
///   ORDER contract on the `char`-typed vocabulary becomes a TYPE-
///   LEVEL theorem the substrate carries per array declaration
///   rather than a runtime iterator sweep the developer must
///   remember to write per array.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   positionwise sweep IS the generative shape. Every new closed-
///   set char array declared as a positionwise composition against
///   named-scalar constants adds ONE `const _` line to get the
///   per-slot ORDER theorem rather than re-deriving a runtime index-
///   by-index `assert_eq!` block per array.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs;
///   the per-slot-ORDER proof at declaration site AND the per-role
///   `pub const` alias-chain composition every consumer relies on
///   regenerate through the SAME `const _` witness.
pub const fn assert_char_array_slice_equals_char_array<
    const N: usize,
    const M: usize,
    const START: usize,
>(
    full: &[char; N],
    sub: &[char; M],
) {
    if START > N {
        panic!(
            "assert_char_array_slice_equals_char_array: START-OUT-OF-\
             BOUNDS — the const parameter `START` sits OUTSIDE the \
             outer array's valid position range `[0..N]` (inclusive \
             upper bound: `START == N` combined with `M == 0` is the \
             LEGAL empty-slice-at-right-endpoint corner). Fix at the \
             `const _` witness's turbofish by reconciling `START` \
             against the outer array's declared arity `N`. The \
             START-OUT-OF-BOUNDS gate fires FIRST — a mistyped \
             `START` on the caller side fails HERE before the peer \
             `SLICE-LENGTH-OUT-OF-BOUNDS` gate reads `N - START` \
             (which would underflow `usize` had this gate not caught \
             the slip), so a subtle bounds slip doesn't silently \
             degenerate into a subtraction wrap-around OR a panic \
             deeper in `full[START + i]` bounds-checking."
        );
    }
    if M > N - START {
        panic!(
            "assert_char_array_slice_equals_char_array: SLICE-LENGTH-\
             OUT-OF-BOUNDS — the peer sub-array's arity `M` exceeds \
             the outer array's tail cardinality `N - START`, so the \
             positionwise sweep `full[START + i]` for `i ∈ [0..M)` \
             would overrun the outer array's valid position range \
             `[0..N)` at some `i ∈ [N - START..M)`. Fix at the \
             `const _` witness's turbofish by reconciling `M` against \
             the outer array's tail cardinality `N - START` OR by \
             narrowing `START` to leave a longer tail. The peer \
             `START-OUT-OF-BOUNDS` gate above guarantees `START ≤ N` \
             so `N - START` never underflows `usize` at this gate. \
             The LEGAL exact-fit corner `M == N - START` (the sub-\
             array reaches EXACTLY to the outer array's right \
             endpoint) is accepted; the STRICT `M > N - START` slip \
             is what this gate rejects."
        );
    }
    let mut i = 0;
    while i < M {
        if full[START + i] as u32 != sub[i] as u32 {
            panic!(
                "assert_char_array_slice_equals_char_array: CHAR-\
                 SLICE-EQUALS-ARRAY-VIOLATION — the outer `[char; N]` \
                 array `full` carries a `char` at some position \
                 `START + i` (for `i ∈ [0..M)`) that does NOT byte-\
                 equal the peer `[char; M]` sub-array `sub` at the \
                 offset-matched position `i`. The substrate's SLICE-\
                 EQUALS-ARRAY positionwise-composition contract on the \
                 sub-slice `full[START..START + M) == sub[..]` is \
                 broken; every consumer that reads `full[START..START \
                 + M)` as a positionwise-aligned copy of a peer literal-\
                 char listing (the reader-outer-dispatch pair \
                 `Sexp::LIST_DELIMITERS == [Sexp::LIST_OPEN, \
                 Sexp::LIST_CLOSE]` at `[0..2)`; the comment-boundary \
                 pair `Sexp::COMMENT_DELIMITERS == [Sexp::COMMENT_LEAD, \
                 Sexp::COMMENT_TERM]` at `[0..2)`; the escape-self \
                 pair `Atom::SELF_ESCAPE_TABLE == [Atom::STR_DELIMITER, \
                 Atom::STR_ESCAPE_LEAD]` at `[0..2)`; the escape-\
                 source column `Atom::ESCAPE_SOURCES == [n, t, r, \", \
                 \\]` at `[0..5)`; the escape-decoded column \
                 `Atom::ESCAPE_DECODED == [\\n, \\t, \\r, \", \\]` at \
                 `[0..5)`; the reader-boundary category-leading \
                 seven-char SPAN `Sexp::NON_WHITESPACE_BARE_ATOM_\
                 TERMINATORS` at `[0..7)`; the quote-family lead-char \
                 triple `QuoteForm::LEADS == [QuoteForm::QUOTE_LEAD, \
                 QuoteForm::QUASIQUOTE_LEAD, QuoteForm::UNQUOTE_LEAD]` \
                 at `[0..3)`; the substitution-subset singleton \
                 `UnquoteForm::LEADS == [UnquoteForm::UNQUOTE_LEAD]` \
                 at `[0..1)`; any future family-wide `[char; N]` sub-\
                 slice byte-for-byte equal to a peer literal-char \
                 listing) relies on this invariant. Fix at the ARRAY-\
                 DECLARATION site (the drifted `full[START + i]` slot \
                 inside the slice segment) OR at the peer per-role \
                 `pub const *_LEAD` / `*_DELIMITER` / `*_ESCAPE_LEAD` \
                 / `*_ESCAPE_SOURCE` / `*_ESCAPE_DECODED` alias's \
                 declaration — the choice depends on whether the \
                 drift is an unintended slot reorder in the outer \
                 array's initializer OR in the per-role alias's \
                 canonical `char` value."
            );
        }
        i += 1;
    }
}

// Compile-time FULL-ARRAY per-position ORDER pins — one `const _: () =
// assert_char_array_slice_equals_char_array::<N, N, 0>(&…, &[literal
// chars; N])` per family-wide `[char; N]` scalar-composed substrate
// array on the reader-boundary closed-set outer algebras. Each
// invocation exercises the [`assert_char_array_slice_equals_char_array`]
// helper at its FULL-ARRAY corner (`M == N`, `START == 0`) — the
// SLICE-EQUALS-ARRAY sweep collapses to the ALL-positions-equal-peer-
// array pointwise identity `arr == [c_0, c_1, …, c_{N-1}]`. The peer
// literal-char sub-array on the RHS pins BOTH (a) the per-position
// ORDER of the outer array's declaration (the CANONICAL variant-
// declaration order every reader-outer-dispatch consumer depends on)
// AND (b) each per-role `pub const *_LEAD` / `*_DELIMITER` /
// `*_ESCAPE_LEAD` / `*_ESCAPE_SOURCE` / `*_ESCAPE_DECODED` alias's
// canonical `char` value the outer array's slots re-export. Strictly
// STRONGER on the (contract-strength) axis than the sibling
// `_pairwise_distinct` witnesses at lines 116..=122 above: those bind
// each array's IMAGE SET via INJECTIVITY but are SILENT on which SLOT
// each char lands at — a regression that swapped `Sexp::LIST_OPEN`
// (`'('`) and `Sexp::LIST_CLOSE` (`')'`) (drifting
// `Sexp::LIST_DELIMITERS` from `['(', ')']` to `[')', '(']`) preserves
// the pairwise-distinctness witness (both chars still distinct) but
// silently misaligns every consumer indexing `LIST_DELIMITERS[0]` for
// the reader-open dispatch. Post-lift the ARRAY-LEVEL per-position
// order binds at rustc time via ONE `const _` witness per array; a
// drift at either the per-role `pub const` char OR the array
// declaration's ordering fails at `cargo check` BEFORE any test
// scheduler runs.
//
// Sibling posture to the FOUR-witness EXHAUSTIVE per-position sweep on
// the FOUR sub-carving `[u8; N]` `HASH_DISCRIMINATORS` arrays in the
// (u8) row's FULL-ARRAY per-position ORDER cluster below in this file.
// Those four witnesses close the FOUR sub-carving arrays against their
// LITERAL byte listing at the (u8) row's FULL-ARRAY corner; these
// EIGHT witnesses close the EIGHT reader-boundary scalar-composed
// arrays against their LITERAL char listing at the (char) row's FULL-
// ARRAY corner. Together the twelve witnesses close the (element-
// type × contract-shape) matrix's FULL-ARRAY per-position ORDER
// column across BOTH the (u8) row (outer-`Sexp` cache-key
// discriminator vocabulary) AND the (char) row (reader-boundary char
// vocabulary) EXHAUSTIVELY at rustc time.
//
// The eight pinned arrays appear here in canonical (owning-algebra,
// per-role-alias-count-ascending) order:
// * `Sexp::LIST_DELIMITERS == ['(', ')']` — outer-`Sexp` list pair.
// * `Sexp::COMMENT_DELIMITERS == [';', '\n']` — outer-`Sexp` comment
//   boundary pair.
// * `Atom::SELF_ESCAPE_TABLE == ['"', '\\']` — `Atom` escape-self
//   pair (pattern-equals-value sub-vocabulary of the Str-escape
//   closed set).
// * `Atom::ESCAPE_SOURCES == ['n', 't', 'r', '"', '\\']` — `Atom`
//   escape-source column (non-passthrough SOURCE-column chars).
// * `Atom::ESCAPE_DECODED == ['\n', '\t', '\r', '"', '\\']` —
//   `Atom` escape-decoded column (column-dual DECODED-column chars).
// * `Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS == ['(', ')', '\'',
//   '`', ',', '"', ';']` — outer-`Sexp` reader-boundary category-
//   leading seven-char SPAN across THREE type namespaces ([`Sexp`],
//   [`QuoteForm`], [`Atom`]).
// * `QuoteForm::LEADS == ['\'', '`', ',']` — quote-family reader-
//   lead-char triple.
// * `UnquoteForm::LEADS == [',']` — substitution-subset shared-lead
//   singleton (both `Unquote` and `UnquoteSplice` share the `,`
//   lead byte and disambiguate on the peek-then-consume `@` second
//   char).
const _: () =
    assert_char_array_slice_equals_char_array::<2, 2, 0>(&Sexp::LIST_DELIMITERS, &['(', ')']);
const _: () =
    assert_char_array_slice_equals_char_array::<2, 2, 0>(&Sexp::COMMENT_DELIMITERS, &[';', '\n']);
const _: () =
    assert_char_array_slice_equals_char_array::<2, 2, 0>(&Atom::SELF_ESCAPE_TABLE, &['"', '\\']);
const _: () = assert_char_array_slice_equals_char_array::<5, 5, 0>(
    &Atom::ESCAPE_SOURCES,
    &['n', 't', 'r', '"', '\\'],
);
const _: () = assert_char_array_slice_equals_char_array::<5, 5, 0>(
    &Atom::ESCAPE_DECODED,
    &['\n', '\t', '\r', '"', '\\'],
);
const _: () = assert_char_array_slice_equals_char_array::<7, 7, 0>(
    &Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS,
    &['(', ')', '\'', '`', ',', '"', ';'],
);
const _: () =
    assert_char_array_slice_equals_char_array::<3, 3, 0>(&QuoteForm::LEADS, &['\'', '`', ',']);
const _: () =
    assert_char_array_slice_equals_char_array::<1, 1, 0>(&crate::error::UnquoteForm::LEADS, &[',']);

// Compile-time SUB-CARVING per-position ARRAY-LEVEL POSITIONAL-
// COMPOSITION witnesses on `Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS`
// (`[char; 7]`) — the outer-`Sexp` reader-boundary category-leading
// seven-char SPAN whose declaration order composes across THREE type
// namespaces (`Sexp`, `QuoteForm`, `Atom`) as the segmented
// concatenation
//
//     NON_WHITESPACE_BARE_ATOM_TERMINATORS
//         == Sexp::LIST_DELIMITERS       // slots [0..2)
//         ++ QuoteForm::LEADS            // slots [2..5)
//         ++ [Atom::STR_DELIMITER]       // slot   [5..6)
//         ++ [Sexp::COMMENT_LEAD]        // slot   [6..7)
//
// Each of the FOUR right-hand-side segments names an INDEPENDENT
// substrate primitive on ONE of the three sub-algebras — the OUTER
// terminator SPAN is the composition surface where the FOUR sub-
// vocabularies land at their canonical reader-outer-dispatch slots. The
// pre-existing FULL-ARRAY LITERAL-listing witness IMMEDIATELY ABOVE
// (`assert_char_array_slice_equals_char_array::<7, 7, 0>(&…, &['(', ')',
// '\'', '`', ',', '"', ';'])`) binds the SPAN against a HARDCODED
// `[char; 7]` peer literal — it catches drifts of the PER-ROLE `pub
// const` chars each sub-carving array's slot re-exports through the
// underlying `Sexp::LIST_OPEN` / `Sexp::LIST_CLOSE` / `QuoteForm::
// QUOTE_LEAD` / … / `Sexp::COMMENT_LEAD` primitives, but is SILENT on
// the ARRAY-LEVEL structural composition axis — a regression that
// reorders `Sexp::LIST_DELIMITERS` from `[LIST_OPEN, LIST_CLOSE]` to
// `[LIST_CLOSE, LIST_OPEN]` (or `QuoteForm::LEADS` from `[QUOTE_LEAD,
// QUASIQUOTE_LEAD, UNQUOTE_LEAD]` to any other permutation of the same
// three chars) while leaving `NON_WHITESPACE_BARE_ATOM_TERMINATORS` in
// its canonical initializer form silently misaligns every consumer that
// treats the composite's HEAD-2-slice as positionally-interchangeable
// with `Sexp::LIST_DELIMITERS` (or the MIDDLE-3-slice with
// `QuoteForm::LEADS`) — the OUTER LITERAL witness accepts both
// sub-carving reorders because the LITERAL peer array's slot-0 (`'('`)
// and slot-1 (`')'`) still match `NON_WHITESPACE_BARE_ATOM_TERMINATORS`
// even though the sub-carving's declaration slot-0 and slot-1 drifted.
// The pre-existing SET-level SUBSET witnesses at lines 369..=380 above
// (`assert_char_array_within_char_finite_set::<{2,3}, 7>(&{LIST_
// DELIMITERS, QuoteForm::LEADS}, &NON_WHITESPACE_BARE_ATOM_TERMINATORS)`)
// bind the sub-carvings' distinct-value SET is CONTAINED in the
// composite's distinct-value SET but are silent on positional alignment
// — the SAME sub-carving reorders survive those witnesses because
// distinct-value SET membership is order-invariant.
//
// These FOUR new `const _` witnesses close the missing corner: each
// binds a SUB-CARVING array positionwise-equal to its canonical SLOT
// SEGMENT of the composite terminator SPAN via
// [`assert_char_array_slice_equals_char_array`] at the SUB-SLICE ARRAY-
// image corner (`START ∈ {0, 2, 5, 6}`, `M ∈ {2, 3, 1, 1}`,
// `M < N == 7`). Post-lift a drift at ANY of the sub-carvings'
// declaration ordering (or at the composite's slot ordering) fails
// AT rustc time BEFORE the pre-existing FULL-ARRAY LITERAL witness re-
// verifies the composite's literal identity — the two witness families
// bind the composite through DISTINCT drift-detection axes (LITERAL
// against inline chars, POSITIONAL against sub-carving arrays) that
// TOGETHER catch every ARRAY-LEVEL misalignment the pre-lift
// (INJECTIVITY + SUBSET-EMBEDDING) 2-corner face silently accepted.
//
// Sibling posture to the FOUR-witness EXHAUSTIVE per-position sub-
// carving composition sweep on the OUTER `SexpShape::HASH_DISCRIMINATORS`
// container (the trio of `assert_u8_array_slice_equals_u8_array::<12,
// {1, 4}, {0, 7, 8}>` witnesses + the `assert_u8_array_slice_is_scalar_
// replica::<12, 1, 7>` witness below in this file). Those FOUR
// witnesses pin the (u8) row's twelve-slot outer container against its
// FOUR sub-carvings at rustc time; THESE FOUR witnesses pin the (char)
// row's seven-slot outer terminator SPAN against its FOUR sub-carvings
// at rustc time. Together the eight witnesses close the (element-type
// × contract-shape) matrix's SUB-CARVING per-position POSITIONAL-
// COMPOSITION corner across BOTH the (u8) row (outer-`Sexp` cache-key
// discriminator hierarchy) AND the (char) row (reader-outer-dispatch
// terminator SPAN) EXHAUSTIVELY at the FOUR-sub-carving-per-container
// depth.
//
// A hypothetical seventh reader-outer-dispatch category (e.g. a
// `#|…|#` block-comment lead byte pinning a fresh `Sexp::BLOCK_COMMENT_
// LEAD` primitive) would extend `NON_WHITESPACE_BARE_ATOM_TERMINATORS`
// to `[char; 8]` AND require a FIFTH witness below binding
// `NON_WHITESPACE_BARE_ATOM_TERMINATORS[7..8) == [Sexp::BLOCK_COMMENT_
// LEAD]` (or, if the new lead byte joins an EXISTING sub-carving like
// `Sexp::COMMENT_LEAD`'s comment axis, a widened `Sexp::COMMENT_LEADS`
// array replaces the singleton at slot `[6..7)` and its widened arity
// propagates through the widened witness's const-generic turbofish).
// Rustc's forced-arity check on `[char; N]` fails compilation if the
// composite's arity grows without the corresponding sub-carving
// widening (or vice versa).
const _: () = assert_char_array_slice_equals_char_array::<7, 2, 0>(
    &Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS,
    &Sexp::LIST_DELIMITERS,
);
const _: () = assert_char_array_slice_equals_char_array::<7, 3, 2>(
    &Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS,
    &QuoteForm::LEADS,
);
const _: () = assert_char_array_slice_equals_char_array::<7, 1, 5>(
    &Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS,
    &[Atom::STR_DELIMITER],
);
const _: () = assert_char_array_slice_equals_char_array::<7, 1, 6>(
    &Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS,
    &[Sexp::COMMENT_LEAD],
);

/// Compile-time contract verifier — panics at const evaluation time if
/// any two entries of `arr` alias byte-for-byte through
/// [`str::as_bytes`].
///
/// Column-dual peer to [`assert_char_array_pairwise_distinct`] on the
/// (element-type) axis: where the `char` sibling closes the reader-
///
/// Column-dual peer to [`assert_char_array_pairwise_distinct`] on the
/// (element-type) axis: where the `char` sibling closes the reader-
/// boundary `[char; N]` vocabulary at compile time, this closes the
/// substrate's family-wide `[&'static str; N]` vocabulary at compile
/// time. The two helpers together lift EVERY `pub const` scalar-
/// family-wide array declared on the substrate's closed-set outer
/// algebras (`Sexp` / `Atom` / `AtomKind` / `QuoteForm`) into a
/// COMPILE-TIME pairwise-distinctness theorem — a regression that
/// silently collides two entries fails the build at `cargo check`
/// time, one invocation stage earlier than the test-run pin.
///
/// The invariant is load-bearing for every consumer that pattern-
/// matches the array's entries as DISJOINT arms —
/// [`Atom::bool_literal`]'s two-arm projection through
/// [`Atom::BOOL_LITERALS`] (a duplicate here would silently shadow
/// the second arm's `#f` spelling at the same-index projection);
/// [`AtomKind::label`]'s six-arm projection through
/// [`AtomKind::LABELS`] (a duplicate here would collapse two
/// distinct atomic-payload variants onto the same diagnostic
/// label, breaking every downstream label-driven partition on
/// the closed-set AtomKind algebra); [`QuoteForm::prefix`]'s
/// four-arm projection over [`QuoteForm::PREFIXES`] (a duplicate
/// here would silently collapse two distinct quote-family
/// variants onto the same reader-prefix `&'static str`);
/// [`QuoteForm::iac_forge_tag`]'s four-arm projection through
/// [`QuoteForm::IAC_FORGE_TAGS`] (a duplicate here would silently
/// collapse two distinct quote-family variants onto the same
/// canonical-form tag, breaking the iac-forge interop round-trip
/// through [`QuoteForm::from_iac_forge_tag`]); AND
/// [`QuoteForm::label`]'s four-arm projection through
/// [`QuoteForm::LABELS`] (a duplicate here would collapse two
/// distinct quote-family variants onto the same diagnostic
/// label). Every future family-wide `[&'static str; N]` on the
/// substrate that participates in a `match`-arm partition or a
/// same-index alias-chain benefits from the SAME compile-time
/// guarantee via one `const _` line.
///
/// Pre-lift each array carried its pairwise-distinctness contract
/// EITHER at a runtime test (`atom_bool_literals_pairwise_distinct`,
/// `atom_kind_labels_pairwise_distinct`, `quote_form_prefixes_
/// pairwise_distinct`, `quote_form_iac_forge_tags_pairwise_distinct`,
/// `quote_form_labels_pairwise_distinct`) OR implicitly through the
/// same-index alias-chain composition law's runtime pin; post-lift
/// the pairwise-distinctness contract binds at `cargo check` time,
/// one invocation stage earlier, catching regressions on `cargo
/// build` / `cargo clippy` runs that skip the test suite.
///
/// Adding a new family-wide `[&'static str; N]` array to the
/// substrate: pair the declaration with `const _: () = assert_str_
/// array_pairwise_distinct(&Self::FOO_ARRAY);` co-located immediately
/// after the array's declaration and the distinctness contract is
/// enforced at compile time. The rustc-forced arity `[&'static str;
/// N]` composes with this const-eval sweep so BOTH cardinality AND
/// injectivity are compile-time theorems on the SAME array.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — e.g. a REPL / LSP
/// autocomplete surface that constructs a `[&'static str; N]` at
/// runtime from a user-supplied vocabulary AND wants to verify
/// pairwise distinctness before consuming it — and the panic
/// surfaces normally in that path (pinned by
/// `assert_str_array_pairwise_distinct_panics_at_runtime_on_binary_
/// collision`).
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the family-wide
///   distinctness contract on the `&'static str`-typed vocabulary
///   becomes a TYPE-LEVEL theorem the substrate carries per array
///   declaration rather than a runtime test the developer must
///   remember to write per array.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   sweep IS the generative shape. Every new closed-set string
///   array adds ONE `const _` line to get the distinctness theorem
///   rather than re-deriving a per-array runtime iterator sweep.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs;
///   the distinctness proof at declaration site AND the same-index
///   alias-chain composition the consumer relies on regenerate
///   through the SAME `const _` witness.
pub const fn assert_str_array_pairwise_distinct<const N: usize>(arr: &[&'static str; N]) {
    let mut i = 0;
    while i < N {
        let mut j = i + 1;
        while j < N {
            if str_bytes_equal(arr[i], arr[j]) {
                panic!(
                    "assert_str_array_pairwise_distinct: family-wide \
                     &'static str array carries a duplicate entry \
                     across two positions — the substrate's pairwise-\
                     distinctness contract on the array is broken; \
                     every consumer that pattern-matches the array's \
                     entries as DISJOINT arms (bool-literal dispatch, \
                     atomic-kind label decode, quote-family prefix \
                     decode, iac-forge tag decode, quote-family label \
                     projection) relies on this invariant"
                );
            }
            j += 1;
        }
        i += 1;
    }
}

/// Const-fn byte-equality helper for `assert_str_array_pairwise_
/// distinct` — compares two `&'static str`s byte-for-byte through
/// their [`str::as_bytes`] projections. Lifted as a co-located
/// module-private helper rather than an inline sweep so the outer
/// helper's triangular `(i, j)` pair-walk mirrors the shape of
/// [`assert_char_array_pairwise_distinct`] at the outer method
/// axis without an inline byte-loop obscuring the `(i, j)` sweep.
///
/// The equality relation this helper computes is EXACTLY
/// [`str::eq`] (i.e. byte-for-byte length + content equality on
/// the underlying UTF-8 bytes), just re-derived in a const-eval
/// friendly shape since `str::eq` / `<[u8]>::eq` are not (yet)
/// callable from `const fn` context on the substrate's toolchain.
/// A future toolchain that stabilises `const fn str::eq` collapses
/// this helper to a one-line `str::eq(a, b)` delegation.
const fn str_bytes_equal(a: &str, b: &str) -> bool {
    let a = a.as_bytes();
    let b = b.as_bytes();
    if a.len() != b.len() {
        return false;
    }
    let mut k = 0;
    while k < a.len() {
        if a[k] != b[k] {
            return false;
        }
        k += 1;
    }
    true
}

// Compile-time pairwise-distinctness witnesses — one `const _: () =
// assert_str_array_pairwise_distinct(&…)` per family-wide `[&'static
// str; N]` array on the substrate's closed-set outer algebras. Each
// invocation is const-evaluated at `cargo check` time; a regression
// that silently collides two entries fails the build rather than the
// test suite. Sibling to the runtime `_pairwise_distinct` tests at
// `ast.rs`'s tests module — the two enforce the same theorem at TWO
// stages of the toolchain, so a build that skips tests still catches
// the regression here, and a build that runs tests catches it a
// second time as a safety net if the const-eval sweep is ever
// silently dropped. Peer to the seven `assert_char_array_pairwise_
// distinct` witnesses above on the (element-type) axis: `char` covers
// the reader-boundary vocabulary; `&'static str` covers the closed-
// set outer-algebras' family-wide label / prefix / tag / literal
// vocabularies.
const _: () = assert_str_array_pairwise_distinct(&Atom::BOOL_LITERALS);
const _: () = assert_str_array_pairwise_distinct(&AtomKind::LABELS);
const _: () = assert_str_array_pairwise_distinct(&QuoteForm::PREFIXES);
const _: () = assert_str_array_pairwise_distinct(&QuoteForm::IAC_FORGE_TAGS);
const _: () = assert_str_array_pairwise_distinct(&QuoteForm::LABELS);

// Compile-time FULL-ARRAY per-position ORDER pins — one `const _: () =
// assert_str_array_slice_equals_str_array::<N, N, 0>(&…, &[literal strs;
// N])` per family-wide `[&'static str; N]` scalar-composed substrate
// array on the closed-set outer-algebras' label / prefix / tag / literal
// vocabularies. Each invocation exercises the
// [`assert_str_array_slice_equals_str_array`] helper at its FULL-ARRAY
// corner (`M == N`, `START == 0`) — the SLICE-EQUALS-ARRAY sweep
// collapses to the ALL-positions-equal-peer-array pointwise identity
// `arr == [s_0, s_1, …, s_{N-1}]`. The peer literal-str sub-array on
// the RHS pins BOTH (a) the per-position ORDER of the outer array's
// declaration (the CANONICAL variant-declaration order every
// closed-set outer-algebra consumer depends on) AND (b) each per-role
// `pub const *_LABEL` / `*_PREFIX` / `*_TAG` / `TRUE_LITERAL` /
// `FALSE_LITERAL` alias's canonical `&'static str` value the outer
// array's slots re-export. Strictly STRONGER on the (contract-strength)
// axis than the sibling `_pairwise_distinct` witnesses at lines
// 1173..=1177 above: those bind each array's IMAGE SET via INJECTIVITY
// but are SILENT on which SLOT each str lands at — a regression that
// swapped `Atom::TRUE_LITERAL` (`"#t"`) and `Atom::FALSE_LITERAL`
// (`"#f"`) (drifting `Atom::BOOL_LITERALS` from `["#t", "#f"]` to
// `["#f", "#t"]`) preserves the pairwise-distinctness witness (both
// strs still distinct) but silently misaligns every consumer indexing
// `BOOL_LITERALS[0]` for the canonical `true`-lexeme dispatch. A
// silent value-drift of a per-role scalar (e.g. an ELisp-compat
// rename of `AtomKind::SYMBOL_LABEL` from `"symbol"` to `"sym"`, a
// Racket-compat rename of `QuoteForm::QUASIQUOTE_LABEL`) that flows
// through the composed array without updating the outer array's
// literal image ALSO fails HERE where the pairwise-distinctness
// witness stays silent. Post-lift the ARRAY-LEVEL per-position order
// binds at rustc time via ONE `const _` witness per array; a drift
// at either the per-role `pub const *_LABEL` / `*_PREFIX` / `*_TAG`
// str OR the array declaration's ordering fails at `cargo check`
// BEFORE any test scheduler runs.
//
// Sibling posture to the EIGHT-witness (char)-row FULL-ARRAY per-
// position ORDER cluster at lines 893..=914 above (the eight
// `assert_char_array_slice_equals_char_array::<N, N, 0>(&…, &[literal
// chars; N])` witnesses on the substrate's `[char; N]` reader-boundary
// vocabulary) and the FOUR-witness (u8)-row FULL-ARRAY per-position
// ORDER cluster below in this file (four
// `assert_u8_array_slice_equals_u8_array::<N, N, 0>(&…, &[literal
// bytes; N])` witnesses on the sub-carving `[u8; N]`
// `HASH_DISCRIMINATORS` arrays). Together the eight (char)-row + four
// (u8)-row + these five (str)-row witnesses close the (element-type
// × contract-shape) matrix's FULL-ARRAY per-position ORDER column
// across ALL THREE scalar element-type rows (char, u8, &'static str)
// EXHAUSTIVELY at rustc time.
//
// The five pinned arrays appear here in canonical (owning-algebra,
// per-role-alias-count-ascending) order:
// * `Atom::BOOL_LITERALS == ["#t", "#f"]` — Scheme-canonical bool-
//   lexeme spellings on the `Atom` algebra (two per-role literals).
// * `AtomKind::LABELS == ["symbol", "keyword", "string", "int",
//   "float", "bool"]` — atomic-payload diagnostic labels on the
//   `AtomKind` subset algebra (six per-role labels).
// * `QuoteForm::PREFIXES == ["'", "`", ",", ",@"]` — quote-family
//   reader-punctuation prefix bytes on the `QuoteForm` algebra (four
//   per-role prefixes; the fourth `",@"` is the ONLY two-char prefix
//   on the closed set — pinned separately by
//   `quote_form_unquote_splice_prefix_constant_composes_from_unquote_lead_and_splice_discriminator`).
// * `QuoteForm::LABELS == ["quote", "quasiquote", "unquote",
//   "unquote-splice"]` — diagnostic labels on the `QuoteForm` algebra
//   (four per-role labels; the fourth `"unquote-splice"` is the
//   substrate's SHORTER diagnostic idiom for `LispError::TypeMismatch.got`
//   surfaces — INTENTIONALLY DISTINCT from the iac-forge tag's
//   Common-Lisp-canonical `"unquote-splicing"` spelling).
// * `QuoteForm::IAC_FORGE_TAGS == ["quote", "quasiquote", "unquote",
//   "unquote-splicing"]` — cross-crate canonical-form tags on the
//   `QuoteForm` algebra (four per-role tags; the fourth
//   `"unquote-splicing"` is Common-Lisp-canonical and distinct from
//   `QuoteForm::LABELS[3]`'s shorter `"unquote-splice"` spelling —
//   pinned by
//   `quote_form_iac_forge_tag_and_label_disagree_only_on_unquote_splice_arm`).
const _: () =
    assert_str_array_slice_equals_str_array::<2, 2, 0>(&Atom::BOOL_LITERALS, &["#t", "#f"]);
const _: () = assert_str_array_slice_equals_str_array::<6, 6, 0>(
    &AtomKind::LABELS,
    &["symbol", "keyword", "string", "int", "float", "bool"],
);
const _: () = assert_str_array_slice_equals_str_array::<4, 4, 0>(
    &QuoteForm::PREFIXES,
    &["'", "`", ",", ",@"],
);
const _: () = assert_str_array_slice_equals_str_array::<4, 4, 0>(
    &QuoteForm::LABELS,
    &["quote", "quasiquote", "unquote", "unquote-splice"],
);
const _: () = assert_str_array_slice_equals_str_array::<4, 4, 0>(
    &QuoteForm::IAC_FORGE_TAGS,
    &["quote", "quasiquote", "unquote", "unquote-splicing"],
);

/// Compile-time contract verifier — panics at const evaluation time if
/// any entry of `arr` has zero length under [`str::len`] (equivalently
/// `str::is_empty`).
///
/// Contract-orthogonal peer to [`assert_str_array_pairwise_distinct`]
/// on the (contract-shape) column of the (`&'static str`) row of the
/// (element-type × contract-shape) matrix: where the pairwise-
/// distinctness sibling binds INTRA-array `∀ i ≠ j : arr[i] ≠ arr[j]`
/// (INJECTIVITY on the multiset of entries), this NONEMPTY-CARDINALITY-
/// LOWER-BOUND sibling binds the strictly-weaker per-entry cardinality
/// gate `∀ i : arr[i].len() > 0` (NO ENTRY is the zero-length byte
/// sequence). The two contracts compose orthogonally: an array that
/// carries `["", ""]` fails the pairwise-distinctness contract at the
/// zero-length-pair corner (pinned by
/// `assert_str_array_pairwise_distinct_rejects_length_zero_collision`),
/// but an array that carries `["", "a"]` passes pairwise-distinctness
/// while failing NONEMPTY — so the NONEMPTY sibling closes the
/// remaining `""`-carrying corner that INJECTIVITY alone cannot pin.
/// The inner test is a direct [`str::is_empty`] delegation — const-
/// stable since Rust 1.39 and const-callable on the substrate's
/// toolchain — so no `str_bytes_equal`-shaped auxiliary helper is
/// needed for this contract (the peer `_pairwise_distinct` sibling
/// uses `str_bytes_equal` because it must compare TWO strings byte-
/// for-byte while `const fn str::eq` remains unstable; this sibling
/// only tests ONE string's length so it delegates directly).
///
/// The invariant is load-bearing for every consumer that spells a
/// closed-set variant through its `&'static str` label — every
/// [`AtomKind::label`] / [`QuoteForm::label`] / `parse_label` /
/// `find_by_label` composition on the ClosedSet trait's family-wide
/// label vocabularies (`Atom::BOOL_LITERALS` on the bool-literal
/// dispatch; `AtomKind::LABELS` on the atomic-payload kind decode;
/// `QuoteForm::LABELS` on the quote-family diagnostic vocabulary;
/// `QuoteForm::PREFIXES` on the reader-boundary prefix vocabulary;
/// `QuoteForm::IAC_FORGE_TAGS` on the canonical iac-forge tag
/// vocabulary) treats each entry as a NONEMPTY identifier and would
/// silently mis-behave on a `""` entry: `parse_label("")` would decode
/// the empty string to that variant (silently making empty user input a
/// valid variant spelling); `find_by_label("")` would return `Some(v)`
/// rather than `None`; every string-search consumer that scans for a
/// prefix or contains a label as a substring would spuriously match on
/// every input (since `""` is a prefix and a substring of every
/// string). Post-lift a regression that silently re-inlined one label
/// constant to `""` (e.g. `AtomKind::SYMBOL_LABEL = "";`) fails at
/// `cargo check` BEFORE any test scheduler runs.
///
/// Adding a new family-wide `[&'static str; N]` label / prefix / tag /
/// literal vocabulary to the substrate: pair the declaration with
/// `const _: () = assert_str_array_all_nonempty(&Self::FOO_ARRAY);`
/// co-located after the array's declaration and the NONEMPTY-CARDINALITY-
/// LOWER-BOUND contract binds at compile time. The rustc-forced arity
/// `[&'static str; N]` composes with this const-eval sweep so BOTH
/// cardinality AND per-entry nonempty are compile-time theorems on the
/// SAME array.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — pinned by
/// `assert_str_array_all_nonempty_panics_at_runtime_on_head_empty` /
/// `_interior_empty` / `_tail_empty` and
/// `assert_str_array_all_nonempty_panic_message_names_the_helper`. The
/// panic site carries the `"STR-EMPTY-ENTRY"` axis-provenance string
/// chosen DISTINCT from every sibling helper's axis vocabulary
/// (`"duplicate"` on the pairwise-distinct sibling; `"STR-DISJOINTNESS-
/// VIOLATION"` on the arrays-disjoint sibling; `"STR-SUBSET-VIOLATION"`
/// on the within-finite-set sibling) so a diagnostic that names the
/// failed axis routes UNAMBIGUOUSLY to THIS specific NONEMPTY helper.
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the family-wide nonempty-
///   cardinality-lower-bound contract on the `&'static str` label
///   vocabulary becomes a TYPE-LEVEL theorem the substrate carries per
///   array declaration rather than a runtime test the developer must
///   remember to write per label constant.
/// - THEORY.md §II.1 invariant 1 — typed entry; a closed-set variant's
///   label projection is the entry-point discriminator into the typed
///   algebra, and a `""` entry would silently break the discriminator
///   at the boundary between untyped `&str` input and typed enum
///   variant.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   sweep IS the generative shape. Every new closed-set label array
///   adds ONE `const _` line to get the NONEMPTY theorem rather than
///   re-deriving a per-array runtime iterator sweep at each call site.
pub const fn assert_str_array_all_nonempty<const N: usize>(arr: &[&'static str; N]) {
    let mut i = 0;
    while i < N {
        if arr[i].is_empty() {
            panic!(
                "assert_str_array_all_nonempty: STR-EMPTY-ENTRY — the \
                 family-wide &'static str array carries a zero-length \
                 entry at some position — the substrate's NONEMPTY-\
                 CARDINALITY-LOWER-BOUND contract on the array is \
                 broken; every consumer that spells a closed-set variant \
                 through its `&'static str` label (AtomKind / QuoteForm \
                 / UnquoteForm / StructuralKind / SexpShape label \
                 projections; the reader-boundary prefix / tag \
                 vocabularies; the bool-literal dispatch) treats each \
                 entry as a NONEMPTY identifier — `parse_label(\"\")` \
                 would silently decode the empty string to the offending \
                 variant, `find_by_label(\"\")` would return `Some(v)` \
                 rather than `None`, every substring / prefix scan would \
                 spuriously match on every input. Fix at the ARRAY-\
                 DECLARATION site by removing the `\"\"` entry OR by \
                 giving it a nonempty canonical spelling"
            );
        }
        i += 1;
    }
}

// Compile-time NONEMPTY-CARDINALITY-LOWER-BOUND witnesses — one
// `const _: () = assert_str_array_all_nonempty(&…)` per family-wide
// `[&'static str; N]` array on the substrate's closed-set outer
// algebras. Each invocation is const-evaluated at `cargo check` time; a
// regression that silently re-inlined one label constant to `""` fails
// the build rather than deferring to a per-consumer misbehavior at
// runtime. Sibling to the pairwise-distinctness witnesses above — those
// pin INJECTIVITY on each array, these pin the strictly-weaker per-
// entry cardinality gate on the SAME arrays. The two contracts compose
// orthogonally on every closed-set outer algebra's label vocabulary.
// The five arrays covered here mirror the five arrays already pinned
// by the `_pairwise_distinct` witnesses above (`Atom::BOOL_LITERALS`,
// `AtomKind::LABELS`, `QuoteForm::PREFIXES`, `QuoteForm::IAC_FORGE_TAGS`,
// `QuoteForm::LABELS`) — the (array × contract-shape) coverage matrix
// on the (`&'static str`) row of this file now holds at every
// (INJECTIVITY, NONEMPTY) corner for the five outer-algebra arrays
// declared here. Analogous witnesses on the (`&'static str`) arrays
// declared under `crate::error` (`CompilerSpecIoStage::LABELS`,
// `MacroDefHead::KEYWORDS`, `MacroParams::LAMBDA_LIST_KEYWORDS`,
// `UnquoteForm::MARKERS` / `IAC_FORGE_TAGS` / `LABELS`,
// `KwargPathKind::LABELS`, `ExpectedKwargShape::LABELS`,
// `SexpShape::LABELS`, `StructuralKind::LABELS`) land co-located with
// the pre-existing `_pairwise_distinct` witnesses at that file's
// module-level prelude.
const _: () = assert_str_array_all_nonempty(&Atom::BOOL_LITERALS);
const _: () = assert_str_array_all_nonempty(&AtomKind::LABELS);
const _: () = assert_str_array_all_nonempty(&QuoteForm::PREFIXES);
const _: () = assert_str_array_all_nonempty(&QuoteForm::IAC_FORGE_TAGS);
const _: () = assert_str_array_all_nonempty(&QuoteForm::LABELS);

/// Compile-time contract verifier — panics at const evaluation time if
/// any entry of `arr` carries a byte outside the seven-bit ASCII range
/// (`>= 0x80`, the first byte of any non-ASCII UTF-8 sequence).
///
/// Per-entry peer to [`assert_str_array_all_nonempty`] on the (per-
/// entry × contract-shape) axis of the (`&'static str`) row: where the
/// NONEMPTY sibling pins the length-lower-bound gate (`∀ i :
/// arr[i].len() > 0`), this ASCII sibling pins the byte-range
/// containment gate (`∀ i, ∀ b ∈ arr[i].as_bytes() : b <= 0x7F`). The
/// two contracts compose orthogonally — an array carrying `["café"]`
/// passes NONEMPTY while failing ASCII; an array carrying `["", "a"]`
/// passes ASCII while failing NONEMPTY. Together with the INJECTIVITY
/// sibling ([`assert_str_array_pairwise_distinct`]) the substrate's
/// (per-entry × contract-shape) coverage matrix on the (`&'static
/// str`) row closes at THREE corners: {NONEMPTY, ASCII, INJECTIVITY}
/// on the SAME five outer-algebra arrays declared here.
///
/// The invariant is load-bearing for every consumer that ships an
/// array entry through a downstream surface whose canonical form is
/// seven-bit-clean — Kubernetes annotation keys + label values (RFC
/// 1123 subset of ASCII); YAML flow-scalar map keys the reader-boundary
/// prefix vocabulary threads through the four-Lisp projection; BLAKE3
/// hash inputs on the three-pillar attestation chain (identical byte
/// sequences hash identically regardless of encoding, but authoring a
/// non-ASCII label silently invites U+FEFF BOMs and Unicode-normalization
/// drift on the wire); Rust `matches!(s, "quote" | …)` byte-pattern
/// arms the compiler lowers to `[u8]` comparison. Post-lift a
/// regression that silently re-inlined one label constant to a byte-
/// equivalent non-ASCII spelling (e.g. `AtomKind::SYMBOL_LABEL =
/// "sýmbol";`, a lookalike that would parse as a Rust `&'static str`
/// but ship non-ASCII bytes at every consumer) fails at `cargo check`
/// BEFORE any test scheduler runs.
///
/// Adding a new family-wide `[&'static str; N]` label / prefix / tag /
/// literal vocabulary whose canonical spelling is seven-bit-clean:
/// pair the declaration with `const _: () =
/// assert_str_array_all_ascii(&Self::FOO_ARRAY);` co-located after
/// the array's declaration and the ASCII-BYTE-RANGE contract binds at
/// compile time. The rustc-forced arity `[&'static str; N]` composes
/// with this const-eval sweep so BOTH cardinality AND per-entry ASCII
/// are compile-time theorems on the SAME array declaration.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — pinned by
/// `assert_str_array_all_ascii_panics_at_runtime_on_head_non_ascii` /
/// `_interior_non_ascii` / `_tail_non_ascii` and
/// `assert_str_array_all_ascii_panic_message_names_the_helper_and_axis`.
/// The panic site carries the `"STR-NON-ASCII-ENTRY"` axis-provenance
/// string chosen DISTINCT from every sibling helper's axis vocabulary
/// (`"duplicate"` on the pairwise-distinct sibling; `"STR-EMPTY-
/// ENTRY"` on the per-entry NONEMPTY sibling; `"STR-DISJOINTNESS-
/// VIOLATION"` on the arrays-disjoint sibling; `"STR-SUBSET-
/// VIOLATION"` on the within-finite-set sibling) so a diagnostic that
/// names the failed axis routes UNAMBIGUOUSLY to THIS specific ASCII
/// helper.
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the family-wide per-entry
///   ASCII-byte-range contract on the substrate's `&'static str`
///   label vocabulary becomes a TYPE-LEVEL theorem the substrate
///   carries per array declaration rather than a runtime test the
///   developer must remember to write per label constant.
/// - THEORY.md §II.1 invariant 1 — typed entry; a closed-set variant's
///   label projection is the entry-point discriminator into the typed
///   algebra, and a non-ASCII byte in that projection silently
///   escapes the seven-bit-clean assumption every downstream wire
///   surface encodes into its own byte-level parser.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   byte-range sweep IS the generative shape. Every new closed-set
///   label array adds ONE `const _` line to get the ASCII theorem
///   rather than re-deriving a per-array runtime iterator sweep at
///   each call site.
pub const fn assert_str_array_all_ascii<const N: usize>(arr: &[&'static str; N]) {
    let mut i = 0;
    while i < N {
        let bytes = arr[i].as_bytes();
        let mut j = 0;
        while j < bytes.len() {
            if bytes[j] > 0x7F {
                panic!(
                    "assert_str_array_all_ascii: STR-NON-ASCII-ENTRY — \
                     the family-wide &'static str array carries an \
                     entry with a byte outside the seven-bit ASCII \
                     range (>= 0x80) at some position — the \
                     substrate's ASCII-BYTE-RANGE contract on the \
                     array is broken; 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 on \
                     the three-pillar attestation chain; Rust \
                     `matches!(s, ...)` byte-pattern arms) treats \
                     each entry as ASCII — a non-ASCII byte silently \
                     invites Unicode-normalization drift on the wire, \
                     BOM injection, and lookalike-label collisions \
                     that byte-equality parsing cannot detect. Fix at \
                     the ARRAY-DECLARATION site by re-inlining the \
                     offending label constant to its seven-bit-clean \
                     canonical spelling"
                );
            }
            j += 1;
        }
        i += 1;
    }
}

// Compile-time ASCII-BYTE-RANGE witnesses — one `const _: () =
// assert_str_array_all_ascii(&…)` per family-wide `[&'static str; N]`
// array on the substrate's closed-set outer algebras. Each invocation
// is const-evaluated at `cargo check` time; a regression that
// silently re-inlined one label constant to a lookalike non-ASCII
// spelling fails the build rather than deferring to a per-consumer
// byte-parse misbehavior at runtime. Sibling to the NONEMPTY witnesses
// above — those pin the per-entry length-lower-bound gate on each
// array, these pin the strictly-orthogonal per-entry byte-range gate
// on the SAME arrays. The two contracts compose orthogonally on every
// closed-set outer algebra's label vocabulary. The five arrays covered
// here mirror the five arrays already pinned by the `_pairwise_distinct`
// AND `_all_nonempty` witnesses above — the (per-entry × contract-shape)
// coverage matrix on the (`&'static str`) row of this file now holds
// at THREE corners {NONEMPTY, ASCII, INJECTIVITY} for the five outer-
// algebra arrays declared here. Analogous witnesses on the (`&'static
// str`) arrays declared under `crate::error` land co-located with the
// pre-existing `_pairwise_distinct` + `_all_nonempty` witnesses at
// that file's module-level prelude.
const _: () = assert_str_array_all_ascii(&Atom::BOOL_LITERALS);
const _: () = assert_str_array_all_ascii(&AtomKind::LABELS);
const _: () = assert_str_array_all_ascii(&QuoteForm::PREFIXES);
const _: () = assert_str_array_all_ascii(&QuoteForm::IAC_FORGE_TAGS);
const _: () = assert_str_array_all_ascii(&QuoteForm::LABELS);

/// Compile-time contract verifier — panics at const evaluation time if
/// any entry of `a` aliases any entry of `b` byte-for-byte through
/// [`str::as_bytes`].
///
/// Row-dual peer to [`assert_char_arrays_disjoint`] and
/// [`assert_u8_arrays_disjoint`] on the (element-type) axis of the
/// (element-type × contract-shape) matrix at the (disjointness)
/// column: where the (char) sibling closes the reader-boundary char
/// DISJOINTNESS corner and the (u8) sibling closes the outer-`Sexp`
/// cache-key `u8` DISJOINTNESS corner at compile time, this (`&'static
/// str`) sibling closes the outer-algebras' family-wide `[&'static
/// str; N]` label / prefix / tag / literal DISJOINTNESS corner on the
/// SAME contract-shape column. Together with the pre-existing
/// [`assert_char_arrays_disjoint`] + [`assert_u8_arrays_disjoint`]
/// row-siblings the three helpers close the (element-type ∈
/// {char, u8, &'static str} × contract-shape ∈ {disjointness})
/// 3-corner row of the DISJOINTNESS column at ONE peer const-fn helper
/// per element-type. Contract-orthogonal peer to
/// [`assert_str_array_pairwise_distinct`] on the (INJECTIVITY,
/// DISJOINTNESS) axis of the (contract-shape) column on the SAME
/// (`&'static str`) row: where the pairwise-distinctness sibling binds
/// INTRA-array `∀ i ≠ j : arr[i] ≠ arr[j]`, this DISJOINTNESS sibling
/// binds INTER-array `∀ i, j : a[i] ≠ b[j]` — the two together give
/// every `&'static str` sub-vocabulary on the substrate BOTH intra-
/// array injectivity AND inter-array disjointness at compile time.
///
/// The invariant is load-bearing for every consumer that partitions
/// the two arrays' distinct-values sets into disjoint sub-vocabularies
/// of a shared outer surface —
/// [`QuoteForm::PREFIXES`] (`["'", "\`", ",", ",@"]` — reader-boundary
/// prefix tokens the tokenizer scans in [`crate::reader::tokenize`])
/// is intentionally-closed disjoint from
/// [`QuoteForm::LABELS`] (`["quote", "quasiquote", "unquote",
/// "unquote-splice"]` — human-diagnostic labels the error module
/// projects through [`QuoteForm::label`]) so a reader-boundary token
/// never aliases a diagnostic label spelling; the SAME `QuoteForm::
/// PREFIXES` array is disjoint from
/// [`QuoteForm::IAC_FORGE_TAGS`] (`["quote", "quasiquote", "unquote",
/// "unquote-splicing"]` — canonical iac-forge interop symbol heads the
/// `crate::interop` (removed) round-trip pins through
/// [`QuoteForm::from_iac_forge_tag`]) so the reader-boundary vocabulary
/// stays clean of the canonical-form serialization vocabulary; the
/// SAME `QuoteForm::PREFIXES` array is disjoint from
/// [`AtomKind::LABELS`] (`["symbol", "keyword", "string", "int",
/// "float", "bool"]` — atomic-payload kind labels) so a reader-boundary
/// prefix never aliases an atom-kind diagnostic label; AND
/// [`AtomKind::LABELS`] is intentionally-closed disjoint from
/// [`QuoteForm::LABELS`] so a diagnostic that identifies "the token is
/// an atom of kind X" never aliases "the token is a quote form of
/// kind Y". Every future `[&'static str; N]` pair on the substrate
/// whose distinct-values sets must remain disjoint sub-vocabularies of
/// a shared outer surface participates in the SAME compile-time
/// guarantee via one `const _` line per pair.
///
/// Pre-lift the four disjointness relations lived only as runtime
/// tests (`quote_form_prefixes_disjoint_from_quote_form_labels`,
/// `quote_form_prefixes_disjoint_from_iac_forge_tags`,
/// `quote_form_prefixes_disjoint_from_atom_kind_labels`,
/// `atom_kind_labels_disjoint_from_quote_form_labels`) or implicitly
/// through the outer-algebra's non-aliasing composition rule; post-
/// lift the ARRAY-LEVEL disjointness of the four pinned pairs binds at
/// rustc time via one `const _` line per pair. A regression that
/// silently renamed one of `QuoteForm::PREFIXES`'s entries to a string
/// that aliased a `QuoteForm::LABELS` / `QuoteForm::IAC_FORGE_TAGS` /
/// `AtomKind::LABELS` entry (or vice versa) fails at `cargo check`
/// BEFORE any test scheduler runs.
///
/// Adding a new `[&'static str; N]` sub-vocabulary whose distinct-
/// values set must remain disjoint from another substrate `[&'static
/// str; M]` array's distinct-values set: pair the declaration with
/// `const _: () = assert_str_arrays_disjoint::<N, M>(&Self::FOO_ARRAY,
/// &Other::BAR_ARRAY);` co-located after the array's declaration and
/// the DISJOINTNESS contract binds at compile time. The rustc-forced
/// arities `[&'static str; N]` and `[&'static str; M]` compose with
/// this const-eval sweep so BOTH cardinality-pair AND cross-array
/// disjointness are compile-time theorems on the SAME (a, b) str-array
/// pair.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — pinned by
/// `assert_str_arrays_disjoint_panics_at_runtime_on_collision` and
/// `assert_str_arrays_disjoint_panic_message_names_the_helper_and_str_disjointness_violation_axis`.
/// The panic site carries the `"STR-DISJOINTNESS-VIOLATION"` axis-
/// provenance string chosen DISTINCT from every sibling helper's axis
/// vocabulary (`"duplicate"` on the ARRAY-side pairwise-distinct
/// sibling; `"CHAR-DISJOINTNESS-VIOLATION"` on the (char) row-dual
/// DISJOINTNESS sibling; `"U8-DISJOINTNESS-VIOLATION"` on the (u8)
/// row-dual DISJOINTNESS sibling; `"CHAR-SUBSET-VIOLATION"` on the
/// (char) SUBSET-embedding sibling; `"SUBSET-VIOLATION"` on the (u8)
/// finite-set SUBSET-only sibling; `"RANGE-SUBSET-VIOLATION"` on the
/// (u8) range SUBSET-only sibling; `"OUT-OF-SET"` / `"SET-BYTE-
/// MISSING"` on the (u8) covers-finite-set sibling; `"OUT-OF-RANGE"` /
/// `"MISSING"` on the (u8) covers-inclusive-range sibling; `"ARITY-
/// MISMATCH"` on both (u8) `_permutes_*` compound helpers; `"SET-NOT-
/// PAIRWISE-DISTINCT"` on the (u8) SET-side well-formedness sibling)
/// so a diagnostic that names the failed axis routes UNAMBIGUOUSLY to
/// THIS specific `&'static str` DISJOINTNESS helper. The `"STR-"`
/// prefix disambiguates from the (char) + (u8) row-dual DISJOINTNESS
/// siblings; the shared `"-DISJOINTNESS-VIOLATION"` suffix lets
/// callers grep any row's DISJOINTNESS sibling by
/// `"DISJOINTNESS-VIOLATION"` alone.
///
/// Byte-equality reuse: the helper delegates to the same module-
/// private [`str_bytes_equal`] const-fn helper the sibling
/// [`assert_str_array_pairwise_distinct`] uses — a single canonical
/// site for `&'static str` byte-equality in const context, so a future
/// toolchain stabilising `const fn str::eq` collapses BOTH callers at
/// ONE edit rather than two.
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the family-wide cross-array
///   disjointness contract on the substrate's `&'static str`
///   vocabulary becomes a TYPE-LEVEL theorem the substrate carries per
///   (a, b) str-array pair rather than a runtime test the developer
///   must remember to write per pair.
/// - THEORY.md §III — the typescape; the (element-type × contract-
///   shape) matrix now carries the DISJOINTNESS corner on THREE rows
///   ({char, u8, `&'static str`}) at ONE peer const-fn helper per row.
///   The (element-type ∈ {char, u8, `&'static str`}) × (contract-shape
///   ∈ {pairwise-distinctness (INJECTIVITY), disjointness}) 3×2 =
///   6-corner face on the array-pair-contract prism is now closed at
///   SIX peer const-fn helpers.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   cross-array byte-membership sweep IS the generative shape. Every
///   new `[&'static str; N]` sub-vocabulary array whose distinct-
///   values set is an intentionally-disjoint peer of another substrate
///   `[&'static str; M]` array adds ONE `const _` line to get the
///   disjointness theorem rather than re-deriving a per-pair runtime
///   iterator sweep at each call site.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs; the
///   DISJOINTNESS proof at declaration site AND the outer-algebra's
///   arm-set partition contract (`QuoteForm::PREFIXES` on the reader-
///   boundary token surface vs. `QuoteForm::LABELS` on the human-
///   diagnostic label surface, etc.) regenerate through the SAME
///   `const _` witnesses at the ARRAY level.
///
/// Frontier inspiration: Lean 4's `Finset.disjoint_iff` unfolded to
/// `∀ a ∈ s, ∀ b ∈ t, a ≠ b` at the concrete two-array
/// `[&'static str; N] × [&'static str; M]` monomorphic realisation.
/// The (char, u8, `&'static str`) row triple mirrors Lean's
/// polymorphic `[DecidableEq α] → Finset α → Finset α → Prop`
/// realised at the three concrete element-type instantiations the
/// substrate closes at compile time.
pub const fn assert_str_arrays_disjoint<const N: usize, const M: usize>(
    a: &[&'static str; N],
    b: &[&'static str; M],
) {
    let mut i = 0;
    while i < N {
        let mut j = 0;
        while j < M {
            if str_bytes_equal(a[i], b[j]) {
                panic!(
                    "assert_str_arrays_disjoint: STR-DISJOINTNESS-\
                     VIOLATION — the two family-wide &'static str \
                     arrays `a` and `b` share an entry at some (i, j) \
                     position pair. The substrate's CROSS-ARRAY \
                     DISJOINTNESS contract on the pair is broken; \
                     every consumer that partitions the two arrays' \
                     distinct-values sets into disjoint sub-\
                     vocabularies of a shared outer surface (the \
                     reader-boundary prefix vocabulary at \
                     `QuoteForm::PREFIXES` vs the human-diagnostic \
                     label vocabulary at `QuoteForm::LABELS`; the \
                     reader-boundary prefix vocabulary vs the \
                     canonical iac-forge tag vocabulary at \
                     `QuoteForm::IAC_FORGE_TAGS`; the reader-boundary \
                     prefix vocabulary vs the atomic-kind label \
                     vocabulary at `AtomKind::LABELS`; the atomic-kind \
                     label vocabulary vs the quote-family label \
                     vocabulary; any future typed-disjointness pair on \
                     the substrate's `&'static str` sub-vocabularies) \
                     relies on the two arrays' distinct-values sets \
                     NOT sharing an entry. Fix at WHICHEVER ARRAY-\
                     DECLARATION site drifted (the symmetric \
                     disjointness relation carries no built-in axis-\
                     provenance role split between `a` and `b`) by \
                     renaming the offending entry on one array OR re-\
                     shaping the partition to route the shared entry \
                     to a single sub-vocabulary"
                );
            }
            j += 1;
        }
        i += 1;
    }
}

// Compile-time DISJOINTNESS witnesses — the FOUR substrate-pinned
// (a, b) `[&'static str; N] × [&'static str; M]` pairs whose distinct-
// values sets are intentionally-closed disjoint sub-vocabularies of a
// shared outer surface. Pre-lift the four disjointness relations lived
// only as runtime tests (or implicitly through the outer-algebra's
// non-aliasing composition rule); post-lift the ARRAY-LEVEL
// disjointness of the four pinned pairs binds at rustc time via one
// `const _` line per pair. A regression that silently renamed
// `QuoteForm::QUOTE_PREFIX` (`"'"`) to `"quote"` (aliasing
// `QuoteForm::QUOTE_LABEL` and `QuoteForm::QUOTE_IAC_FORGE_TAG`),
// renamed `AtomKind::SYMBOL_LABEL` (`"symbol"`) to `"quote"` (aliasing
// `QuoteForm::QUOTE_LABEL`), or drifted any entry of one array to
// bytes shared with an entry of a disjoint peer array fails at
// `cargo check` BEFORE any test scheduler runs. Sibling to the FIVE
// `assert_char_arrays_disjoint` witnesses and the TWO
// `assert_u8_arrays_disjoint` witnesses above on the (element-type)
// axis: `char` covers the reader-boundary char sub-vocabularies;
// `u8` covers the outer-`Sexp` cache-key discriminator sub-
// vocabularies; `&'static str` covers the outer-algebras' family-wide
// label / prefix / tag vocabularies.
//
// The four pinned pairs are (all under the shared `&'static str`
// element-type):
//   1. `QuoteForm::PREFIXES` ∩ `QuoteForm::LABELS`         = ∅
//   2. `QuoteForm::PREFIXES` ∩ `QuoteForm::IAC_FORGE_TAGS` = ∅
//   3. `QuoteForm::PREFIXES` ∩ `AtomKind::LABELS`          = ∅
//   4. `AtomKind::LABELS`    ∩ `QuoteForm::LABELS`         = ∅
//
// The TWO remaining disjointness pairs on the twelve-arm
// `SexpShape::LABELS` partition triple
// (`AtomKind::LABELS`, `QuoteForm::LABELS`, `StructuralKind::LABELS`)
// — namely (`AtomKind::LABELS`, `StructuralKind::LABELS`) and
// (`QuoteForm::LABELS`, `StructuralKind::LABELS`) — are pinned as
// peer `const _` lines in `error.rs` (the file where the
// `StructuralKind` host type lives). Split by host-file, unified in
// theorem: together with pair 4 above they cover every pair on the
// three-element sub-vocabulary triple (C(3, 2) = 3), closing the
// DISJOINT-UNION proof
//   `SexpShape::LABELS ≡ AtomKind::LABELS ⊕ QuoteForm::LABELS ⊕
//    StructuralKind::LABELS`
// at compile time.
//
// Note on the intentionally-NOT-pinned pair
// (`QuoteForm::LABELS`, `QuoteForm::IAC_FORGE_TAGS`): the two
// deliberately OVERLAP on three of four arms (`"quote"`, `"quasiquote"`,
// `"unquote"`) because both surfaces spell those three quote-family
// heads with the Common-Lisp-canonical name — `QuoteForm::LABELS` for
// diagnostics, `QuoteForm::IAC_FORGE_TAGS` for canonical serialization.
// Only the fourth arm differs (`QuoteForm::UNQUOTE_SPLICE_LABEL` at
// `"unquote-splice"` vs `QuoteForm::UNQUOTE_SPLICE_IAC_FORGE_TAG` at
// `"unquote-splicing"`) so the pair is NOT disjoint and would fail
// this witness. Pinning it here would be a category error — the
// overlap is load-bearing, not accidental.
const _: () = assert_str_arrays_disjoint::<4, 4>(&QuoteForm::PREFIXES, &QuoteForm::LABELS);
const _: () = assert_str_arrays_disjoint::<4, 4>(&QuoteForm::PREFIXES, &QuoteForm::IAC_FORGE_TAGS);
const _: () = assert_str_arrays_disjoint::<4, 6>(&QuoteForm::PREFIXES, &AtomKind::LABELS);
const _: () = assert_str_arrays_disjoint::<6, 4>(&AtomKind::LABELS, &QuoteForm::LABELS);

/// Compile-time contract verifier — panics at const evaluation time if
/// any entry of `arr` is NOT a member of `set` (byte-for-byte through
/// [`str::as_bytes`]).
///
/// Row-dual peer to [`assert_char_array_within_char_finite_set`] and
/// [`assert_u8_array_within_u8_finite_set`] on the (element-type) axis
/// of the (element-type × contract-shape) matrix at the (subset-
/// embedding) column: where the (char) sibling closes the reader-
/// boundary `[char; N] ⊆ [char; M]` corner and the (u8) sibling closes
/// the outer-`Sexp` cache-key `[u8; N] ⊆ [u8; M]` finite-set embedding
/// corner at compile time, this (`&'static str`) sibling closes the
/// outer-algebras' family-wide `[&'static str; N] ⊆ [&'static str; M]`
/// label / prefix / tag SUB-VOCABULARY carving corner. Together with
/// the pre-existing [`assert_char_array_within_char_finite_set`] +
/// [`assert_u8_array_within_u8_finite_set`] row-siblings the three
/// helpers close the (element-type ∈ {char, u8, &'static str} ×
/// contract-shape ∈ {subset-embedding}) 3-corner row of the SUBSET-
/// EMBEDDING column at ONE peer const-fn helper per element-type.
/// Contract-orthogonal peer to [`assert_str_array_pairwise_distinct`]
/// and [`assert_str_arrays_disjoint`] on the (INJECTIVITY,
/// DISJOINTNESS, SUBSET-EMBEDDING) axis of the (contract-shape) column
/// on the SAME (`&'static str`) row: where the pairwise-distinctness
/// sibling binds INTRA-array `∀ i ≠ j : arr[i] ≠ arr[j]` and the
/// disjointness sibling binds INTER-array `∀ i, j : a[i] ≠ b[j]`, this
/// SUBSET-EMBEDDING sibling binds ORIENTED-INTER-array `∀ i : ∃ j :
/// arr[i] = set[j]` — the three together give every `&'static str`
/// sub-vocabulary on the substrate INTRA-array injectivity AND INTER-
/// array disjointness (symmetric) AND INTER-array subset embedding
/// (oriented) at compile time.
///
/// The invariant is load-bearing for every consumer that carves a
/// SUB-vocabulary of a shared OUTER `&'static str` vocabulary:
/// [`AtomKind::LABELS`] (`[&; 6]`, `["symbol", "keyword", "string",
/// "int", "float", "bool"]` — the atomic-payload kind labels) is an
/// intentionally-closed proper subset of
/// [`crate::error::SexpShape::LABELS`] (`[&; 12]`, the twelve outer-
/// `Sexp` shape labels; six atomic + two structural + four quote-
/// family) so every atom-kind diagnostic label stays inside the outer-
/// shape label vocabulary; [`QuoteForm::LABELS`] (`[&; 4]`, `["quote",
/// "quasiquote", "unquote", "unquote-splice"]` — the quote-family
/// labels) is likewise a proper subset of the SAME
/// [`crate::error::SexpShape::LABELS`] so every quote-family diagnostic
/// stays inside the outer-shape vocabulary; and
/// [`crate::error::StructuralKind::LABELS`] (`[&; 2]`, `["nil",
/// "list"]` — the structural-shape labels) is the third proper subset
/// of the SAME twelve-arm superset. Union together `AtomKind::LABELS`
/// (6) + `QuoteForm::LABELS` (4) + `StructuralKind::LABELS` (2) = 12
/// = `SexpShape::LABELS.len()` closes a NON-CONTIGUOUS PARTITION of
/// the outer twelve-arm vocabulary at compile time; the three
/// SUBSET-EMBEDDING witnesses PLUS the pre-existing pairwise-
/// distinctness witnesses PLUS the pre-existing (AtomKind, QuoteForm)
/// disjointness witness compose to a full partition proof. Every
/// future `[&'static str; N]` sub-vocabulary on the substrate whose
/// distinct-values set must remain embedded in a shared outer surface
/// (a new tokenizer keyword vocabulary embedded in an outer prefix
/// vocabulary; a new diagnostic label vocabulary embedded in an outer
/// error-family label vocabulary; a new algebra whose display / label
/// / prefix arrays must remain sub-vocabularies of the closed-set
/// outer algebras' `&'static str` surface) gets the subset-embedding
/// theorem at ONE `const _` line rather than a per-pair runtime
/// iterator sweep.
///
/// SET-side well-formedness is DELEGATED to the sibling ARRAY-side
/// pairwise-distinctness helper ([`assert_str_array_pairwise_distinct`])
/// via a co-located call at the TOP of the sweep — a malformed `set`
/// (e.g. `["a", "a", "b"]`) is NOT a well-formed finite set of
/// cardinality `M` and silently mis-verifies the intended subset
/// contract on any `arr` embedded in the DISTINCT-value subset. The
/// delegated arm routes drift on the CALLER'S TARGET-SET SPEC to the
/// SET-side well-formedness axis rather than to a downstream STR-
/// SUBSET-VIOLATION symptom on `arr`. A well-formed `set` passes this
/// arm as a no-op — the sweep is const-eval-elidable and costs zero
/// at rustc-time on the substrate call sites. The (str) row does NOT
/// carry a separate `assert_str_finite_set_pairwise_distinct` alias
/// (the (u8) row's `assert_u8_finite_set_pairwise_distinct` is the
/// only SET-side well-formedness peer on the substrate); the
/// delegation reuses the ARRAY-side helper directly, matching the
/// (char) row's (`assert_char_array_within_char_finite_set` →
/// `assert_char_array_pairwise_distinct`) delegation shape.
///
/// Pre-lift the three subset embeddings lived as prose in the parent
/// arrays' partition-rule docstrings (the `SexpShape::LABELS` twelve-
/// arm decomposition into atomic / structural / quote-family sub-
/// vocabularies) and as runtime `_pairwise_distinct` cross-checks on
/// the tests submodule — the ARRAY-LEVEL embedding was not itself
/// pinned. Post-lift the three witnesses bind at rustc time via one
/// `const _` line per pair; a regression that silently re-inlined
/// either the SUBSET side (dropping `AtomKind::SYMBOL_LABEL`'s
/// `SexpShape::SYMBOL_LABEL` alias to a fresh distinct byte spelling)
/// or the SUPERSET side (dropping `SexpShape::SYMBOL_LABEL` and
/// leaving `AtomKind::SYMBOL_LABEL` as a stale copy of `"symbol"`)
/// fails at `cargo check` BEFORE any test scheduler runs.
///
/// Adding a new family-wide `[&'static str; N]` sub-vocabulary whose
/// distinct-values set must remain embedded in another substrate
/// `[&'static str; M]` array's distinct-values set: pair the
/// declaration with `const _: () = assert_str_array_within_str_finite_
/// set::<N, M>(&Self::FOO_ARRAY, &Other::BAR_ARRAY);` co-located after
/// the array's declaration and the SUBSET-EMBEDDING contract binds at
/// compile time. The rustc-forced arities `[&'static str; N]` and
/// `[&'static str; M]` compose with this const-eval sweep so BOTH
/// cardinality-pair AND cross-array subset embedding are compile-time
/// theorems on the SAME (arr, set) str-array pair.
///
/// Delegates to the existing module-private [`str_bytes_equal`] const-
/// fn helper so a future toolchain stabilising `const fn str::eq`
/// collapses ALL THREE (str)-row helpers ((str, pairwise-distinct),
/// (str, disjointness), (str, subset-embedding)) through ONE edit.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — pinned by
/// `assert_str_array_within_str_finite_set_panics_at_runtime_on_out_of_set_entry`
/// and
/// `assert_str_array_within_str_finite_set_panic_message_names_the_helper_and_str_subset_violation_axis`.
/// The panic site carries the `"STR-SUBSET-VIOLATION"` axis-provenance
/// string chosen DISTINCT from every sibling helper's axis vocabulary
/// (`"duplicate"` on the ARRAY-side pairwise-distinct sibling; `"STR-
/// DISJOINTNESS-VIOLATION"` on the (str) row DISJOINTNESS sibling;
/// `"CHAR-SUBSET-VIOLATION"` on the (char) row-dual SUBSET sibling;
/// `"SUBSET-VIOLATION"` on the (u8) row-dual finite-set SUBSET-only
/// sibling; `"RANGE-SUBSET-VIOLATION"` on the (u8) range SUBSET-only
/// sibling; `"CHAR-DISJOINTNESS-VIOLATION"` / `"U8-DISJOINTNESS-
/// VIOLATION"` on the (char) / (u8) row-dual DISJOINTNESS siblings;
/// `"OUT-OF-SET"` / `"SET-BYTE-MISSING"` on the (u8) covers-finite-
/// set sibling; `"OUT-OF-RANGE"` / `"MISSING"` on the (u8) covers-
/// inclusive-range sibling; `"ARITY-MISMATCH"` on both (u8)
/// `_permutes_*` compound helpers; `"SET-NOT-PAIRWISE-DISTINCT"` on
/// the (u8) SET-side well-formedness sibling) so a diagnostic that
/// names the failed axis routes UNAMBIGUOUSLY to (a) this specific
/// `&'static str` SUBSET-embedding helper, (b) the `arr` argument as
/// the drift site rather than the `set` argument specifying the
/// target superset. The `"STR-"` prefix disambiguates from the
/// (char) + (u8) row-dual peers; the shared `"-SUBSET-VIOLATION"`
/// suffix lets callers grep any row's SUBSET-embedding sibling by
/// the shared `"SUBSET-VIOLATION"` suffix alone.
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the family-wide cross-array
///   subset-embedding contract on `&'static str` sub-vocabularies
///   becomes a TYPE-LEVEL theorem the substrate carries per (arr,
///   set) str-array pair rather than a runtime test the developer
///   must remember to write per pair.
/// - THEORY.md §III — the typescape; the (element-type × contract-
///   shape) matrix now carries the SUBSET-EMBEDDING corner on THREE
///   rows at ONE peer const-fn helper per row. The (subset,
///   disjointness) 2-corner face on the (`&'static str`) row is now
///   closed at TWO peer const-fn helpers —
///   [`assert_str_arrays_disjoint`] on the DISJOINTNESS corner and
///   this helper on the SUBSET corner.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   cross-array membership sweep IS the generative shape. Every new
///   closed-set `&'static str` sub-vocabulary array whose distinct-
///   values set is an intentionally-embedded proper subset of another
///   substrate `&'static str` array adds ONE `const _` line to get
///   the subset-embedding theorem rather than re-deriving a per-pair
///   runtime iterator sweep at each call site.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs; the
///   SUBSET-EMBEDDING proof at declaration site AND the outer-
///   algebra's twelve-arm shape-label partition contract regenerate
///   through the SAME `const _` witnesses at the ARRAY level.
///
/// Frontier inspiration: Lean 4's `Finset.subset_iff : s ⊆ t ↔ ∀ a ∈
/// s, a ∈ t` unfolded at the concrete `[&'static str; N] ⊆ [&'static
/// str; M]` monomorphic realisation — the substrate primitive here
/// embeds the same subset relation as a rustc const-eval-time proof
/// obligation at every `assert_str_array_within_str_finite_set` call
/// site rather than as a Lean tactic invocation deferred to
/// `elab_command`. The (char, u8, `&'static str`) row triple mirrors
/// Lean's polymorphic `[DecidableEq α] → Finset α → Finset α → Prop`
/// realised at three concrete element-type instantiations the
/// substrate closes at compile time.
pub const fn assert_str_array_within_str_finite_set<const N: usize, const M: usize>(
    arr: &[&'static str; N],
    set: &[&'static str; M],
) {
    // Delegate target-set well-formedness to the sibling ARRAY-side
    // pairwise-distinctness helper FIRST. Placed BEFORE the STR-
    // SUBSET-VIOLATION sweep below because a malformed `set` (e.g.
    // `["a", "a", "b"]`) is not a well-formed finite set of
    // cardinality `M` and silently mis-verifies the intended subset
    // contract on any `arr` embedded in the DISTINCT-value subset.
    // Routes drift on the CALLER'S TARGET-SET SPEC to the SET-side
    // well-formedness axis (via the sibling's own panic-name prefix)
    // rather than to a downstream STR-SUBSET-VIOLATION symptom on
    // `arr`. A well-formed `set` passes this arm as a no-op — the
    // sweep is const-eval-elidable and costs zero at rustc-time on
    // the substrate call sites.
    assert_str_array_pairwise_distinct(set);
    let mut i = 0;
    while i < N {
        let mut j = 0;
        let mut found = false;
        while j < M {
            if str_bytes_equal(arr[i], set[j]) {
                found = true;
                break;
            }
            j += 1;
        }
        if !found {
            panic!(
                "assert_str_array_within_str_finite_set: STR-SUBSET-\
                 VIOLATION — the family-wide &'static str array `arr` \
                 carries an entry at some position whose bytes are \
                 NOT a member of the target finite superset partition \
                 `set`. The substrate's SUBSET-EMBEDDING contract on \
                 the array is broken; every consumer that expects the \
                 array's distinct-value set to be a subset of the \
                 target finite partition (`AtomKind::LABELS ⊂ \
                 SexpShape::LABELS` on the atomic-payload sub-\
                 vocabulary carve of the twelve-arm outer-shape label \
                 vocabulary; `QuoteForm::LABELS ⊂ SexpShape::LABELS` \
                 on the quote-family sub-vocabulary carve of the SAME \
                 twelve-arm outer-shape label vocabulary; \
                 `StructuralKind::LABELS ⊂ SexpShape::LABELS` on the \
                 structural sub-vocabulary carve of the SAME twelve-\
                 arm outer-shape label vocabulary; any future typed-\
                 subset embedding on the substrate's `&'static str` \
                 sub-vocabularies) relies on every array entry \
                 staying within the target superset. Fix at the \
                 ARRAY-DECLARATION site (the `arr` under \
                 verification, NOT the `set` argument specifying the \
                 target superset) by dropping the offending entry OR \
                 by extending `set` to cover it — the choice depends \
                 on whether the drift is an unintended overshoot \
                 outside the parent superset or an intentional \
                 extension of the superset vocabulary"
            );
        }
        i += 1;
    }
}

/// Compile-time contract verifier — panics at const evaluation time if
/// any entry of the target finite `set` is NOT reached by at least one
/// entry across the three sub-vocabulary arrays `a`, `b`, `c`.
///
/// SURJECTIVITY dual of [`assert_str_array_within_str_finite_set`] at
/// the (`&'static str`) row of the (element-type × contract-shape)
/// matrix, extended to the 3-array-union carrier shape: where the
/// within-helper closes the SUBSET direction for a single array
/// (`arr ⊆ set`), this helper closes the COVERAGE direction for a
/// three-array partition triple (`set ⊆ a ∪ b ∪ c`) at compile time.
/// Composed with the three sibling SUBSET-EMBEDDING witnesses (each
/// sub-array's `_within_str_finite_set` pin) AND the three sibling
/// pairwise-DISJOINTNESS witnesses (each pair's
/// `assert_str_arrays_disjoint` pin) AND the parent's INJECTIVITY
/// witness (`_pairwise_distinct` on the parent set), the four
/// contract-shape corners jointly close the full DISJOINT-UNION
/// theorem `set ≡ a ⊕ b ⊕ c` at rustc const-eval time on the
/// substrate's twelve-arm `SexpShape::LABELS` outer-vocabulary
/// partition — the pre-existing runtime cross-check
/// `sexp_shape_labels_is_disjoint_union_of_three_sub_vocabularies`
/// becomes a defense-in-depth safety net for the SAME theorem the
/// compile-time witness triple now enforces at `cargo check` time,
/// one invocation stage earlier.
///
/// Delegates target-set well-formedness to the ARRAY-side
/// [`assert_str_array_pairwise_distinct`] helper via a co-located
/// call at the TOP of the sweep — a malformed `set` (e.g.
/// `["a", "a", "b"]`) is not a well-formed finite set of cardinality
/// `W` and silently mis-verifies the intended COVERAGE contract on
/// any `(a, b, c)` triple whose distinct-value union misses the
/// duplicated set byte (the duplicated byte still counts as covered
/// on the FIRST hit even if the second copy is absent from the
/// union). Routes drift on the CALLER'S TARGET-SET SPEC to the SET-
/// side well-formedness axis rather than to a downstream SET-STR-
/// MISSING symptom on `(a, b, c)`. The (str) row does NOT carry a
/// separate `assert_str_finite_set_pairwise_distinct` alias; the
/// delegation reuses the ARRAY-side helper directly, matching the
/// (str) row's sibling delegation shape at
/// [`assert_str_array_within_str_finite_set`].
///
/// The sub-vocabulary arities `N`, `M`, `K` and the parent
/// cardinality `W` are INDEPENDENT const generics: this helper
/// intentionally does NOT enforce `N + M + K == W` at const-eval
/// time. That arity sum is a CONSEQUENCE of the disjoint-union
/// theorem (COVERAGE here + pairwise DISJOINTNESS at the sibling
/// witnesses + parent INJECTIVITY) rather than a separate pre-
/// condition; a caller that binds all three peer witnesses AND this
/// COVERAGE witness AND finds a cardinality mismatch has necessarily
/// broken one of the four contract corners, and the diagnostic fires
/// on the specific corner that broke rather than on a synthetic
/// arity-sum pre-check. Under-covering triples (`N + M + K < W`) fire
/// the SET-STR-MISSING panic here; over-covering triples
/// (`N + M + K > W`) fire the STR-DISJOINTNESS-VIOLATION panic at the
/// sibling pairwise-disjointness witness or the STR-SUBSET-VIOLATION
/// panic at the sibling `_within_str_finite_set` witness. The four-
/// corner diagnostic partition stays sharp on the FAILURE mode rather
/// than collapsing every drift onto a single arity-sum axis.
///
/// Pre-lift the twelve-arm `SexpShape::LABELS` disjoint-union
/// theorem lived as a runtime cross-check
/// (`sexp_shape_labels_is_disjoint_union_of_three_sub_vocabularies`
/// at `error.rs` tests module) that iterated every parent label and
/// counted its multiplicity across the three sub-vocabularies. The
/// runtime sweep enforced BOTH directions (⊆) and (⊇) of the
/// disjoint-union at test time; the (⊇) direction was already lifted
/// to compile time via three `_within_str_finite_set` witnesses in
/// `error.rs` (each sub-vocab ⊂ parent) and three
/// `assert_str_arrays_disjoint` witnesses (pairwise disjoint), but
/// the (⊆) direction — every parent label appears in at least one
/// sub-vocabulary — remained runtime-only. Post-lift this helper
/// binds the (⊆) direction at `cargo check` time via ONE `const _`
/// line on the (`AtomKind::LABELS`, `QuoteForm::LABELS`,
/// `StructuralKind::LABELS`, `SexpShape::LABELS`) partition-triple-
/// with-parent quadruple; a regression that silently drops a variant
/// from one of the three sub-vocabularies (e.g. removing
/// `AtomKind::Bool` and its `AtomKind::BOOL_LABEL` alias while
/// leaving `SexpShape::Bool` and its `SexpShape::BOOL_LABEL` alias in
/// the parent vocabulary) fires the SET-STR-MISSING panic at
/// `cargo check` BEFORE any test scheduler runs.
///
/// Adding a new n-way partition proof on the substrate's `&'static
/// str` vocabularies (e.g. a hypothetical fourth sub-vocabulary
/// carving of a widened `SexpShape` parent, or an independent
/// partition on `Atom::ESCAPE_SOURCES` into printable / whitespace /
/// control sub-vocabularies): pair the parent+partition declaration
/// with `const _: () = assert_str_finite_set_covered_by_three_str_
/// arrays::<N, M, K, W>(&Foo::LABELS, &Bar::LABELS, &Baz::LABELS,
/// &Parent::LABELS);` co-located after the partition arrays'
/// declarations and the COVERAGE contract binds at compile time. The
/// rustc-forced arities `[&'static str; N]`, `[&'static str; M]`,
/// `[&'static str; K]`, `[&'static str; W]` compose with this const-
/// eval sweep so BOTH the four cardinalities AND the (⊆) disjoint-
/// union direction are compile-time theorems on the SAME partition
/// quadruple.
///
/// Delegates to the existing module-private [`str_bytes_equal`]
/// const-fn helper so a future toolchain stabilising `const fn
/// str::eq` collapses ALL FOUR (str)-row helpers ((str, pairwise-
/// distinct), (str, disjointness), (str, subset-embedding), (str,
/// three-array-coverage)) through ONE edit.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — pinned by
/// `assert_str_finite_set_covered_by_three_str_arrays_panics_at_runtime_on_uncovered_parent_entry`
/// and
/// `assert_str_finite_set_covered_by_three_str_arrays_panic_message_names_the_helper_and_set_str_missing_axis`.
/// The panic site carries the `"SET-STR-MISSING"` axis-provenance
/// string chosen DISTINCT from every sibling helper's axis vocabulary
/// (`"duplicate"` on the ARRAY-side pairwise-distinct sibling; `"STR-
/// SUBSET-VIOLATION"` on the (str) row SUBSET sibling; `"STR-
/// DISJOINTNESS-VIOLATION"` on the (str) row DISJOINTNESS sibling;
/// `"CHAR-SUBSET-VIOLATION"` on the (char) row-dual SUBSET sibling;
/// `"SUBSET-VIOLATION"` on the (u8) row-dual finite-set SUBSET-only
/// sibling; `"OUT-OF-SET"` / `"SET-BYTE-MISSING"` on the (u8) covers-
/// finite-set sibling; `"OUT-OF-RANGE"` / `"MISSING"` on the (u8)
/// covers-inclusive-range sibling; `"ARITY-MISMATCH"` on both (u8)
/// `_permutes_*` compound helpers; `"SET-NOT-PAIRWISE-DISTINCT"` on
/// the (u8) SET-side well-formedness sibling) so a diagnostic that
/// names the failed axis routes UNAMBIGUOUSLY to (a) this specific
/// three-array COVERAGE helper on the `&'static str` element-type
/// row, (b) the `set` argument as the drift-target (the parent
/// element that no sub-array reaches) rather than any single sub-
/// vocabulary carrier. The `"SET-STR-MISSING"` axis distinguishes
/// from the (u8) row's `"SET-BYTE-MISSING"` peer via the element-
/// type infix — one substring search per element-type routes any
/// row's SET-side COVERAGE-VIOLATION back to its element-type peer.
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the DISJOINT-UNION theorem
///   on `&'static str` sub-vocabulary partitions becomes a TYPE-LEVEL
///   theorem the substrate carries per (partition-triple, parent)
///   quadruple rather than a runtime test the developer must
///   remember to write per partition.
/// - THEORY.md §III — the typescape; the (element-type × contract-
///   shape) matrix now carries the THREE-ARRAY-COVERAGE corner on
///   the (`&'static str`) row at ONE peer const-fn helper. Combined
///   with the pre-existing (str, pairwise-distinct), (str, subset-
///   embedding), and (str, disjointness) siblings, the four contract-
///   shape corners on the (`&'static str`) row jointly close the
///   full DISJOINT-UNION theorem on any n-way partition of a
///   `&'static str` vocabulary at compile time.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   coverage sweep IS the generative shape. Every new n-way `&'static
///   str` vocabulary partition adds ONE `const _` line (plus the
///   sibling SUBSET-EMBEDDING and pairwise-DISJOINTNESS witnesses per
///   sub-array pair) to get the DISJOINT-UNION theorem rather than
///   re-deriving a per-partition runtime iterator sweep at each site.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs; the
///   COVERAGE proof at declaration site AND the outer-algebra's
///   twelve-arm shape-label partition regenerate through the SAME
///   `const _` witness at the ARRAY level.
///
/// Frontier inspiration: Lean 4's `Finset.disjUnion` /
/// `Finset.biUnion_eq_iff_forall_mem_exists` unfolded at the
/// concrete 3-arm `[&'static str; W] ⊆ [&'static str; N] ∪ [&'static
/// str; M] ∪ [&'static str; K]` monomorphic realisation — the
/// substrate primitive here embeds the same coverage relation as a
/// rustc const-eval-time proof obligation at every partition site
/// rather than as a Lean tactic invocation deferred to `elab_command`.
pub const fn assert_str_finite_set_covered_by_three_str_arrays<
    const N: usize,
    const M: usize,
    const K: usize,
    const W: usize,
>(
    a: &[&'static str; N],
    b: &[&'static str; M],
    c: &[&'static str; K],
    set: &[&'static str; W],
) {
    // Delegate target-set well-formedness to the sibling ARRAY-side
    // pairwise-distinctness helper FIRST. Placed BEFORE the SET-STR-
    // MISSING sweep below because a malformed `set` (e.g. `["a", "a",
    // "b"]`) is not a well-formed finite set of cardinality `W` and
    // silently mis-verifies the intended COVERAGE contract — the
    // duplicated byte still counts as covered on the FIRST hit even
    // if the second copy is absent from the union. Routes drift on
    // the CALLER'S TARGET-SET SPEC to the SET-side well-formedness
    // axis rather than to a downstream SET-STR-MISSING symptom on
    // `(a, b, c)`. A well-formed `set` passes this arm as a no-op —
    // the sweep is const-eval-elidable and costs zero at rustc-time
    // on the substrate call sites.
    assert_str_array_pairwise_distinct(set);
    let mut w = 0;
    while w < W {
        let target = set[w];
        let mut found = false;
        let mut i = 0;
        while i < N {
            if str_bytes_equal(target, a[i]) {
                found = true;
                break;
            }
            i += 1;
        }
        if !found {
            let mut j = 0;
            while j < M {
                if str_bytes_equal(target, b[j]) {
                    found = true;
                    break;
                }
                j += 1;
            }
        }
        if !found {
            let mut k = 0;
            while k < K {
                if str_bytes_equal(target, c[k]) {
                    found = true;
                    break;
                }
                k += 1;
            }
        }
        if !found {
            panic!(
                "assert_str_finite_set_covered_by_three_str_arrays: \
                 SET-STR-MISSING — the target finite `set` carries a \
                 parent entry at some position whose bytes are NOT \
                 reached by any of the three sub-vocabulary arrays \
                 `a`, `b`, `c`. The substrate's THREE-ARRAY COVERAGE \
                 contract on the partition-triple is broken; every \
                 consumer that expects the union `a ∪ b ∪ c` to span \
                 the parent finite vocabulary (`SexpShape::LABELS ≡ \
                 AtomKind::LABELS ⊕ QuoteForm::LABELS ⊕ \
                 StructuralKind::LABELS` on the twelve-arm outer-\
                 shape label partition; any future n-way disjoint-\
                 union theorem on the substrate's `&'static str` \
                 vocabularies) relies on every parent entry being \
                 reached by at least one sub-array. Fix at the SUB-\
                 VOCABULARY DECLARATION site (the missing entry is \
                 an intentional variant of the parent that ONE sub-\
                 vocabulary must carry) OR at the PARENT-VOCABULARY \
                 DECLARATION site (the missing entry was inadvertently \
                 added to the parent without extending any sub-\
                 vocabulary) — the choice depends on whether the \
                 drift is an unintended parent overshoot or an \
                 unintended sub-vocabulary shrinkage"
            );
        }
        w += 1;
    }
}

/// Compile-time contract verifier — panics at const evaluation time if
/// `arr` is NOT the concatenation of `K` byte-verbatim replicas of
/// `head` followed by `N - K` byte-verbatim replicas of `tail` on the
/// substrate's family-wide `[&'static str; N]` MANY-TO-ONE variant →
/// canonical-projection vocabulary. Binds ONE conjunct clause: BLOCK-
/// CONSTANCY-VIOLATION — every entry in the HEAD segment `arr[0..K)`
/// MUST byte-equal `head` and every entry in the TAIL segment
/// `arr[K..N)` MUST byte-equal `tail`.
///
/// Contract-orthogonal peer to [`assert_str_array_pairwise_distinct`]
/// on the (INJECTIVITY, MANY-TO-ONE-BLOCK-CONSTANCY) axis of the
/// (contract-shape) column on the SAME (`&'static str`) row: where the
/// pairwise-distinctness sibling binds `∀ i ≠ j : arr[i] ≠ arr[j]` at
/// compile time (INTRA-ARRAY INJECTIVITY on arrays whose per-index
/// projection is bijective with a per-index typed source), this BLOCK-
/// CONSTANCY sibling binds `arr = [head; K] ++ [tail; N - K]` at
/// compile time (INTRA-ARRAY BLOCK-CONSTANT MANY-TO-ONE PROJECTION on
/// arrays whose per-index projection is a MANY-TO-ONE pattern
/// collapsing multiple contiguous typed sources onto ONE canonical
/// scalar byte). The two helpers close the (INJECTIVITY, MANY-TO-ONE-
/// BLOCK-CONSTANCY) 2-corner face on the (`&'static str`) row at ONE
/// peer const-fn helper per structural shape; a single family-wide
/// `[&'static str; N]` array picks whichever helper matches its
/// per-index projection cardinality (a BIJECTIVE per-index projection
/// binds the pairwise-distinct sibling; a MANY-TO-ONE per-index
/// projection binds this block-constancy sibling).
///
/// The invariant is load-bearing for the substrate's typed variant →
/// canonical-projection MANY-TO-ONE closed-set surface at
/// [`crate::error::CompilerSpecIoStage::OPERATIONS`]: the four typed
/// variants of [`crate::error::CompilerSpecIoStage`] project through
/// [`crate::error::CompilerSpecIoStage::operation`] onto EXACTLY TWO
/// canonical `&'static str` operation labels
/// ([`crate::error::CompilerSpecIoStage::REALIZE_TO_DISK_OPERATION`]
/// (`"realize_to_disk"`) shared by
/// [`crate::error::CompilerSpecIoStage::RealizeToDiskSerialize`] and
/// [`crate::error::CompilerSpecIoStage::RealizeToDiskWrite`];
/// [`crate::error::CompilerSpecIoStage::LOAD_FROM_DISK_OPERATION`]
/// (`"load_from_disk"`) shared by
/// [`crate::error::CompilerSpecIoStage::LoadFromDiskRead`] and
/// [`crate::error::CompilerSpecIoStage::LoadFromDiskDeserialize`]).
/// The `[REALIZE, REALIZE, LOAD, LOAD]` block-constant shape encodes
/// the compound-key `"{operation}: {stage}"` surface's 2-of-2-to-2
/// partition — a regression that silently flip-flopped the projection
/// (e.g. reorder to `[REALIZE, LOAD, REALIZE, LOAD]`, drift a variant
/// slot to a distinct third operation label) would compile cleanly
/// past the sibling `_pairwise_distinct` exclusion (this array is
/// INTENTIONALLY non-injective, so the pairwise-distinct helper does
/// NOT bind it) and only fail at test time via the runtime pin
/// `compiler_spec_io_stage_operations_align_with_all_by_index`; post-
/// lift the ARRAY-LEVEL block-constancy binds at rustc time via ONE
/// `const _` line, one invocation stage earlier than the runtime pin.
///
/// The `K = 0` and `K = N` degenerate corners collapse the array into
/// a ONE-BLOCK replica: `K = 0` yields `arr = [tail; N]`; `K = N`
/// yields `arr = [head; N]`. Both corners pass through the same
/// sweep without a distinct code path, and both are covered by the
/// helper's test surface — a future substrate array whose per-index
/// projection collapses ALL positions onto ONE canonical byte binds
/// through either degenerate corner at ONE const-generic setting.
///
/// SET-side well-formedness: no SET-side arm here — the helper takes
/// TWO scalars, NOT a scalar plus a target-set spec, so there's no
/// SET well-formedness axis to gate on the CALLER'S input. The two
/// scalars `head` and `tail` MAY be byte-equal (in which case the
/// helper degenerates to a SINGLE-BLOCK replica-check that binds the
/// SAME constancy across all `N` positions with `head == tail`); the
/// two scalars MAY be byte-distinct (the intended TWO-BLOCK partition
/// shape). Either case is a well-formed BLOCK-CONSTANCY invariant.
///
/// CARDINALITY-MISMATCH gate: `K > N` fails FIRST at const-eval time
/// (before any per-position sweep begins) with a CARDINALITY-MISMATCH
/// arm so a caller-side turbofish arity slip on the `K` const-generic
/// routes to the CARDINALITY axis rather than silently degenerating
/// into a truncated head-only sweep. The `K == N` and `K == 0`
/// corners are LEGAL (the ONE-BLOCK degenerate shapes) so the gate
/// is `K > N`, not `K >= N`.
///
/// Adding a new family-wide `[&'static str; N]` MANY-TO-ONE variant →
/// canonical-projection array to the substrate: pair the declaration
/// with `const _: () = assert_str_array_is_concatenation_of_two_
/// scalar_replicas::<N, K>(&Self::FOO, HEAD_SCALAR, TAIL_SCALAR);`
/// co-located after the array's declaration and the block-constancy
/// contract binds at compile time. The rustc-forced arity
/// `[&'static str; N]` composes with this const-eval sweep so BOTH
/// cardinality AND per-index MANY-TO-ONE block-constancy are compile-
/// time theorems on the SAME array.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — pinned by
/// `assert_str_array_is_concatenation_of_two_scalar_replicas_panics_
/// at_runtime_on_head_segment_drift`, `..._on_tail_segment_drift`,
/// `..._on_arity_slip`, and `..._panic_message_names_the_helper_and_
/// block_constancy_violation_axis`.
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the MANY-TO-ONE variant →
///   canonical-projection block-constant contract on the `&'static
///   str` per-index projection axis becomes a TYPE-LEVEL theorem the
///   substrate carries per (arr, head, tail, K) quadruple rather than
///   a runtime iterator sweep the developer must remember to write
///   per quadruple.
/// - THEORY.md §III — the typescape; the (element-type × contract-
///   shape) matrix now carries the MANY-TO-ONE-BLOCK-CONSTANCY corner
///   on the (`&'static str`) row at ONE peer const-fn helper. Combined
///   with the pre-existing (`_pairwise_distinct`) INJECTIVITY sibling
///   the two helpers close the (INJECTIVITY, MANY-TO-ONE-BLOCK-
///   CONSTANCY) 2-corner face on the (`&'static str`) row — every
///   family-wide `[&'static str; N]` per-index projection array picks
///   the corner that matches its per-index projection cardinality.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   block-constant sweep IS the generative shape. Every new MANY-TO-
///   ONE variant → canonical-projection substrate closed set adds ONE
///   `const _` line to get the block-constant theorem rather than
///   re-deriving a per-projection runtime multiplicity check.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs; the
///   BLOCK-CONSTANCY proof at declaration site AND the compound-key
///   `"{operation}: {stage}"` surface's partition contract regenerate
///   through the SAME `const _` witness at the ARRAY level.
///
/// Frontier inspiration: Lean 4's `List.replicate` unfolded at the
/// concrete 2-block `List.replicate K head ++ List.replicate (N - K)
/// tail` monomorphic realisation — the substrate primitive embeds
/// the same run-length shape as a rustc const-eval-time proof
/// obligation at every block-constant projection site rather than as
/// a Lean tactic invocation deferred to `elab_command`. The MANY-TO-
/// ONE variant → canonical-projection shape mirrors GHC Core's
/// constant-folding of a `case` scrutinee whose match arms collapse a
/// wider sum type onto a narrower sum type via a per-arm literal
/// projection; where GHC folds this at Core compilation, the
/// substrate binds the projection identity at rustc const-eval time.
pub const fn assert_str_array_is_concatenation_of_two_scalar_replicas<
    const N: usize,
    const K: usize,
>(
    arr: &[&'static str; N],
    head: &'static str,
    tail: &'static str,
) {
    if K > N {
        panic!(
            "assert_str_array_is_concatenation_of_two_scalar_replicas: \
             CARDINALITY-MISMATCH — the two const parameters `N` and \
             `K` must satisfy `K <= N` so the HEAD segment of `arr` \
             (positions `[0..K)`) followed by the TAIL segment \
             (positions `[K..N)`) exactly cover `arr`'s `N` \
             positions. Fix at the `const _` witness's turbofish by \
             reconciling the two arities against the composite's \
             declared arity. The CARDINALITY-MISMATCH gate \
             distinguishes THIS failure from every content-drift arm \
             — a mistyped ARITY on the caller side fails HERE before \
             any per-position sweep begins, so a subtle arity slip \
             doesn't silently degenerate into a truncated head-only \
             sweep."
        );
    }
    let mut i = 0;
    while i < K {
        if !str_bytes_equal(arr[i], head) {
            panic!(
                "assert_str_array_is_concatenation_of_two_scalar_replicas: \
                 HEAD-SEGMENT-BLOCK-CONSTANCY-VIOLATION — the family-\
                 wide `&'static str` array `arr` carries an entry at \
                 some position in `[0, K)` (the HEAD segment) that \
                 does NOT byte-for-byte equal the peer `head` scalar. \
                 The substrate's HEAD-SEGMENT BLOCK-CONSTANCY \
                 contract on the array is broken; every consumer that \
                 reads `arr[0..K)` and the peer `head` scalar as \
                 INTERCHANGEABLE (any MANY-TO-ONE variant → \
                 canonical-projection consumer expecting the first \
                 `K` variant slots to share ONE canonical projection \
                 byte — e.g. the `zip(Self::ALL, Self::OPERATIONS)` \
                 compound-key `\"{{operation}}: {{stage}}\"` surface \
                 consumers on \
                 `crate::error::CompilerSpecIoStage::OPERATIONS` \
                 whose first two slots project through \
                 `crate::error::CompilerSpecIoStage::REALIZE_TO_DISK_\
                 OPERATION`) relies on this invariant. Fix at the \
                 ARRAY-DECLARATION site (the drifted `arr[i]` entry) \
                 OR at the per-role scalar constant that `head` \
                 re-exports — the choice depends on whether the drift \
                 is an unintended slot reorder inside the array or a \
                 rename of the canonical projection byte upstream."
            );
        }
        i += 1;
    }
    let mut j = K;
    while j < N {
        if !str_bytes_equal(arr[j], tail) {
            panic!(
                "assert_str_array_is_concatenation_of_two_scalar_replicas: \
                 TAIL-SEGMENT-BLOCK-CONSTANCY-VIOLATION — the family-\
                 wide `&'static str` array `arr` carries an entry at \
                 some position in `[K, N)` (the TAIL segment) that \
                 does NOT byte-for-byte equal the peer `tail` scalar. \
                 The substrate's TAIL-SEGMENT BLOCK-CONSTANCY \
                 contract on the array is broken; every consumer that \
                 reads `arr[K..N)` and the peer `tail` scalar as \
                 INTERCHANGEABLE (any MANY-TO-ONE variant → \
                 canonical-projection consumer expecting the last \
                 `N - K` variant slots to share ONE canonical \
                 projection byte — e.g. the `zip(Self::ALL, \
                 Self::OPERATIONS)` compound-key `\"{{operation}}: \
                 {{stage}}\"` surface consumers on \
                 `crate::error::CompilerSpecIoStage::OPERATIONS` whose \
                 last two slots project through \
                 `crate::error::CompilerSpecIoStage::LOAD_FROM_DISK_\
                 OPERATION`) relies on this invariant. Fix at the \
                 ARRAY-DECLARATION site (the drifted `arr[j]` entry) \
                 OR at the per-role scalar constant that `tail` \
                 re-exports — the choice depends on whether the drift \
                 is an unintended slot reorder inside the array or a \
                 rename of the canonical projection byte upstream."
            );
        }
        j += 1;
    }
}

/// Compile-time contract verifier — panics at const evaluation time if
/// the sub-slice `full[START..START + M)` does NOT byte-equal the peer
/// sub-array `sub[..]` positionwise (`&'static str`-by-`&'static str`).
///
/// Row-dual peer of [`assert_u8_array_slice_equals_u8_array`] and
/// [`assert_char_array_slice_equals_char_array`] on the (element-type)
/// axis: where the `u8` sibling closes the outer-`Sexp` cache-key
/// discriminator sub-carving vocabulary at compile time AND the `char`
/// sibling closes the substrate's reader-boundary `[char; N]` scalar-
/// composed vocabulary at compile time, this closes the substrate's
/// family-wide `[&'static str; N]` label / prefix / tag / literal
/// vocabulary at compile time. Opens the SUB-SLICE ARRAY-image column
/// on the (str) row of the (element-type × contract-shape) matrix peer
/// to the u8-row + char-row siblings' SUB-SLICE ARRAY-image column —
/// the three helpers together lift EVERY positionwise-composition
/// contract `arr[START..START + M) == sub[..]` on scalar-family-wide
/// substrate arrays into a COMPILE-TIME theorem, one per element-type
/// row of the matrix.
///
/// The MIDDLE-SLICE corner (`0 < START`, `START + M < N`) — the shape
/// the (str) row uniquely exercises against the substrate's twelve-arm
/// [`crate::error::SexpShape::LABELS`] vocabulary — pins that each
/// sub-carving's LABELS array occupies its CANONICAL SLOTS on the
/// parent superset's declaration order, one invocation stage stronger
/// than the pre-existing SET-level DISJOINT-UNION witnesses (three
/// `assert_str_array_within_str_finite_set::<sub, 12>` embeddings,
/// three `assert_str_arrays_disjoint::<a, b>` pairwise-disjointness
/// witnesses, one `assert_str_finite_set_covered_by_three_str_arrays::
/// <6, 4, 2, 12>` coverage witness, one `assert_str_array_pairwise_
/// distinct(&SexpShape::LABELS)` INJECTIVITY witness). The SET-level
/// 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
/// `[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)` — the CANONICAL positional decomposition) 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. THIS helper binds each sub-slice's positionwise composition
/// against its sub-vocabulary's canonical array at rustc time —
/// strictly STRONGER on the (contract-strength) axis than the sibling
/// SET-level DISJOINT-UNION witnesses.
///
/// Consumer sites this helper closes at the MIDDLE-SLICE corner:
/// * [`crate::error::SexpShape::LABELS`] `[0..1) ==
///   [crate::error::StructuralKind::NIL_LABEL]` — the singleton left-
///   endpoint slot of the outer twelve-shape LABELS array binds the
///   structural-residual carving's NIL role at the CANONICAL slot `0`.
/// * [`crate::error::SexpShape::LABELS`] `[1..7) == AtomKind::LABELS` —
///   the six-slot atomic-payload middle slice binds the six atomic
///   variants' LABELS at the CANONICAL slots `[1..7)`, one invocation
///   stage stronger than the (u8)-row peer at the SAME slice range
///   `[1..7)` where the six slots collapse to a single scalar
///   [`AtomKind::OUTER_HASH_DISCRIMINATOR`] byte (`1u8`) — the (str)
///   row's per-slot LABELS listing distinguishes ALL SIX slots
///   individually, so a permutation of the six atomic arms inside the
///   parent's `[1..7)` slice fails HERE where the (u8)-row's SCALAR-
///   REPLICA sibling stays silent.
/// * [`crate::error::SexpShape::LABELS`] `[7..8) ==
///   [crate::error::StructuralKind::LIST_LABEL]` — the singleton mirror-
///   endpoint slot at the atomic-collapse right endpoint binds the
///   structural-residual carving's LIST role at the CANONICAL slot `7`.
/// * [`crate::error::SexpShape::LABELS`] `[8..12) == QuoteForm::LABELS`
///   — the four-slot quote-family tail slice binds the four quote-
///   family variants' LABELS at the CANONICAL slots `[8..12)`, peer to
///   the (u8)-row's `assert_u8_array_slice_equals_u8_array::<12, 4, 8>
///   (&SexpShape::HASH_DISCRIMINATORS, &QuoteForm::HASH_DISCRIMINATORS)`
///   witness.
///
/// Together the FOUR positional witnesses cover the ENTIRE twelve-slot
/// outer container's per-position LABEL sequence at rustc time — the
/// UNION of the four disjoint slice ranges `[0..1) ∪ [1..7) ∪ [7..8) ∪
/// [8..12)` exhausts the twelve-slot outer container's position space.
/// Sibling posture to the (u8)-row's FOUR positional witnesses on
/// `SexpShape::HASH_DISCRIMINATORS` (the two singleton
/// slice-equals-array witnesses on `[0..1)` and `[7..8)`, the six-slot
/// slice-is-scalar-replica witness on `[1..7)`, the four-slot
/// slice-equals-array witness on `[8..12)`) — both rows now carry the
/// FULL positional decomposition of the twelve-slot outer container at
/// rustc time on BOTH the (u8) discriminator axis AND the (str) label
/// axis. A regression that reordered `SexpShape::LABELS` fails at BOTH
/// the (u8)-row `HASH_DISCRIMINATORS` positional witnesses (through
/// the parallel outer twelve-slot ordering) AND the (str)-row LABELS
/// positional witnesses lifted here.
///
/// Pre-lift the twelve-arm `SexpShape::LABELS` positional decomposition
/// lived ONLY through the runtime cross-check
/// `sexp_shape_labels_align_with_sub_vocabularies_by_position` (in
/// `error.rs`, sweeping the twelve positions and routing each
/// `SexpShape::LABELS[i]` through its sub-vocabulary via
/// `SexpShape::ALL[i].as_atom_kind() / .as_quote_form()` composition);
/// post-lift the ARRAY-LEVEL positional decomposition binds at rustc
/// time via FOUR `const _` lines, one invocation stage earlier than
/// the runtime pin. A regression that reorders the outer
/// `SexpShape::LABELS` array's initializer (e.g. swapping slot `0`'s
/// `Self::NIL_LABEL` with slot `1`'s `Self::SYMBOL_LABEL`) while
/// leaving each sub-vocabulary in its canonical order fails at
/// `cargo check` BEFORE any test scheduler runs.
///
/// The three axis-partitioned panic messages (`START-OUT-OF-BOUNDS`,
/// `SLICE-LENGTH-OUT-OF-BOUNDS`, `STR-SLICE-EQUALS-ARRAY-VIOLATION`)
/// mirror the u8 sibling's message vocabulary with the `STR-` prefix
/// on the CONTENT-drift axis so callers grep either the (u8) row's
/// plain `SLICE-EQUALS-ARRAY-VIOLATION`, the (char) row's
/// `CHAR-SLICE-EQUALS-ARRAY-VIOLATION`, or the (str) row's
/// `STR-SLICE-EQUALS-ARRAY-VIOLATION` axis-prefix by element-type. The
/// shared `-SLICE-EQUALS-ARRAY-VIOLATION` infix lets callers grep any
/// element-type variant by the shared axis substring.
///
/// Adding a new family-wide `[&'static str; N]` array to the substrate
/// whose declaration is a positionwise composition against named per-
/// role `pub const *_LABEL` / `*_PREFIX` / `*_TAG` `&'static str`
/// constants: pair the declaration with `const _: () =
/// assert_str_array_slice_equals_str_array::<N, M, START>(&Self::FOO_
/// ARRAY, &Self::SUB_ARRAY);` co-located after the array's declaration
/// and the per-slot ORDER contract binds at compile time. The rustc-
/// forced arities `[&'static str; N]` + `[&'static str; M]` compose
/// with this const-eval sweep so BOTH cardinality AND per-slot
/// canonical-str-value are compile-time theorems on the SAME array.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — e.g. a REPL / LSP surface
/// that constructs a `[&'static str; N]` at runtime from a user-
/// supplied vocabulary and wants to verify positionwise composition
/// against a peer sub-array before consuming it — and the panic
/// surfaces normally in that path (pinned by
/// `assert_str_array_slice_equals_str_array_panics_at_runtime_on_positionwise_drift`,
/// `assert_str_array_slice_equals_str_array_panics_at_runtime_on_start_out_of_bounds`,
/// `assert_str_array_slice_equals_str_array_panics_at_runtime_on_slice_length_out_of_bounds`,
/// AND
/// `assert_str_array_slice_equals_str_array_panic_message_names_the_helper_and_str_slice_equals_array_violation_axis`).
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the family-wide per-position
///   ORDER contract on the `&'static str`-typed vocabulary becomes a
///   TYPE-LEVEL theorem the substrate carries per array declaration
///   rather than a runtime iterator sweep the developer must remember
///   to write per array.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   positionwise sweep IS the generative shape. Every new closed-set
///   string array declared as a positionwise composition against
///   named-per-role `pub const` labels adds ONE `const _` line to get
///   the per-slot ORDER theorem rather than re-deriving a runtime
///   index-by-index `assert_eq!` block per array.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs; the
///   per-slot-ORDER proof at declaration site AND the per-role
///   `pub const *_LABEL` alias-chain composition every consumer relies
///   on regenerate through the SAME `const _` witness.
pub const fn assert_str_array_slice_equals_str_array<
    const N: usize,
    const M: usize,
    const START: usize,
>(
    full: &[&'static str; N],
    sub: &[&'static str; M],
) {
    if START > N {
        panic!(
            "assert_str_array_slice_equals_str_array: START-OUT-OF-\
             BOUNDS — the const parameter `START` sits OUTSIDE the \
             outer array's valid position range `[0..N]` (inclusive \
             upper bound: `START == N` combined with `M == 0` is the \
             LEGAL empty-slice-at-right-endpoint corner). Fix at the \
             `const _` witness's turbofish by reconciling `START` \
             against the outer array's declared arity `N`. The \
             START-OUT-OF-BOUNDS gate fires FIRST — a mistyped \
             `START` on the caller side fails HERE before the peer \
             `SLICE-LENGTH-OUT-OF-BOUNDS` gate reads `N - START` \
             (which would underflow `usize` had this gate not caught \
             the slip), so a subtle bounds slip doesn't silently \
             degenerate into a subtraction wrap-around OR a panic \
             deeper in `full[START + i]` bounds-checking."
        );
    }
    if M > N - START {
        panic!(
            "assert_str_array_slice_equals_str_array: SLICE-LENGTH-\
             OUT-OF-BOUNDS — the peer sub-array's arity `M` exceeds \
             the outer array's tail cardinality `N - START`, so the \
             positionwise sweep `full[START + i]` for `i ∈ [0..M)` \
             would overrun the outer array's valid position range \
             `[0..N)` at some `i ∈ [N - START..M)`. Fix at the \
             `const _` witness's turbofish by reconciling `M` against \
             the outer array's tail cardinality `N - START` OR by \
             narrowing `START` to leave a longer tail. The peer \
             `START-OUT-OF-BOUNDS` gate above guarantees `START ≤ N` \
             so `N - START` never underflows `usize` at this gate. \
             The LEGAL exact-fit corner `M == N - START` (the sub-\
             array reaches EXACTLY to the outer array's right \
             endpoint) is accepted; the STRICT `M > N - START` slip \
             is what this gate rejects."
        );
    }
    let mut i = 0;
    while i < M {
        if !str_bytes_equal(full[START + i], sub[i]) {
            panic!(
                "assert_str_array_slice_equals_str_array: STR-SLICE-\
                 EQUALS-ARRAY-VIOLATION — the outer `[&'static str; \
                 N]` array `full` carries a str at some position \
                 `START + i` (for `i ∈ [0..M)`) that does NOT byte-\
                 equal the peer `[&'static str; M]` sub-array `sub` \
                 at the offset-matched position `i`. The substrate's \
                 SLICE-EQUALS-ARRAY positionwise-composition contract \
                 on the sub-slice `full[START..START + M) == sub[..]` \
                 is broken; every consumer that reads `full[START..\
                 START + M)` as a positionwise-aligned copy of a peer \
                 sub-vocabulary's canonical `[&'static str; M]` \
                 listing (the twelve-slot outer container \
                 `crate::error::SexpShape::LABELS` whose four \
                 canonical sub-slices `[0..1) == \
                 [crate::error::StructuralKind::NIL_LABEL]`, `[1..7) \
                 == AtomKind::LABELS`, `[7..8) == [crate::error::\
                 StructuralKind::LIST_LABEL]`, `[8..12) == \
                 QuoteForm::LABELS` compose the parent LABELS \
                 vocabulary from the three sub-carvings' LABELS \
                 arrays; any future container-array sub-slice byte-\
                 for-byte equal to a peer sub-carving's canonical \
                 `[&'static str; M]` listing) relies on this \
                 invariant. Fix at the ARRAY-DECLARATION site (the \
                 drifted `full[START + i]` entry inside the slice \
                 segment) OR at the peer sub-array's arm listing — \
                 the choice depends on whether the drift is an \
                 unintended slot reorder in the outer array's tail \
                 OR in the sub-carving's own listing."
            );
        }
        i += 1;
    }
}

/// Compile-time contract verifier — panics at const evaluation time if
/// any two entries of `arr` alias byte-for-byte.
///
/// Column-dual peer to [`assert_char_array_pairwise_distinct`] and
/// [`assert_str_array_pairwise_distinct`] on the (element-type) axis:
/// where the `char` sibling closes the reader-boundary `[char; N]`
/// vocabulary at compile time and the `&'static str` sibling closes
/// the outer-algebras' family-wide label / prefix / tag / literal
/// vocabularies, this closes the substrate's family-wide `[u8; N]`
/// cache-key discriminator vocabulary. The three helpers together
/// lift EVERY `pub const` scalar-family-wide array declared on the
/// substrate's closed-set outer algebras (`Sexp` / `Atom` /
/// `AtomKind` / `QuoteForm` / `StructuralKind` / `UnquoteForm`) into
/// a COMPILE-TIME pairwise-distinctness theorem — a regression that
/// silently collides two entries fails the build at `cargo check`
/// time, one invocation stage earlier than the test-run pin.
///
/// The invariant is load-bearing for the outer-`Sexp` cache-key
/// algebra: every consumer that pattern-matches the array's entries
/// as DISJOINT arms of a hash-discriminator projection —
/// [`AtomKind::hash_discriminator`]'s six-arm `{0..=5}` byte partition
/// under [`Hash for Atom`](crate::ast::Atom); [`QuoteForm::hash_discriminator`]'s
/// four-arm `{3, 4, 5, 6}` byte partition under
/// [`Hash for Sexp`](crate::ast::Sexp); [`crate::error::StructuralKind::hash_discriminator`]'s
/// two-arm `{0, 2}` byte partition under the outer-`Sexp` cache-key
/// algebra's structural-residual carve; AND
/// [`crate::error::UnquoteForm::hash_discriminator`]'s two-arm byte
/// partition on the substitution-subset carving — relies on this
/// invariant. A duplicate here would silently collide two DISTINCT
/// variants at the SAME cache-key byte, breaking the `Expander::cache`
/// keying on `(macro_name, args)` hash and mis-hashing every cached
/// expansion across the collided variants.
///
/// Pre-lift each of these four arrays carried its pairwise-
/// distinctness contract at a runtime test
/// (`atom_kind_hash_discriminators_pairwise_distinct`,
/// `quote_form_hash_discriminators_pairwise_distinct`,
/// `structural_kind_hash_discriminators_pairwise_distinct`,
/// `unquote_form_hash_discriminators_pairwise_distinct`); post-lift
/// the pairwise-distinctness contract binds at `cargo check` time,
/// one invocation stage earlier, catching regressions on `cargo
/// build` / `cargo clippy` runs that skip the test suite.
///
/// NB: [`crate::error::SexpShape::HASH_DISCRIMINATORS`] (`[u8; 12]`)
/// is INTENTIONALLY excluded from this compile-time sweep — the
/// twelve outer shapes DELIBERATELY collapse onto only SEVEN outer
/// cache-key bytes `{0..=6}` (the six atomic shapes all map to `1`
/// per the outer-Sexp `Atom` marker byte, per the collapse rule
/// documented on [`AtomKind::OUTER_HASH_DISCRIMINATOR`]). A
/// pairwise-distinctness pin there would fire correctly, matching
/// the load-bearing non-injectivity that closes the twelve-arm
/// shape space onto the seven-arm outer-Sexp cache-key space.
///
/// Adding a new family-wide `[u8; N]` array to the substrate: pair
/// the declaration with `const _: () = assert_u8_array_pairwise_
/// distinct(&Self::FOO_ARRAY);` co-located after the array's
/// declaration and the distinctness contract is enforced at
/// compile time. The rustc-forced arity `[u8; N]` composes with
/// this const-eval sweep so BOTH cardinality AND injectivity are
/// compile-time theorems on the SAME array.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — pinned by
/// `assert_u8_array_pairwise_distinct_panics_at_runtime_on_binary_
/// collision`. Unlike [`assert_str_array_pairwise_distinct`] this
/// helper needs no auxiliary byte-equality helper: `u8` supports
/// `==` directly in const-fn context, collapsing the triangular
/// pair sweep to a two-loop shape without an inner byte walk.
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the family-wide
///   distinctness contract on the `u8` cache-key vocabulary becomes
///   a TYPE-LEVEL theorem the substrate carries per array
///   declaration rather than a runtime test the developer must
///   remember to write per array.
/// - THEORY.md §V.3 — three-pillar attestation; the outer-`Sexp`
///   cache-key partition is the `intent_hash` composition axis —
///   binding the discriminator arrays on the typed algebra makes
///   attestation-key drift a compile error rather than a silent
///   BLAKE3 mis-hash on any consumer keyed on `Hash for Sexp`.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   sweep IS the generative shape. Every new closed-set
///   discriminator array adds ONE `const _` line to get the
///   distinctness theorem rather than re-deriving a per-array
///   runtime iterator sweep.
pub const fn assert_u8_array_pairwise_distinct<const N: usize>(arr: &[u8; N]) {
    let mut i = 0;
    while i < N {
        let mut j = i + 1;
        while j < N {
            if arr[i] == arr[j] {
                panic!(
                    "assert_u8_array_pairwise_distinct: family-wide \
                     u8 array carries a duplicate entry across two \
                     positions — the substrate's pairwise-\
                     distinctness contract on the array is broken; \
                     every consumer that pattern-matches the array's \
                     entries as DISJOINT arms (Atom / Sexp cache-key \
                     hash-discriminator projection, structural-\
                     residual / quote-family / substitution-subset \
                     byte partition) relies on this invariant",
                );
            }
            j += 1;
        }
        i += 1;
    }
}

// Compile-time pairwise-distinctness on family-wide `[u8; N]` hash-
// discriminator arrays no longer surfaces at this level as DIRECT
// witnesses — every family-wide `[u8; N]` HASH_DISCRIMINATORS array
// whose INJECTIVITY contract binds now does so through ONE of the two
// stronger COMPOUND (INJECTIVITY ∧ SURJECTIVITY ∧ ARITY) permutation
// helpers defined below (`assert_u8_array_permutes_inclusive_range` on
// the CONTIGUOUS-INCLUSIVE-RANGE corner of the (contiguity) axis at
// `AtomKind::HASH_DISCRIMINATORS` / `QuoteForm::HASH_DISCRIMINATORS` /
// `UnquoteForm::HASH_DISCRIMINATORS`; `assert_u8_array_permutes_
// finite_set` on the NON-CONTIGUOUS-FINITE-SET corner at
// `StructuralKind::HASH_DISCRIMINATORS`), each of which delegates
// through this pairwise-distinct helper for the INJECTIVITY arm — the
// helper is now purely a delegation target. `SexpShape::HASH_
// DISCRIMINATORS` is intentionally OMITTED from BOTH compound helpers
// per the intentionally-non-injective twelve-shape → seven-byte
// collapse rule documented on the helper above — INJECTIVITY does not
// hold, so no permutation contract can bind on any contiguity corner
// (its SURJECTIVITY-only contract binds through the single-axis
// `assert_u8_array_covers_inclusive_range` sibling further below).
//
// Adding a new family-wide `[u8; N]` permutation-shaped HASH_
// DISCRIMINATORS array: prefer the compound helpers below
// (`_permutes_inclusive_range` for the contiguous-range corner or
// `_permutes_finite_set` for the non-contiguous-finite-set corner)
// which bind INJECTIVITY ∧ SURJECTIVITY ∧ ARITY at ONE `const _` line;
// fall back to a DIRECT `const _: () = assert_u8_array_pairwise_
// distinct(&Self::FOO_ARRAY);` witness at this level ONLY for an array
// that is intentionally injective but whose distinct-value set is
// NEITHER a contiguous inclusive range NOR a known finite set (a
// hypothetical looser-contract case not currently exercised by any
// substrate array). Sibling to the runtime `_hash_discriminators_
// pairwise_distinct` tests at `ast.rs` + `error.rs`'s tests modules —
// those enforce the same theorem at `cargo test` time through direct
// runtime calls to this helper, so the theorem is still bound at
// TWO stages of the toolchain (compile time through the delegated
// path inside the compound helpers, test time through the direct
// runtime calls). Peer to the seven `assert_char_array_pairwise_
// distinct` witnesses AND the thirteen `assert_str_array_pairwise_
// distinct` witnesses above on the (element-type) axis: `char`
// covers the reader-boundary vocabulary; `&'static str` covers the
// closed-set outer-algebras' label / prefix / tag / literal
// vocabularies; `u8` (via the compound helpers below) covers the
// outer-`Sexp` cache-key discriminator vocabulary.

/// Compile-time contract verifier — panics at const evaluation time if
/// any two entries of `arr` share their LEFT `char` column OR their
/// RIGHT `char` column, i.e. binds the `[(char, char); N]` array as a
/// BIJECTION on the substrate's escape-table product-vocabulary.
///
/// Product-element sibling to the scalar-element trio
/// ([`assert_char_array_pairwise_distinct`],
/// [`assert_str_array_pairwise_distinct`], and
/// [`assert_u8_array_pairwise_distinct`]) on the (element-type) axis:
/// where the three scalar-element helpers close every family-wide
/// SINGLE-column array declared on the substrate's closed-set outer
/// algebras (`Sexp` / `Atom` / `AtomKind` / `QuoteForm` /
/// `StructuralKind` / `UnquoteForm` on the reader-boundary + label +
/// prefix + tag + cache-key vocabularies), this closes the substrate's
/// family-wide TWO-column `[(char, char); N]` bijection tables at
/// compile time. A `[(char, char); N]` array is a bijection iff BOTH
/// column projections are pairwise-distinct (LEFT-column injectivity
/// witnesses that `source → decoded` is a well-defined function on
/// distinct sources; RIGHT-column injectivity witnesses that
/// `decoded → source` inverts unambiguously) — since |LEFT| = |RIGHT| =
/// N is finite, the conjunction of the two injectivities IS bijectivity
/// on the paired substrate vocabulary.
///
/// The invariant is load-bearing for the Str-payload escape-table
/// tokenization boundary. [`Atom::NAMED_ESCAPE_TABLE`] (`[(char, char);
/// 3]`, the three pattern-DISTINCT-from-value named-escape rows —
/// `'n' → '\n'`, `'t' → '\t'`, `'r' → '\r'`) is the paired algebra
/// [`Atom::decode_str_escape`]'s three named arms dispatch through; a
/// LEFT-column collision would silently route two escape sequences
/// through the first-matching decoded byte (e.g. a drift of
/// `TAB_ESCAPE_SOURCE` to `'n'` would collapse `\t` and `\n` at the
/// same source arm), and a RIGHT-column collision would collapse two
/// distinct decoded bytes onto ONE (e.g. a drift of `TAB_ESCAPE_DECODED`
/// to `'\n'` would emit `\n` on BOTH `\t` and `\n` in the tokenized
/// payload). [`Atom::ESCAPE_TABLE`] (`[(char, char); 5]`, the
/// composite paired SPAN over the three named + two self-escape rows)
/// binds the SAME bijection at the composite level; a LEFT-column
/// collision AT THE COMPOSITE would witness cross-sub-vocabulary
/// aliasing (a named-escape source colliding with a self-escape
/// source, e.g. `'n'` = `Self::STR_DELIMITER`), and a RIGHT-column
/// collision would witness the same at the DECODED axis. Every future
/// family-wide `[(char, char); N]` paired substrate array participates
/// in the SAME compile-time guarantee via one `const _` line.
///
/// Pre-lift each of these two bijection tables carried its
/// column-wise pairwise-distinctness contract at TWO runtime tests
/// (`atom_named_escape_table_sources_pairwise_distinct` +
/// `atom_named_escape_table_decoded_pairwise_distinct` on the
/// NAMED_ESCAPE_TABLE arm; the composite `atom_escape_table_
/// sources_and_decoded_columns_pairwise_distinct` on the ESCAPE_TABLE
/// arm); post-lift the CONJOINED bijectivity contract binds at `cargo
/// check` time — the const-eval panic surfaces the collision at
/// COMPILE time, one invocation stage earlier, catching regressions
/// on `cargo build` / `cargo clippy` runs that skip the test suite.
///
/// Adding a new family-wide `[(char, char); N]` paired array to the
/// substrate: pair the declaration with `const _: () =
/// assert_char_pair_array_bijective(&Self::FOO_TABLE);` co-located
/// after the declaration and the BIJECTION contract binds at compile
/// time. The rustc-forced arity `[(char, char); N]` composes with this
/// const-eval sweep so cardinality AND left-column injectivity AND
/// right-column injectivity are ALL compile-time theorems on the SAME
/// array.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — e.g. a REPL / LSP tokenizer
/// that constructs a `[(char, char); N]` at runtime and wants to
/// verify bijectivity before consuming it — and the two panic sites
/// (LEFT-column collision, RIGHT-column collision) surface normally in
/// that path with column-provenance-preserving panic messages
/// (pinned by
/// `assert_char_pair_array_bijective_panics_at_runtime_on_left_
/// column_collision` +
/// `assert_char_pair_array_bijective_panics_at_runtime_on_right_
/// column_collision`).
///
/// Column-provenance in the panic message is load-bearing: downstream
/// diagnostics (`cargo check` const-eval error output, test-suite
/// failure reports) route the drift back to the failed COLUMN (LEFT
/// source vs. RIGHT decoded) by string search — a bijection failure
/// on a `[(char, char); N]` table names WHICH column collapsed,
/// halving the search space for the operator debugging the drift.
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the family-wide bijectivity
///   contract on the `(char, char)` paired escape-table vocabulary
///   becomes a TYPE-LEVEL theorem the substrate carries per paired-
///   array declaration rather than a two-runtime-test pair the
///   developer must remember to write per array (one per column).
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs; the
///   bijection proof at declaration site AND the outer-dispatch
///   match-arm exhaustiveness at [`Atom::decode_str_escape`]'s five
///   arms regenerate through the SAME `const _` witness.
/// - THEORY.md §VI.1 — generation over composition; the two-column
///   const-eval sweep IS the generative shape. Every new closed-set
///   paired-array vocabulary adds ONE `const _` line to get the
///   bijection theorem rather than re-deriving TWO per-column
///   iterator sweeps at runtime.
pub const fn assert_char_pair_array_bijective<const N: usize>(arr: &[(char, char); N]) {
    let mut i = 0;
    while i < N {
        let mut j = i + 1;
        while j < N {
            if arr[i].0 as u32 == arr[j].0 as u32 {
                panic!(
                    "assert_char_pair_array_bijective: LEFT column of \
                     family-wide `[(char, char); N]` paired substrate \
                     array carries a duplicate SOURCE char across two \
                     positions — the substrate's LEFT-column pairwise-\
                     distinctness contract (source-column injectivity, \
                     i.e. `source → decoded` is a well-defined \
                     function on distinct sources) is broken; every \
                     consumer that pattern-matches the array's SOURCE \
                     column as DISJOINT arms (Atom::decode_str_escape \
                     escape-source outer dispatch, ESCAPE_SOURCES \
                     column-dual SPAN projection) relies on this \
                     invariant"
                );
            }
            if arr[i].1 as u32 == arr[j].1 as u32 {
                panic!(
                    "assert_char_pair_array_bijective: RIGHT column of \
                     family-wide `[(char, char); N]` paired substrate \
                     array carries a duplicate DECODED char across two \
                     positions — the substrate's RIGHT-column \
                     pairwise-distinctness contract (decoded-column \
                     injectivity, i.e. `source → decoded` inverts \
                     unambiguously through `decoded → source` on the \
                     finite paired vocabulary) is broken; every \
                     consumer that enumerates the array's DECODED \
                     column as a disjoint alphabet (ESCAPE_DECODED \
                     column-dual SPAN projection, escape-family \
                     decoded-byte enumeration) relies on this \
                     invariant"
                );
            }
            j += 1;
        }
        i += 1;
    }
}

// Compile-time bijectivity witnesses — one `const _: () =
// assert_char_pair_array_bijective(&…)` per family-wide `[(char, char);
// N]` paired escape-table array on the substrate's Str-payload
// tokenization boundary. Each invocation is const-evaluated at `cargo
// check` time; a regression that silently collided two entries at
// EITHER the LEFT source column OR the RIGHT decoded column fails the
// build rather than the test suite. Sibling to the runtime
// `_pairwise_distinct` tests at `ast::tests` (`atom_named_escape_
// table_sources_pairwise_distinct`, `atom_named_escape_table_decoded_
// pairwise_distinct`, `atom_escape_table_sources_and_decoded_columns_
// pairwise_distinct`) — the two enforce the same theorem at TWO
// stages of the toolchain, so a build that skips tests still catches
// the regression here, and a build that runs tests catches it a
// second time as a safety net if the const-eval sweep is ever
// silently dropped. Peer to the seven `assert_char_array_pairwise_
// distinct` + thirteen `assert_str_array_pairwise_distinct` + four
// `assert_u8_array_pairwise_distinct` witnesses above on the
// (element-type) axis: the three scalar-element helpers close every
// family-wide SINGLE-column array; this product-element helper closes
// the family-wide TWO-column paired escape-table arrays.
const _: () = assert_char_pair_array_bijective(&Atom::NAMED_ESCAPE_TABLE);
const _: () = assert_char_pair_array_bijective(&Atom::ESCAPE_TABLE);

/// Compile-time contract verifier — panics at const evaluation time if
/// the family-wide `[(char, char); N]` paired substrate array `arr`
/// carries a pair at some position whose `(SOURCE, DECODED)` tuple is
/// NOT a member of the target finite superset paired-array partition
/// `set`. Binds ONE conjunct clause on the `(char, char)` product-
/// element row of the (element-type × contract-shape) matrix at the
/// (subset-embedding) column — CHAR-PAIR-SUBSET-VIOLATION — every
/// entry of `arr` MUST be a byte-for-byte-equal `(char, char)` pair
/// found somewhere in `set` (ORIENTED across the two arguments — the
/// SUBSET side `arr` vs the SUPERSET side `set`). Pair equality is
/// CONJOINED across BOTH columns: `arr[i] == set[j]` iff `arr[i].0 ==
/// set[j].0 AND arr[i].1 == set[j].1` — a per-column membership check
/// on either column alone would silently accept a pair whose LEFT
/// column matches ONE set entry and RIGHT column matches a DIFFERENT
/// set entry (a cross-row aliasing collision the CONJOINED-pair
/// contract catches).
///
/// Delegates target-set well-formedness to the sibling
/// [`assert_char_pair_array_bijective`] helper FIRST (peer to the
/// (char, u8, `&'static str`) scalar rows' delegation to the SCALAR
/// pairwise-distinct sibling — the well-formedness delegation lifts
/// TO THE `(char, char)` row through the strongest well-formedness
/// contract on the row, which is BIJECTIVITY on the paired array). A
/// malformed `set` (e.g. `[('a', 'x'), ('a', 'y')]` — LEFT-column
/// collision, or `[('a', 'x'), ('b', 'x')]` — RIGHT-column collision)
/// routes to the SET-side BIJECTIVITY panic (via the sibling's own
/// panic-name prefix) BEFORE the CHAR-PAIR-SUBSET-VIOLATION sweep
/// silently mis-verifies against the distinct-value bijective subset.
/// A well-formed `set` passes this arm as a no-op — the sweep is
/// const-eval-elidable and costs zero at rustc-time on the substrate
/// call sites.
///
/// The substrate binds the paired-array SUBSET theorem at ONE
/// intentionally-closed `(char, char)` sub-vocabulary pair: [`Atom::
/// NAMED_ESCAPE_TABLE`] (`[(char, char); 3]`, the three pattern-
/// DISTINCT-from-value named-escape rows — `'n' → '\n'`, `'t' → '\t'`,
/// `'r' → '\r'`) ⊂ [`Atom::ESCAPE_TABLE`] (`[(char, char); 5]`, the
/// composite paired SPAN over the three named + two self-escape rows).
/// Pre-lift the SUBSET relation lived only implicitly at the composite
/// array's declaration site (`Self::NAMED_ESCAPE_TABLE[0]`,
/// `Self::NAMED_ESCAPE_TABLE[1]`, `Self::NAMED_ESCAPE_TABLE[2]`
/// indexing into the composite's first three positions); post-lift
/// the ARRAY-LEVEL subset embedding binds at rustc time via ONE
/// `const _` line. A regression that silently re-inlined either the
/// SUBSET or the SUPERSET side of the relation to a fresh pair
/// breaking the subset containment (e.g. dropping `NEWLINE` from
/// `NAMED_ESCAPE_TABLE` while keeping it as a `Self::NAMED_ESCAPE_
/// TABLE[0]` index in `ESCAPE_TABLE`; drifting `Self::TAB_ESCAPE_
/// SOURCE` on the NAMED side to a fresh char not present at the
/// composite's second position; re-shuffling the composite's first
/// three positions to swap with the SELF-escape suffix bytes) fails
/// at `cargo check` BEFORE any test scheduler runs.
///
/// Row-dual peer to
/// [`assert_char_array_within_char_finite_set`] +
/// [`assert_u8_array_within_u8_finite_set`] +
/// [`assert_str_array_within_str_finite_set`] on the (element-type)
/// axis of the SAME (subset-embedding) contract-shape column: where
/// the three sibling helpers close the SCALAR (`char`, `u8`,
/// `&'static str`) rows at ONE peer helper per row, this helper
/// opens the PRODUCT-ELEMENT `(char, char)` row on the same column
/// — extending the (element-type × contract-shape) matrix's
/// (subset-embedding) column past the three scalar rows onto the
/// paired-array row.
///
/// Contract-orthogonal peer to
/// [`assert_char_pair_array_bijective`] on the (BIJECTIVITY,
/// SUBSET-EMBEDDING) axis of the (contract-shape) column on the SAME
/// `(char, char)` row: where the BIJECTIVITY sibling binds
/// (LEFT-column INJECTIVITY ∧ RIGHT-column INJECTIVITY) on the SAME
/// array, this SUBSET-EMBEDDING sibling binds (CONJOINED-pair
/// membership) across TWO arrays. Together the two helpers close the
/// (paired-array well-formedness, paired-array subset) 2-corner face
/// on the `(char, char)` row.
///
/// Panic message carries the axis-provenance-named
/// `"CHAR-PAIR-SUBSET-VIOLATION"` string chosen DISTINCT from every
/// sibling helper's axis vocabulary (`"CHAR-SUBSET-VIOLATION"` on the
/// (char) scalar row-dual SUBSET peer; `"SUBSET-VIOLATION"` on the
/// (u8) row-dual finite-set SUBSET peer; `"STR-SUBSET-VIOLATION"` on
/// the (`&'static str`) row-dual SUBSET peer; `"RANGE-SUBSET-
/// VIOLATION"` on the (u8) range SUBSET peer; `"CHAR-DISJOINTNESS-
/// VIOLATION"` / `"U8-DISJOINTNESS-VIOLATION"` / `"STR-DISJOINTNESS-
/// VIOLATION"` on the DISJOINTNESS-column row peers; `"LEFT column"`
/// / `"RIGHT column"` on the paired-array BIJECTIVITY sibling). The
/// `"CHAR-PAIR-"` prefix disambiguates from the (char) SCALAR row-
/// dual SUBSET peer; the shared `"-SUBSET-VIOLATION"` suffix lets
/// callers grep any row's SUBSET-embedding sibling by the shared
/// suffix alone.
///
/// Adding a new family-wide `[(char, char); N]` paired-array
/// intentionally-closed SUBSET carving of another substrate
/// `[(char, char); M]` paired array to the substrate: pair the
/// declaration with `const _: () =
/// assert_char_pair_array_within_char_pair_finite_set::<N, M>(
/// &Self::FOO_SUB_TABLE, &Self::FOO_SUPER_TABLE);` co-located after
/// the SUBSET-side declaration and the paired-array SUBSET-embedding
/// contract binds at compile time. The rustc-forced arity
/// `[(char, char); N] × [(char, char); M]` composes with this const-
/// eval sweep so cardinality AND SUBSET-embedding are BOTH compile-
/// time theorems on the SAME pair.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — pinned by
/// `assert_char_pair_array_within_char_pair_finite_set_panics_at_
/// runtime_on_out_of_set_entry` +
/// `assert_char_pair_array_within_char_pair_finite_set_panic_message_
/// names_the_helper_and_char_pair_subset_violation_axis`.
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the family-wide paired-array
///   SUBSET-embedding contract on `(char, char)` sub-vocabularies
///   becomes a TYPE-LEVEL theorem the substrate carries per (arr,
///   set) `[(char, char); N] × [(char, char); M]` pair rather than a
///   runtime test per pair.
/// - THEORY.md §III — the typescape; the (element-type × contract-
///   shape) matrix's (SUBSET-EMBEDDING) column now carries the
///   PRODUCT-ELEMENT `(char, char)` row alongside the three scalar
///   rows at ONE peer const-fn helper per row.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs; the
///   SUBSET-EMBEDDING proof at declaration site AND the outer-
///   algebra's paired-array partition contract regenerate through
///   the SAME `const _` witness at the ARRAY level.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   CONJOINED-pair membership sweep IS the generative shape — every
///   new `(char, char)` sub-vocabulary paired array whose distinct-
///   value set is an intentionally-closed subset of another substrate
///   paired array adds ONE `const _` line.
pub const fn assert_char_pair_array_within_char_pair_finite_set<const N: usize, const M: usize>(
    arr: &[(char, char); N],
    set: &[(char, char); M],
) {
    // Delegate target-set well-formedness to the sibling paired-
    // array BIJECTIVITY helper FIRST. Placed BEFORE the CHAR-PAIR-
    // SUBSET-VIOLATION sweep below because a malformed `set` (e.g.
    // `[('a', 'x'), ('a', 'y')]` — LEFT-column collision; or
    // `[('a', 'x'), ('b', 'x')]` — RIGHT-column collision) is not a
    // well-formed finite bijective set of paired-cardinality `M` and
    // silently mis-verifies the intended SUBSET contract on any
    // `arr` embedded in the distinct-value bijective subset. Routes
    // drift on the CALLER'S TARGET-SET SPEC to the SET-side
    // well-formedness axis (via the sibling's own panic-name
    // prefix) rather than to a downstream CHAR-PAIR-SUBSET-VIOLATION
    // symptom on `arr`. A well-formed `set` passes this arm as a no-
    // op — the sweep is const-eval-elidable and costs zero at
    // rustc-time on the substrate call sites.
    assert_char_pair_array_bijective(set);
    let mut i = 0;
    while i < N {
        let mut j = 0;
        let mut found = false;
        while j < M {
            // CONJOINED-pair equality — BOTH columns must match the
            // SAME `set[j]` entry. A per-column membership check on
            // either column alone (e.g. `arr[i].0 in set.map(|p|
            // p.0)` AND separately `arr[i].1 in set.map(|p| p.1)`)
            // would silently accept a cross-row aliasing collision
            // where `arr[i].0 == set[j1].0` for some `j1` AND
            // `arr[i].1 == set[j2].1` for some DIFFERENT `j2` while
            // `arr[i]` itself is NOT in `set` (a pair the CONJOINED
            // gate rejects).
            if arr[i].0 as u32 == set[j].0 as u32 && arr[i].1 as u32 == set[j].1 as u32 {
                found = true;
                break;
            }
            j += 1;
        }
        if !found {
            panic!(
                "assert_char_pair_array_within_char_pair_finite_set: \
                 CHAR-PAIR-SUBSET-VIOLATION — the family-wide \
                 `[(char, char); N]` paired substrate array `arr` \
                 carries a pair at some position whose (SOURCE, \
                 DECODED) tuple is NOT a byte-for-byte-equal member \
                 of the target finite superset paired-array \
                 partition `set`. The substrate's paired-array \
                 SUBSET-EMBEDDING contract on `arr` is broken; every \
                 consumer that expects the paired array's distinct-\
                 value set of `(SOURCE, DECODED)` tuples to be a \
                 subset of the target finite superset paired \
                 partition (`Atom::NAMED_ESCAPE_TABLE ⊂ Atom::\
                 ESCAPE_TABLE` on the pattern-DISTINCT-from-value \
                 sub-vocabulary axis of the paired escape-arm SPAN; \
                 any future typed-paired-subset embedding on the \
                 substrate's reader-boundary `(char, char)` \
                 algebras) relies on every array pair staying within \
                 the target paired superset. Fix at the SUBSET-side \
                 ARRAY-DECLARATION site (the `arr` under \
                 verification, NOT the `set` argument specifying the \
                 target superset) by dropping the offending pair OR \
                 by extending `set` to cover it — the choice depends \
                 on whether the drift is an unintended overshoot \
                 outside the parent superset or an intentional \
                 extension of the superset paired vocabulary. The \
                 CONJOINED-pair equality gate distinguishes THIS \
                 helper from a per-column membership check that \
                 would silently accept a cross-row aliasing pair \
                 (`arr[i].0` matches ONE set entry's LEFT column \
                 while `arr[i].1` matches a DIFFERENT set entry's \
                 RIGHT column) — the CONJOINED gate rejects the \
                 pair unless BOTH columns match the SAME `set[j]`"
            );
        }
        i += 1;
    }
}

// Compile-time SUBSET-embedding witness — the ONE intentionally-
// closed `[(char, char); N] ⊂ [(char, char); M]` paired sub-
// vocabulary carving on the substrate's Str-payload tokenization
// boundary whose distinct-value set of `(SOURCE, DECODED)` tuples
// is a subset of another family-wide paired substrate array's
// distinct-value set. Pre-lift the SUBSET relation lived only
// implicitly at the composite `Atom::ESCAPE_TABLE`'s declaration
// site (`Self::NAMED_ESCAPE_TABLE[0]`, `Self::NAMED_ESCAPE_TABLE[1]`,
// `Self::NAMED_ESCAPE_TABLE[2]` indexing into the composite's first
// three positions). Post-lift the ARRAY-LEVEL subset embedding
// binds at rustc time — a regression that silently re-inlined the
// SUBSET or SUPERSET side of the relation to a fresh pair breaking
// the subset containment fails at `cargo check` BEFORE any test
// scheduler runs. Sibling to the pre-existing BIJECTIVITY witnesses
// above — those pin (LEFT-column INJECTIVITY ∧ RIGHT-column
// INJECTIVITY) on each individual paired array, this pins
// CONJOINED-pair SUBSET containment across a PAIR of paired arrays.
// Peer to the (char) + (u8) + (`&'static str`) scalar rows' SUBSET-
// embedding witnesses above on the (element-type) axis of the SAME
// (subset-embedding) contract-shape column.
const _: () = assert_char_pair_array_within_char_pair_finite_set::<3, 5>(
    &Atom::NAMED_ESCAPE_TABLE,
    &Atom::ESCAPE_TABLE,
);

/// Compile-time contract verifier — panics at const evaluation time if
/// any pair of `a` aliases any pair of `b` byte-for-byte through
/// CONJOINED-pair equality on both `(char, char)` columns.
///
/// Row-dual peer to [`assert_char_arrays_disjoint`] +
/// [`assert_u8_arrays_disjoint`] + [`assert_str_arrays_disjoint`] on the
/// (element-type) axis of the (element-type × contract-shape) matrix at
/// the (disjointness) column: where the three SCALAR (char, u8,
/// `&'static str`) siblings close the DISJOINTNESS corner at ONE peer
/// helper per scalar element type, this helper opens the PRODUCT-ELEMENT
/// `(char, char)` row on the same column — extending the
/// (element-type × contract-shape) matrix's (disjointness) column past
/// the three scalar rows onto the paired-array row. Combined with the
/// pre-existing [`assert_char_pair_array_bijective`] (INJECTIVITY axis)
/// and [`assert_char_pair_array_within_char_pair_finite_set`] (SUBSET-
/// EMBEDDING axis), the substrate now closes the (paired-array
/// well-formedness, paired-array subset, paired-array disjointness)
/// 3-corner face on the `(char, char)` row of the (element-type ×
/// contract-shape) matrix at THREE peer const-fn helpers.
///
/// Contract-orthogonal peer to
/// [`assert_char_pair_array_within_char_pair_finite_set`] on the
/// (SUBSET-EMBEDDING, DISJOINTNESS) axis of the (contract-shape) column
/// on the SAME `(char, char)` row: where the SUBSET-EMBEDDING sibling
/// binds `arr ⊆ set` (every `arr` pair IS in `set`), this DISJOINTNESS
/// sibling binds `a ∩ b = ∅` (no `a` pair is in `b`). Together the two
/// helpers close the (paired-array subset, paired-array disjointness)
/// 2-corner face on the `(char, char)` row peer to the same face on
/// each of the (char, u8, `&'static str`) SCALAR rows.
///
/// CONJOINED-pair equality gate: `a[i] == b[j]` iff `a[i].0 == b[j].0
/// AND a[i].1 == b[j].1`. A per-column disjointness check on either
/// column alone (e.g. `a[i].0 ∉ b.map(|p| p.0)` AND separately
/// `a[i].1 ∉ b.map(|p| p.1)`) would REJECT paired arrays whose columns
/// share entries INDIVIDUALLY across rows even when NO CONJOINED pair
/// aliases — a stricter contract than paired-array disjointness. The
/// CONJOINED gate here PERMITS the per-column aliasing corner as
/// disjoint (a pair `('a', 'x')` in `a` and a pair `('a', 'y')` in `b`
/// alias at the LEFT column only — the CONJOINED pairs differ so the
/// paired arrays are correctly disjoint). This is the SAME gate the
/// sibling [`assert_char_pair_array_within_char_pair_finite_set`] uses
/// on its SUBSET arm — the two helpers share ONE product-element
/// equality relation across the (SUBSET, DISJOINTNESS) axis so a
/// caller who understands the gate on ONE arm carries the intuition to
/// the other.
///
/// The invariant is load-bearing for the substrate's Str-payload
/// escape-arm dispatch at [`Atom::decode_str_escape`]: the FIVE
/// non-passthrough escape arms partition into the pattern-DISTINCT-
/// from-value [`Atom::NAMED_ESCAPE_TABLE`] (`[(char, char); 3]`,
/// `'n' → '\n'`, `'t' → '\t'`, `'r' → '\r'`) and the pattern-EQUALS-
/// value self-escape rows (`STR_DELIMITER → STR_DELIMITER`,
/// `STR_ESCAPE_LEAD → STR_ESCAPE_LEAD` — expressed as pairs
/// `[(SELF_ESCAPE_TABLE[0], SELF_ESCAPE_TABLE[0]),
/// (SELF_ESCAPE_TABLE[1], SELF_ESCAPE_TABLE[1])]` at the paired-
/// vocabulary level). The two sub-vocabularies MUST remain disjoint —
/// otherwise a NAMED escape source (`'n'` / `'t'` / `'r'`) would
/// simultaneously ALSO be a SELF-escape source, breaking the
/// two-sub-vocabulary partition of [`Atom::ESCAPE_TABLE`] and
/// silently routing an escape byte through TWO cascading arms of
/// `decode_str_escape` at the same input position (with the earlier-
/// matched arm winning arbitrarily). Post-lift the paired-array
/// DISJOINTNESS of the two sub-vocabularies binds at rustc time via
/// ONE `const _` line — a regression that silently drifted a NAMED
/// escape source to `Atom::STR_DELIMITER` (colliding with the self-
/// escape row's first entry) OR drifted [`Atom::STR_DELIMITER`] to
/// `'n'` (colliding with the NEWLINE named-escape source) fails at
/// `cargo check` BEFORE any test scheduler runs.
///
/// SYMMETRY IN THE NESTED SWEEP: the inner `while j < M` sweep visits
/// every position of `b` per outer `i` and panics at the FIRST cross-
/// array CONJOINED-pair collision (`a[i] == b[j]` on both columns).
/// Because the relation is symmetric and the two-loop sweep visits
/// every `(i, j) ∈ [0, N) × [0, M)` pair, swapping `a` and `b` at the
/// call site produces the SAME verdict — the helper does NOT
/// gratuitously depend on argument order. Row-parallel to the SCALAR
/// siblings' symmetric-nested-sweep posture — the shape of the
/// disjointness relation carries no argument-order preference across
/// the (element-type) axis.
///
/// Adding a new family-wide `[(char, char); N]` paired sub-vocabulary
/// whose distinct-values set must remain disjoint from another substrate
/// `[(char, char); M]` paired array's distinct-values set: pair the
/// declaration with `const _: () =
/// assert_char_pair_arrays_disjoint::<N, M>(&Self::FOO_ARRAY,
/// &Other::BAR_ARRAY);` co-located after the array's declaration and
/// the paired-array DISJOINTNESS contract binds at compile time. The
/// rustc-forced arities `[(char, char); N]` and `[(char, char); M]`
/// compose with this const-eval sweep so BOTH cardinality-pair AND
/// cross-array CONJOINED-pair disjointness are compile-time theorems
/// on the SAME (a, b) paired-array pair.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — pinned by
/// `assert_char_pair_arrays_disjoint_panics_at_runtime_on_collision`
/// and `assert_char_pair_arrays_disjoint_panic_message_names_the_
/// helper_and_char_pair_disjointness_violation_axis`. The panic site
/// carries the `"CHAR-PAIR-DISJOINTNESS-VIOLATION"` axis-provenance
/// string chosen DISTINCT from every sibling helper's axis vocabulary
/// (`"CHAR-DISJOINTNESS-VIOLATION"` / `"U8-DISJOINTNESS-VIOLATION"` /
/// `"STR-DISJOINTNESS-VIOLATION"` on the three SCALAR row-dual
/// DISJOINTNESS peers; `"CHAR-PAIR-SUBSET-VIOLATION"` on the paired-
/// array SUBSET-embedding sibling; `"LEFT column"` / `"RIGHT column"`
/// on the paired-array BIJECTIVITY sibling). The `"CHAR-PAIR-"` prefix
/// disambiguates from the (char) SCALAR row-dual DISJOINTNESS peer;
/// the shared `"-DISJOINTNESS-VIOLATION"` suffix lets callers grep any
/// row's DISJOINTNESS sibling by `"DISJOINTNESS-VIOLATION"` alone or
/// route to the specific element-type by the axis prefix.
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the family-wide paired-array
///   cross-array disjointness contract on `(char, char)` sub-
///   vocabularies becomes a TYPE-LEVEL theorem the substrate carries
///   per (a, b) paired-array pair rather than a runtime test the
///   developer must remember to write per pair.
/// - THEORY.md §III — the typescape; the (element-type × contract-
///   shape) matrix's (DISJOINTNESS) column now carries the PRODUCT-
///   ELEMENT `(char, char)` row alongside the three SCALAR rows at ONE
///   peer const-fn helper per row. The (element-type ∈ {char, u8,
///   `&'static str`, `(char, char)`} × contract-shape ∈ {disjointness})
///   4-corner column of the paired-array-contract prism is now closed
///   at FOUR peer const-fn helpers.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs; the
///   DISJOINTNESS proof at declaration site AND the outer-algebra's
///   two-sub-vocabulary partition contract on `Atom::ESCAPE_TABLE`
///   (pattern-DISTINCT-from-value NAMED rows disjoint from pattern-
///   EQUALS-value SELF rows) regenerate through the SAME `const _`
///   witness at the paired-ARRAY level.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   CONJOINED-pair membership sweep IS the generative shape. Every
///   new `(char, char)` sub-vocabulary paired array whose distinct-
///   value set is an intentionally-disjoint peer of another substrate
///   paired array adds ONE `const _` line.
///
/// Frontier inspiration: Lean 4's `Finset.disjoint_iff_ne` unfolded to
/// `∀ a ∈ s, ∀ b ∈ t, a ≠ b` at the concrete two-array
/// `[(char, char); N] × [(char, char); M]` monomorphic realisation
/// with the CONJOINED-pair `≠` decidable on product `(α × β)` reducing
/// to `a ≠ b ∨ c ≠ d` on `(a, c) ≠ (b, d)` — the substrate primitive
/// here embeds the same product-decidable disjointness relation as a
/// rustc const-eval-time proof obligation at every
/// `assert_char_pair_arrays_disjoint` call site.
pub const fn assert_char_pair_arrays_disjoint<const N: usize, const M: usize>(
    a: &[(char, char); N],
    b: &[(char, char); M],
) {
    let mut i = 0;
    while i < N {
        let mut j = 0;
        while j < M {
            // CONJOINED-pair equality — BOTH columns must match the
            // SAME `(a[i], b[j])` entry pair. A per-column disjointness
            // check on either column alone would REJECT paired arrays
            // whose columns share entries INDIVIDUALLY across rows even
            // when no CONJOINED pair aliases (a stricter contract than
            // paired-array disjointness). The CONJOINED gate permits
            // per-column aliasing as disjoint when the pairs themselves
            // differ — mirrors the sibling paired-array SUBSET
            // helper's CONJOINED gate on the same `(char, char)` row.
            if a[i].0 as u32 == b[j].0 as u32 && a[i].1 as u32 == b[j].1 as u32 {
                panic!(
                    "assert_char_pair_arrays_disjoint: CHAR-PAIR-\
                     DISJOINTNESS-VIOLATION — the two family-wide \
                     `[(char, char); N]` paired substrate arrays `a` \
                     and `b` share a CONJOINED-pair entry at some \
                     (i, j) position pair (BOTH columns of `a[i]` \
                     byte-for-byte equal BOTH columns of `b[j]`). The \
                     substrate's CROSS-ARRAY PAIRED-DISJOINTNESS \
                     contract on the pair is broken; every consumer \
                     that partitions the two paired arrays' distinct-\
                     value CONJOINED-pair sets into disjoint sub-\
                     vocabularies of a shared outer surface (the Str-\
                     payload escape-arm dispatch through `Atom::decode_\
                     str_escape` partitioning `Atom::ESCAPE_TABLE` \
                     into pattern-DISTINCT-from-value `Atom::NAMED_\
                     ESCAPE_TABLE` rows disjoint from pattern-EQUALS-\
                     value self-escape rows expressed as `(c, c)` \
                     pairs; any future typed-disjointness pair on the \
                     substrate's reader-boundary `(char, char)` \
                     algebras) relies on the two paired arrays' \
                     distinct-value CONJOINED-pair sets NOT sharing a \
                     pair. Fix at WHICHEVER ARRAY-DECLARATION site \
                     drifted (the symmetric disjointness relation \
                     carries no built-in axis-provenance role split \
                     between `a` and `b`) by dropping the offending \
                     pair from one array OR re-shaping the partition \
                     to route the shared pair to a single sub-\
                     vocabulary. The CONJOINED-pair equality gate \
                     distinguishes THIS helper from a per-column \
                     disjointness check that would REJECT paired \
                     arrays whose columns share entries INDIVIDUALLY \
                     across rows even when no CONJOINED pair aliases \
                     — the CONJOINED gate permits the per-column \
                     aliasing corner as disjoint"
                );
            }
            j += 1;
        }
        i += 1;
    }
}

// Compile-time DISJOINTNESS witness — the ONE substrate-pinned
// `[(char, char); N] × [(char, char); M]` paired-array pair whose
// distinct-value CONJOINED-pair sets are intentionally-closed disjoint
// sub-vocabularies of the Str-payload escape-arm dispatch at
// `Atom::decode_str_escape`. The pattern-DISTINCT-from-value NAMED rows
// (`Atom::NAMED_ESCAPE_TABLE`, `[(char, char); 3]`) partition
// `Atom::ESCAPE_TABLE`'s first three positions; the pattern-EQUALS-
// value SELF rows lifted to `(c, c)` pair form (constructed inline
// from `Atom::SELF_ESCAPE_TABLE`) partition `Atom::ESCAPE_TABLE`'s
// remaining two positions. Pre-lift the paired-DISJOINTNESS of the
// two sub-vocabularies lived only implicitly at `Atom::ESCAPE_TABLE`'s
// composite declaration site (positions [0..3] as `NAMED_ESCAPE_TABLE`
// indexings + positions [3..5] as `(SELF[k], SELF[k])` pair
// constructions — the disjointness of the two SLICES holding by
// construction rather than by a checked contract). Post-lift the
// paired-ARRAY-LEVEL disjointness binds at rustc time via ONE `const
// _` line. A regression that silently drifted a NAMED escape source
// (e.g. `NEWLINE_ESCAPE_SOURCE` from `'n'` to `Atom::STR_DELIMITER`,
// colliding with the SELF row's first entry) OR drifted `Atom::STR_
// DELIMITER` to `'n'` (colliding with the NAMED NEWLINE source) fails
// at `cargo check` BEFORE any test scheduler runs. Sibling to the
// pre-existing paired-array BIJECTIVITY witnesses above (which pin
// LEFT-column ∧ RIGHT-column injectivity on each individual paired
// array) and the paired-array SUBSET-EMBEDDING witness (which pins
// `NAMED_ESCAPE_TABLE ⊂ ESCAPE_TABLE` at CONJOINED-pair containment)
// on the `(char, char)` row of the (element-type × contract-shape)
// matrix — the three witnesses together close the (paired-array well-
// formedness, paired-array subset, paired-array disjointness) 3-corner
// face on the paired-array row at ONE peer const-fn helper per corner.
// Row-parallel to the (char) + (u8) + (`&'static str`) SCALAR rows'
// DISJOINTNESS witnesses above on the (element-type) axis of the SAME
// (disjointness) contract-shape column.
const _: () = assert_char_pair_arrays_disjoint::<3, 2>(
    &Atom::NAMED_ESCAPE_TABLE,
    &[
        (Atom::SELF_ESCAPE_TABLE[0], Atom::SELF_ESCAPE_TABLE[0]),
        (Atom::SELF_ESCAPE_TABLE[1], Atom::SELF_ESCAPE_TABLE[1]),
    ],
);

/// Compile-time contract verifier — panics at const evaluation time if
/// the family-wide `[(char, char); N]` paired substrate array `arr`
/// carries a pair at two distinct positions whose `(SOURCE, DECODED)`
/// tuples are byte-for-byte equal. Binds ONE conjunct clause on the
/// `(char, char)` product-element row of the (element-type × contract-
/// shape) matrix at the (pairwise-distinctness) column — CHAR-PAIR-
/// TUPLE-COLLISION — every position of `arr` MUST carry a
/// CONJOINED-pair `(a, b)` byte-for-byte distinct from every other
/// position's pair. Pair equality is CONJOINED across BOTH columns:
/// `arr[i] == arr[j]` iff `arr[i].0 == arr[j].0 AND arr[i].1 ==
/// arr[j].1` — a per-column pairwise-distinct check on either column
/// alone would REJECT paired arrays whose columns share entries
/// INDIVIDUALLY across rows even when no CONJOINED tuple aliases
/// (a stricter contract than tuple-level pairwise-distinctness, which
/// the sibling [`assert_char_pair_array_bijective`] closes as the
/// (column-INDEPENDENT injectivity) axis on the SAME row).
///
/// Contract-strength peer to [`assert_char_pair_array_bijective`] on
/// the (independent-column-injectivity vs tuple-injectivity) axis
/// splitting the (char, char) row's INJECTIVITY column into TWO
/// distinct sub-contracts. Bijectivity is strictly stronger — a
/// bijective paired array (`assert_char_pair_array_bijective`) has
/// LEFT-column pairwise-distinct AND RIGHT-column pairwise-distinct
/// INDEPENDENTLY, which implies tuple-level pairwise-distinctness
/// (if `a[i].0 == a[j].0` fails and `a[i].1 == a[j].1` fails
/// independently, then the tuples cannot collide either). This
/// helper enforces ONLY the CONJOINED-tuple distinctness — a strictly
/// WEAKER contract that permits per-column aliasing across rows as
/// long as no CONJOINED tuple aliases. Mirrors the sibling
/// (char, char) row helpers' CONJOINED-pair gate posture:
/// [`assert_char_pair_array_within_char_pair_finite_set`] and
/// [`assert_char_pair_arrays_disjoint`] BOTH gate on
/// CONJOINED-tuple equality; this helper closes the third
/// CONJOINED-tuple sibling on the SAME (char, char) row.
///
/// Element-type row-parallel to the three SCALAR-element pairwise-
/// distinctness sibling helpers on the (element-type) axis:
/// [`assert_char_array_pairwise_distinct`] (the (char) scalar-element
/// peer), [`assert_str_array_pairwise_distinct`] (the (`&'static str`)
/// scalar-element peer), and [`assert_u8_array_pairwise_distinct`]
/// (the (u8) scalar-element peer). Where the three scalar-element
/// siblings close the INJECTIVITY column on the three SCALAR rows of
/// the (element-type × contract-shape) matrix, this helper closes the
/// TUPLE-level INJECTIVITY corner on the (char, char) PRODUCT-element
/// row — the fourth row of the matrix's element-type axis. Together
/// with [`assert_char_pair_array_bijective`] (the column-INDEPENDENT
/// INJECTIVITY peer on the SAME row) the (char, char) row now closes
/// BOTH INJECTIVITY sub-shapes at ONE const-fn helper each: the
/// stronger column-independent axis at the bijective sibling; the
/// weaker CONJOINED-tuple axis here.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — e.g. a REPL / LSP
/// tokenizer that constructs a `[(char, char); N]` paired array at
/// runtime and wants to verify tuple-level pairwise-distinctness
/// before consuming it — and the panic surfaces normally in that
/// path (pinned by
/// `assert_char_pair_array_pairwise_distinct_panics_at_runtime_on_tuple_collision`
/// and
/// `assert_char_pair_array_pairwise_distinct_panic_message_names_the_helper_and_char_pair_tuple_collision_axis`).
/// The panic message carries a CHAR-PAIR-TUPLE-COLLISION axis-
/// provenance suffix so downstream diagnostics (`cargo check` const-
/// eval error output, test-suite failure reports) route the drift
/// back to THIS helper's tuple-level axis rather than to the
/// sibling bijective helper's column-LABELED axis (LEFT-column vs
/// RIGHT-column) — halving the search space for the operator
/// debugging a drift that surfaces at the tuple axis but is invisible
/// at either column axis alone.
///
/// Adding a new family-wide `[(char, char); N]` paired-array whose
/// distinct-value tuple-set carries a pairwise-distinct-but-NOT-
/// bijective contract: pair the declaration with `const _: () =
/// assert_char_pair_array_pairwise_distinct(&Self::FOO_TABLE);` co-
/// located after the array's declaration and the tuple-level
/// distinctness contract binds at compile time. The rustc-forced
/// arity `[(char, char); N]` composes with this const-eval sweep so
/// cardinality AND tuple-level injectivity are compile-time theorems
/// on the SAME array. A future consumer keyed on tuple-level
/// (rather than column-level) distinctness — a hypothetical (short-
/// form, canonical-form) alias table that permits many-to-one
/// aliasing on either column but requires the paired short↔canonical
/// tuples to be pairwise-distinct — reaches for THIS helper without
/// composing through the strictly stronger bijective sibling.
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the family-wide tuple-
///   level pairwise-distinctness contract on the `(char, char)`
///   paired substrate vocabulary becomes a TYPE-LEVEL theorem the
///   substrate carries per paired-array declaration rather than a
///   runtime test the developer must remember to write per array.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs; a
///   tuple-level distinctness proof at declaration site AND the
///   tuple-level match-arm exhaustiveness at every consumer that
///   enumerates the array's tuples as DISJOINT arms regenerate
///   through the SAME `const _` witness.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   tuple-CONJOINED sweep IS the generative shape. Every new
///   closed-set paired-array vocabulary whose distinct-value tuple-
///   set is intentionally pairwise-distinct-at-the-tuple-level adds
///   ONE `const _` line to get the tuple-level distinctness theorem
///   rather than re-deriving a `HashSet::insert` loop test per array.
///
/// Frontier inspiration: Lean 4's `List.Nodup` on `List (α × β)` at
/// the concrete monomorphic realisation `[(char, char); N]` with the
/// CONJOINED-tuple `≠` decidable on product `(α × β)` reducing to
/// `a ≠ b ∨ c ≠ d` on `(a, c) ≠ (b, d)` — the substrate primitive
/// here embeds the same product-decidable pairwise-distinctness
/// relation as a rustc const-eval-time proof obligation at every
/// `assert_char_pair_array_pairwise_distinct` call site.
pub const fn assert_char_pair_array_pairwise_distinct<const N: usize>(arr: &[(char, char); N]) {
    let mut i = 0;
    while i < N {
        let mut j = i + 1;
        while j < N {
            // CONJOINED-tuple equality — BOTH columns must match the
            // SAME `(arr[i], arr[j])` position pair. A per-column
            // pairwise-distinct check on either column alone would
            // REJECT paired arrays whose columns share entries
            // INDIVIDUALLY across rows even when no CONJOINED tuple
            // aliases (a stricter contract than tuple-level pairwise-
            // distinctness, which the sibling
            // `assert_char_pair_array_bijective` closes as the
            // column-INDEPENDENT INJECTIVITY axis on the SAME row).
            // The CONJOINED gate is the (char, char) row's WEAKER
            // pairwise-distinctness axis — mirrors the sibling
            // `assert_char_pair_arrays_disjoint` +
            // `assert_char_pair_array_within_char_pair_finite_set`
            // CONJOINED-tuple gates on the same row.
            if arr[i].0 as u32 == arr[j].0 as u32 && arr[i].1 as u32 == arr[j].1 as u32 {
                panic!(
                    "assert_char_pair_array_pairwise_distinct: CHAR-\
                     PAIR-TUPLE-COLLISION — family-wide `[(char, \
                     char); N]` paired substrate array carries a \
                     duplicate CONJOINED-tuple entry across two \
                     positions (BOTH columns of `arr[i]` byte-for-\
                     byte equal BOTH columns of `arr[j]`). The \
                     substrate's TUPLE-level pairwise-distinctness \
                     contract on the array is broken; every consumer \
                     that pattern-matches the array's CONJOINED-\
                     tuples as DISJOINT arms (any future \
                     `match (a, b) {{ … }}` outer dispatch on a paired \
                     vocabulary, any future tuple-keyed cache index \
                     on a `[(char, char); N]` table) relies on this \
                     invariant. Fix at the ARRAY-DECLARATION site by \
                     dropping the duplicate tuple OR re-shaping the \
                     partition to route the shared tuple to a single \
                     position. The CONJOINED-tuple equality gate \
                     distinguishes THIS helper from a per-column \
                     pairwise-distinct check that would REJECT paired \
                     arrays whose columns share entries INDIVIDUALLY \
                     across rows even when no CONJOINED tuple aliases \
                     — the CONJOINED gate is the (char, char) row's \
                     WEAKER pairwise-distinctness axis, peer to the \
                     stricter column-INDEPENDENT INJECTIVITY axis at \
                     `assert_char_pair_array_bijective`"
                );
            }
            j += 1;
        }
        i += 1;
    }
}

// Compile-time TUPLE-level pairwise-distinctness witnesses — one
// `const _: () = assert_char_pair_array_pairwise_distinct(&…)` per
// family-wide `[(char, char); N]` paired substrate array on the Str-
// payload escape-table product-vocabulary. Each invocation is const-
// evaluated at `cargo check` time; a regression that silently
// collided TWO CONJOINED-tuples across positions fails the build
// rather than the test suite. Sibling to the pre-existing paired-
// array BIJECTIVITY witnesses above (which pin the strictly stronger
// column-INDEPENDENT INJECTIVITY axis — LEFT-column ∧ RIGHT-column
// pairwise-distinct per array); this helper pins the WEAKER
// CONJOINED-tuple INJECTIVITY axis at the SAME two arrays. Both
// axes are compile-time theorems on both arrays post-lift: bijective
// binds the strictly stronger axis (implied on both existing
// arrays); this helper binds the WEAKER tuple-level axis. Row-
// parallel to the three SCALAR-element rows' pairwise-distinct
// witnesses above on the (element-type) axis: (char) closes the
// reader-boundary vocabulary; (`&'static str`) closes the closed-set
// outer-algebras' label / prefix / tag / literal vocabularies; (u8)
// closes the outer-`Sexp` cache-key discriminator vocabulary; and
// this (char, char) product-element sibling closes the paired
// escape-table vocabulary at the TUPLE-level. The dual-axis coverage
// (bijective + pairwise-distinct-tuples) gives downstream consumers
// TWO axis-provenance vocabularies to route regressions through: a
// future consumer keyed on tuple-level (rather than column-level)
// distinctness — a hypothetical (short-form, canonical-form) alias
// table that permits many-to-one aliasing on either column but
// requires paired short↔canonical tuples to be pairwise-distinct —
// reaches for THIS helper's `CHAR-PAIR-TUPLE-COLLISION` panic
// message rather than for the bijective sibling's column-LABELED
// panic (LEFT-column collision vs RIGHT-column collision).
const _: () = assert_char_pair_array_pairwise_distinct(&Atom::NAMED_ESCAPE_TABLE);
const _: () = assert_char_pair_array_pairwise_distinct(&Atom::ESCAPE_TABLE);

/// Compile-time contract verifier — panics at const evaluation time
/// if either column-projection of the family-wide `[(char, char); N]`
/// paired substrate array `pairs` diverges byte-for-byte from its
/// declared peer scalar `[char; N]` array. Binds a JOINT
/// (LEFT_col == left) ∧ (RIGHT_col == right) POSITIONWISE-EQUALITY
/// contract at ONE `const _` line on the (char, char) product-element
/// row of the (element-type × contract-shape) matrix at the
/// (column-projection-equality) column — a NEW column opened past the
/// (INJECTIVITY, SUBSET-EMBEDDING, DISJOINTNESS) triple the four
/// sibling helpers close ([`assert_char_pair_array_bijective`] +
/// [`assert_char_pair_array_pairwise_distinct`] on INJECTIVITY,
/// [`assert_char_pair_array_within_char_pair_finite_set`] on SUBSET-
/// EMBEDDING, [`assert_char_pair_arrays_disjoint`] on DISJOINTNESS).
///
/// Rust's forced `[T; N]` cardinality composes with the const-eval
/// sweep to pin THREE clauses at ONE `const _` line:
///   1. ARITY: `pairs.len() == left.len() == right.len() == N` — a
///      regression that drifts EITHER peer scalar array's arity away
///      from the paired array's `N` fails-loudly at type-check time
///      (before const eval), so the two clauses BELOW walk a
///      length-parallel sweep unconditionally.
///   2. LEFT-COLUMN-EQUALITY: `pairs[i].0 == left[i]` for every
///      `i ∈ 0..N` — a regression that drifts ONE paired-table LEFT
///      entry away from the peer scalar SOURCE array (e.g. renames
///      `NEWLINE_ESCAPE_SOURCE` to `LINEFEED_ESCAPE_SOURCE` and
///      updates ONLY the pair entry without updating the scalar
///      declaration, OR vice versa) fails-loudly at const eval.
///   3. RIGHT-COLUMN-EQUALITY: `pairs[i].1 == right[i]` for every
///      `i ∈ 0..N` — same posture on the RIGHT / DECODED column.
///
/// Currently applied to the (`ESCAPE_TABLE`, `ESCAPE_SOURCES`,
/// `ESCAPE_DECODED`) triple where the paired array is CONSTRUCTED
/// from `NAMED_ESCAPE_TABLE` + `SELF_ESCAPE_TABLE` (see
/// [`Atom::ESCAPE_TABLE`]'s definition) and the two peer scalar
/// arrays are DECLARED INDEPENDENTLY as
/// [`Atom::ESCAPE_SOURCES`](Atom::ESCAPE_SOURCES) +
/// [`Atom::ESCAPE_DECODED`](Atom::ESCAPE_DECODED). Pre-lift the
/// three-way column bond ("`ESCAPE_TABLE`'s LEFT column IS
/// `ESCAPE_SOURCES` AND RIGHT column IS `ESCAPE_DECODED`") lived
/// as PROSE in the peer arrays' docstrings ("the SPAN of the two
/// peer sub-vocabulary source columns") plus as a runtime test that
/// zipped the three arrays; post-lift the bond binds at `cargo
/// check` time — a regression that renames a source or decoded byte
/// on ONE of the three arrays without updating the other two fails
/// the build rather than the test suite. The const-eval panic
/// surfaces the column-divergence at COMPILE time, one invocation
/// stage earlier, catching regressions on `cargo build` /
/// `cargo clippy` runs that skip the test suite.
///
/// Contract-shape peer to the four sibling paired-array verifiers
/// on the (char, char) row: where the sibling
/// [`assert_char_pair_array_bijective`] closes the INJECTIVITY axis
/// (LEFT-column ∧ RIGHT-column pairwise-distinct, INDEPENDENTLY),
/// [`assert_char_pair_array_pairwise_distinct`] closes the WEAKER
/// CONJOINED-tuple INJECTIVITY axis, [`assert_char_pair_array_
/// within_char_pair_finite_set`] closes the SUBSET-EMBEDDING axis,
/// and [`assert_char_pair_arrays_disjoint`] closes the DISJOINTNESS
/// axis, THIS helper opens the fifth (column-projection-EQUALITY)
/// axis — the (LEFT column == left) ∧ (RIGHT column == right) JOINT
/// clause that bonds a paired vocabulary to TWO peer scalar
/// vocabularies. Compound-JOINT posture parallels the pre-existing
/// [`assert_scalar_plus_two_u8_arrays_permute_inclusive_range`] on
/// the (u8) row (three-array joint contract at one witness line);
/// unlike the permutation posture there, this helper's joint
/// contract is POSITIONWISE-EQUALITY (order-sensitive) rather than
/// set-EQUALITY.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — e.g. a REPL / LSP
/// tokenizer that constructs a paired escape table + two peer
/// scalar columns at runtime and wants to verify column-projection
/// equality before consuming them — and the two panic sites (LEFT-
/// column divergence, RIGHT-column divergence) surface normally in
/// that path with column-provenance-preserving panic messages
/// (pinned by the two `_panics_at_runtime_on_left_head_divergence`
/// and `_panics_at_runtime_on_right_head_divergence` tests plus
/// their middle-position and tail-position peers). The two axis-
/// provenance strings `"LEFT-COLUMN-DIVERGENCE"` and
/// `"RIGHT-COLUMN-DIVERGENCE"` are chosen DISTINCT from every
/// sibling helper's axis vocabulary (`"LEFT column"` and
/// `"RIGHT column"` on the paired-array BIJECTIVITY sibling name the
/// COLUMN but the failure MODE is `duplicate SOURCE / DECODED char`;
/// this helper's failure MODE is `divergence from peer scalar
/// array`) so a diagnostic that names the failed axis routes
/// UNAMBIGUOUSLY to (a) this specific paired-array COLUMN-
/// PROJECTION-EQUALITY helper, (b) the failed COLUMN by the
/// `"LEFT-"` and `"RIGHT-"` prefix.
///
/// Adding a new family-wide `[(char, char); N]` paired array
/// declared alongside TWO peer scalar `[char; N]` arrays whose
/// LEFT + RIGHT columns are meant to project to the peer arrays'
/// contents: pair the declarations with `const _: () =
/// assert_char_pair_array_columns_equal_char_arrays(&Self::FOO_
/// TABLE, &Self::FOO_LEFT, &Self::FOO_RIGHT);` and the three-way
/// column bond binds at compile time WITHOUT a runtime zip loop.
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the three-way column bond
///   on the paired-array + peer-scalar-columns vocabulary becomes
///   a TYPE-LEVEL theorem the substrate carries per declaration
///   triple rather than a runtime zip loop the developer must
///   remember to write per triple.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs;
///   the column-projection-equality proof at declaration site AND
///   the peer-array outer-dispatch consumers regenerate through
///   the SAME `const _` witness.
/// - THEORY.md §VI.1 — generation over composition; the two-column
///   positionwise-equality sweep IS the generative shape. Every
///   new closed-set paired-array declared alongside peer scalar
///   columns adds ONE `const _` line to get the three-way bond
///   theorem rather than re-deriving a runtime zip loop per triple.
pub const fn assert_char_pair_array_columns_equal_char_arrays<const N: usize>(
    pairs: &[(char, char); N],
    left: &[char; N],
    right: &[char; N],
) {
    let mut i = 0;
    while i < N {
        if pairs[i].0 as u32 != left[i] as u32 {
            panic!(
                "assert_char_pair_array_columns_equal_char_arrays: \
                 LEFT-COLUMN-DIVERGENCE — family-wide `[(char, \
                 char); N]` paired substrate array's LEFT column \
                 projection carries an entry at some position that \
                 does NOT byte-for-byte equal the peer scalar \
                 `[char; N]` array's entry at the SAME position. \
                 The substrate's LEFT-column POSITIONWISE-EQUALITY \
                 contract on the (paired, peer-scalar) column-\
                 projection bond is broken; every consumer that \
                 reads the paired array's LEFT column and the peer \
                 scalar SOURCE array as INTERCHANGEABLE (any \
                 outer-tokenizer `Sexp` dispatch that pattern-\
                 matches on `Atom::ESCAPE_SOURCES` while a peer \
                 attestation code path reads `Atom::ESCAPE_TABLE`'s \
                 LEFT column, any future `[char; N]` peer-column \
                 dual projection that assumes the two are equal at \
                 every position) relies on this invariant. Fix at \
                 one of the THREE declaration sites (`pairs`, \
                 `left`, or the peer scalar RIGHT column's \
                 declaration if the drift is a cross-column rename) \
                 by reconciling the entry across the three arrays. \
                 The LEFT-column-divergence gate distinguishes THIS \
                 helper from the sibling `assert_char_pair_array_\
                 bijective` (which surfaces LEFT-column DUPLICATE-\
                 SOURCE failures, not LEFT-column-vs-peer-scalar \
                 DIVERGENCE failures) and from the sibling `assert_\
                 char_pair_array_within_char_pair_finite_set` \
                 (which surfaces CONJOINED-tuple SUBSET-VIOLATION \
                 failures, not per-column POSITIONWISE-EQUALITY \
                 failures)"
            );
        }
        if pairs[i].1 as u32 != right[i] as u32 {
            panic!(
                "assert_char_pair_array_columns_equal_char_arrays: \
                 RIGHT-COLUMN-DIVERGENCE — family-wide `[(char, \
                 char); N]` paired substrate array's RIGHT column \
                 projection carries an entry at some position that \
                 does NOT byte-for-byte equal the peer scalar \
                 `[char; N]` array's entry at the SAME position. \
                 The substrate's RIGHT-column POSITIONWISE-EQUALITY \
                 contract on the (paired, peer-scalar) column-\
                 projection bond is broken; every consumer that \
                 reads the paired array's RIGHT column and the peer \
                 scalar DECODED array as INTERCHANGEABLE (any \
                 outer-tokenizer `Sexp` dispatch that pattern-\
                 matches on `Atom::ESCAPE_DECODED` while a peer \
                 attestation code path reads `Atom::ESCAPE_TABLE`'s \
                 RIGHT column, any future `[char; N]` peer-column \
                 dual projection that assumes the two are equal at \
                 every position) relies on this invariant. Fix at \
                 one of the THREE declaration sites (`pairs`, \
                 `right`, or the peer scalar LEFT column's \
                 declaration if the drift is a cross-column rename) \
                 by reconciling the entry across the three arrays"
            );
        }
        i += 1;
    }
}

// Compile-time column-projection-EQUALITY witness — one `const _: ()
// = assert_char_pair_array_columns_equal_char_arrays(&…, &…, &…)`
// binding the (ESCAPE_TABLE, ESCAPE_SOURCES, ESCAPE_DECODED) three-
// way column bond on the substrate's Str-payload escape-table
// vocabulary. `Atom::ESCAPE_TABLE` (`[(char, char); 5]`) is
// CONSTRUCTED from `NAMED_ESCAPE_TABLE[0..=2]` + two SELF-diagonal
// pairs `(SELF_ESCAPE_TABLE[0], SELF_ESCAPE_TABLE[0])` +
// `(SELF_ESCAPE_TABLE[1], SELF_ESCAPE_TABLE[1])`, whose LEFT +
// RIGHT column projections match `Atom::ESCAPE_SOURCES` +
// `Atom::ESCAPE_DECODED` position-for-position by declaration
// intent — this const-eval witness binds that intent as a compile-
// time theorem so a regression that renames a source or decoded
// byte on ONE of the three arrays without updating the other two
// fails the build. Sibling to the `_pairwise_distinct` + `_bijective`
// witnesses above on the SAME paired array — the FOUR const-eval
// sweeps enforce complementary axes of the same substrate table at
// FOUR stages of the toolchain, so a build that skips tests still
// catches column-projection drift here, and a build that runs tests
// catches it a second time as a safety net if the const-eval sweep
// is ever silently dropped.
const _: () = assert_char_pair_array_columns_equal_char_arrays(
    &Atom::ESCAPE_TABLE,
    &Atom::ESCAPE_SOURCES,
    &Atom::ESCAPE_DECODED,
);

/// Compile-time contract verifier — panics at const evaluation time if
/// the family-wide `[(char, char); N]` paired substrate array `arr`
/// carries a character that appears in BOTH its LEFT column projection
/// AND its RIGHT column projection (across ANY position pair). Binds
/// ONE conjunct clause on the `(char, char)` product-element row of the
/// (element-type × contract-shape) matrix at the
/// (cross-column-disjointness) column — CROSS-COLUMN-COLLISION — the
/// set of characters appearing as LEFT entries MUST be DISJOINT from
/// the set of characters appearing as RIGHT entries. Formally:
/// `∀ i, j ∈ 0..N : arr[i].0 as u32 != arr[j].1 as u32` — including
/// the diagonal `i == j` case (a `('a', 'a')` self-mapping pair
/// FAILS this contract even though it satisfies BOTH the SELF-arm
/// identity-relation shape AND the sibling
/// [`assert_char_pair_array_bijective`] per-column injectivity check).
///
/// Contract-shape orthogonality with the FOUR sibling paired-array
/// verifiers on the SAME row:
///   * [`assert_char_pair_array_bijective`] closes the per-column
///     INJECTIVITY axis (LEFT-column ∧ RIGHT-column pairwise-distinct,
///     INDEPENDENTLY) — a table like `[('a', 'x'), ('a', 'y')]` fails
///     BIJECTIVITY (LEFT duplicated) but passes CROSS-COLUMN-DISJOINT
///     (LEFT = {'a'}, RIGHT = {'x', 'y'}, disjoint). The two axes are
///     INDEPENDENT: neither implies the other.
///   * [`assert_char_pair_array_pairwise_distinct`] closes the WEAKER
///     CONJOINED-tuple INJECTIVITY axis — a table like
///     `[('a', 'a')]` passes CONJOINED-tuple pairwise-distinctness
///     (only one tuple) but FAILS CROSS-COLUMN-DISJOINT (LEFT[0] ==
///     RIGHT[0] on the diagonal).
///   * [`assert_char_pair_array_within_char_pair_finite_set`] closes
///     the SUBSET-EMBEDDING axis — orthogonal to cross-column
///     disjointness (a table can be a subset of a well-formed set and
///     still violate cross-column disjointness if the set itself does).
///   * [`assert_char_pair_arrays_disjoint`] closes the BETWEEN-ARRAY
///     DISJOINTNESS axis (two arrays share no CONJOINED tuple) — this
///     helper closes the WITHIN-ARRAY CROSS-COLUMN DISJOINTNESS axis
///     (one array's LEFT column shares no CHARACTER with its RIGHT
///     column). The two axes are DUAL: BETWEEN-ARRAY vs WITHIN-ARRAY,
///     CONJOINED-tuple vs CROSS-COLUMN-CHARACTER.
///
/// The invariant is load-bearing for the substrate's
/// pattern-DISTINCT-from-value sub-vocabulary at
/// [`Atom::NAMED_ESCAPE_TABLE`] (`[(char, char); 3]`): the three
/// named-escape rows `('n', '\n')`, `('t', '\t')`, `('r', '\r')` are
/// pattern-DISTINCT-from-value by algebra design (the printable ASCII
/// SOURCE column and the control-character DECODED column MUST NOT
/// overlap — a regression that added a pair like `('n', 'r')` or
/// `('a', 'a')` would silently collapse the pattern-DISTINCT-from-value
/// axis by routing a SOURCE character back to itself OR to another
/// SOURCE character, making the two sub-vocabularies
/// (pattern-distinct at [`Atom::NAMED_ESCAPE_TABLE`] +
/// pattern-equals at [`Atom::SELF_ESCAPE_TABLE`]) share membership).
/// The SHAPE ASYMMETRY between the two peer arrays (`[(char, char); N]`
/// vs `[char; N]`) already encodes the identity-relation asymmetry in
/// the TYPE — but a `[(char, char); N]` on the DISTINCT sub-vocabulary
/// side can silently drift a pair onto the diagonal while retaining
/// its paired shape. Pre-lift, the cross-column disjointness of
/// `NAMED_ESCAPE_TABLE` lived ONLY as prose in the substrate's escape-
/// table docstrings ("the THREE pattern-DISTINCT-from-value named-
/// escape rows") plus as an implicit consequence of the ASCII-letter
/// vs control-character byte-range partition. Post-lift the cross-
/// column disjointness binds at `cargo check` time — a regression
/// that adds a `('a', 'a')` diagonal pair, a `('n', 'r')` cross-row
/// SOURCE-to-SOURCE aliasing pair, or any pair drifting a character
/// across the LEFT / RIGHT partition fails the build rather than the
/// test suite.
///
/// Applies ONLY to the pattern-DISTINCT-from-value sub-vocabulary of
/// the escape-table family. [`Atom::ESCAPE_TABLE`] (`[(char, char); 5]`)
/// INTENTIONALLY violates cross-column disjointness on its two SELF
/// arms (the tail two positions `(STR_DELIMITER, STR_DELIMITER)` +
/// `(STR_ESCAPE_LEAD, STR_ESCAPE_LEAD)` are diagonal self-mappings by
/// design). No witness is co-located on `Atom::ESCAPE_TABLE` — the
/// SHAPE ASYMMETRY between the two escape-table sub-vocabularies IS
/// the axis distinguishing them, and this helper's contract holds
/// ONLY on the DISTINCT side.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — e.g. a REPL / LSP
/// tokenizer that constructs a paired vocabulary at runtime and wants
/// to verify cross-column disjointness before consuming it — and the
/// panic surfaces normally in that path (pinned by
/// `assert_char_pair_array_columns_cross_disjoint_panics_at_runtime_
/// on_diagonal_collision` and its off-diagonal peers). The axis-
/// provenance string `"CROSS-COLUMN-COLLISION"` is chosen DISTINCT
/// from every sibling helper's axis vocabulary (`"CHAR-PAIR-TUPLE-
/// COLLISION"` on `_pairwise_distinct`, `"LEFT column"` / `"RIGHT
/// column"` on `_bijective`, `"CHAR-PAIR-SUBSET-VIOLATION"` on
/// `_within_char_pair_finite_set`, `"CHAR-PAIR-DISJOINTNESS-
/// VIOLATION"` on `_arrays_disjoint`, `"LEFT-COLUMN-DIVERGENCE"` /
/// `"RIGHT-COLUMN-DIVERGENCE"` on `_columns_equal_char_arrays`) so a
/// diagnostic that names the failed axis routes UNAMBIGUOUSLY to
/// this specific cross-column-disjointness helper rather than to a
/// sibling paired-array verifier.
///
/// Adding a new family-wide `[(char, char); N]` paired array on a
/// pattern-DISTINCT-from-value sub-vocabulary (e.g. a hypothetical
/// (short-form, long-form) alias table where short and long forms
/// live in disjoint character partitions, or a `(bracket-open,
/// bracket-close)` table where open and close characters MUST NOT
/// alias): pair the declaration with `const _: () = assert_char_
/// pair_array_columns_cross_disjoint(&Self::FOO_TABLE);` co-located
/// immediately after the array's declaration and the cross-column
/// disjointness contract binds at compile time WITHOUT a runtime
/// LEFT.iter().any(RIGHT.contains) sweep.
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the WITHIN-ARRAY CROSS-
///   COLUMN disjointness contract becomes a TYPE-LEVEL theorem the
///   substrate carries per pattern-DISTINCT-from-value paired-array
///   declaration rather than a runtime membership sweep the developer
///   must remember to write per array.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs; the
///   cross-column disjointness proof at declaration site AND the
///   escape-table consumers that route SOURCE-column characters
///   THROUGH `decode_str_escape` to DECODED-column characters (and
///   rely on that route being one-way) regenerate through the SAME
///   `const _` witness.
/// - THEORY.md §VI.1 — generation over composition; the doubly-nested
///   `while` cross-column sweep IS the generative shape. Every new
///   pattern-DISTINCT-from-value closed-set paired-array adds ONE
///   `const _` line to get the cross-column disjointness theorem
///   rather than re-deriving a `HashSet::intersection` runtime test
///   per array.
pub const fn assert_char_pair_array_columns_cross_disjoint<const N: usize>(
    arr: &[(char, char); N],
) {
    let mut i = 0;
    while i < N {
        let mut j = 0;
        while j < N {
            if arr[i].0 as u32 == arr[j].1 as u32 {
                panic!(
                    "assert_char_pair_array_columns_cross_disjoint: \
                     CROSS-COLUMN-COLLISION — family-wide `[(char, \
                     char); N]` paired substrate array carries a \
                     character appearing in BOTH the LEFT column at \
                     some position `i` AND the RIGHT column at some \
                     position `j` (possibly `i == j`, the diagonal \
                     self-mapping case). The substrate's WITHIN-ARRAY \
                     CROSS-COLUMN DISJOINTNESS contract on the array \
                     is broken; every consumer that treats the paired \
                     array as a pattern-DISTINCT-from-value sub-\
                     vocabulary (any escape-table decode path that \
                     assumes SOURCE bytes and DECODED bytes live in \
                     disjoint character partitions so `decode_str_\
                     escape` is a strictly ONE-WAY mapping, any \
                     future `(bracket-open, bracket-close)` paired \
                     vocabulary that assumes open and close characters \
                     alias with neither each other nor a peer role) \
                     relies on this invariant. Fix at the ARRAY-\
                     DECLARATION site by moving the diagonal or \
                     cross-row aliased pair to the peer SELF-arm \
                     vocabulary (`Atom::SELF_ESCAPE_TABLE` on the \
                     escape-table family) OR by re-shaping the pair \
                     to route the shared character to a single column. \
                     The CROSS-COLUMN-COLLISION axis is DISTINCT from \
                     the sibling `_bijective` per-column INJECTIVITY \
                     axis (a table like `[('a', 'x'), ('a', 'y')]` \
                     fails `_bijective` on the LEFT-column-duplicate \
                     arm but PASSES this helper because LEFT = {{'a'}} \
                     and RIGHT = {{'x', 'y'}} are disjoint) and from \
                     the sibling `_pairwise_distinct` CONJOINED-tuple \
                     INJECTIVITY axis (a table like `[('a', 'a')]` \
                     passes `_pairwise_distinct` on the singleton but \
                     FAILS this helper on the diagonal `arr[0].0 == \
                     arr[0].1` — the two axes cross-check different \
                     failure modes on the SAME paired vocabulary)"
                );
            }
            j += 1;
        }
        i += 1;
    }
}

// Compile-time WITHIN-ARRAY CROSS-COLUMN disjointness witness — one
// `const _: () = assert_char_pair_array_columns_cross_disjoint(&…)`
// binding the pattern-DISTINCT-from-value sub-vocabulary's cross-
// column character-set disjointness at `cargo check` time on the
// substrate's escape-table family. Applied to
// `Atom::NAMED_ESCAPE_TABLE` (`[(char, char); 3]` — the three named-
// escape rows `('n', '\n')`, `('t', '\t')`, `('r', '\r')`); the LEFT
// column projection = {'n', 't', 'r'} (printable ASCII) and the RIGHT
// column projection = {'\n', '\t', '\r'} (control characters) are
// disjoint by algebra design. A regression that added a `('n', 'r')`
// SOURCE-to-SOURCE aliasing pair, a `('a', 'a')` diagonal self-
// mapping pair, or any pair drifting a character across the LEFT /
// RIGHT partition fails the build rather than the test suite.
// Deliberately NOT applied to `Atom::ESCAPE_TABLE` — that array
// composes `NAMED_ESCAPE_TABLE` with two SELF arms at the tail
// (`(STR_DELIMITER, STR_DELIMITER)` + `(STR_ESCAPE_LEAD, STR_ESCAPE_
// LEAD)`), which INTENTIONALLY violate cross-column disjointness on
// the diagonal by algebra design. The SHAPE ASYMMETRY between the
// pattern-DISTINCT-from-value (`NAMED_ESCAPE_TABLE`) and the pattern-
// EQUALS-value (`SELF_ESCAPE_TABLE`) sub-vocabularies is the axis
// distinguishing them, and this helper's contract holds ONLY on the
// DISTINCT side of that partition. Sibling to the `_bijective` +
// `_pairwise_distinct` witnesses above on the SAME paired array — the
// three witnesses close complementary INJECTIVITY axes (per-column,
// per-tuple, per-CROSS-column) at `cargo check` time.
const _: () = assert_char_pair_array_columns_cross_disjoint(&Atom::NAMED_ESCAPE_TABLE);

/// Compile-time contract verifier — panics at const evaluation time if
/// the family-wide `[(char, char); N]` paired substrate array `arr` is
/// NOT byte-for-byte equal to the CONCATENATION of the peer paired
/// array `head` (contributing the FIRST `K` positions of `arr`
/// verbatim) followed by the DIAGONAL-EMBEDDING of the peer scalar
/// `[char; M]` array `tail_diag` (contributing the REMAINING `M = N -
/// K` positions as `(tail_diag[j], tail_diag[j])` at position `K + j`).
/// Binds ONE compound (SEGMENTED-CONCATENATION × DIAGONAL-EMBEDDING)
/// contract clause on the `(char, char)` product-element row of the
/// (element-type × contract-shape) matrix at a fresh
/// (concat-with-diagonal-tail) column — an ORDERING-SENSITIVE
/// SEGMENTED-POSITIONWISE contract joining the pre-existing
/// (pairwise-distinct), (bijective), (subset-embedding),
/// (disjointness), and (column-projection-equality) columns on the
/// SAME paired-array row.
///
/// Cardinality precondition: `K + M == N` — the caller passes the
/// three const parameters explicitly (`N`, `K`, `M`), and the helper's
/// FIRST arm fires at const-eval if the three fail to sum. A caller
/// who supplies mismatched arities (e.g. `<5, 3, 3>` — `K + M == 6 ≠
/// N == 5`) fails-loudly at the CARDINALITY-MISMATCH panic BEFORE the
/// sweep begins, so a mistyped ARITY doesn't degenerate into a silent
/// truncation of the paired array. Pinned by
/// `assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal_panics_at_runtime_on_cardinality_mismatch`.
///
/// Failure axes — the helper partitions its rejection surface into
/// FIVE disjoint arms, each with a DISTINCT axis-provenance prefix on
/// the panic message so downstream diagnostics route the drift back
/// to the specific SEGMENT and COLUMN that diverged:
///   1. `CARDINALITY-MISMATCH` — `K + M != N`.
///   2. `HEAD-SEGMENT-LEFT-DIVERGENCE` — some `i ∈ [0, K)` where
///      `arr[i].0 != head[i].0`.
///   3. `HEAD-SEGMENT-RIGHT-DIVERGENCE` — some `i ∈ [0, K)` where
///      `arr[i].1 != head[i].1`.
///   4. `DIAGONAL-TAIL-SEGMENT-LEFT-DIVERGENCE` — some `j ∈ [0, M)`
///      where `arr[K + j].0 != tail_diag[j]`.
///   5. `DIAGONAL-TAIL-SEGMENT-RIGHT-DIVERGENCE` — some `j ∈ [0, M)`
///      where `arr[K + j].1 != tail_diag[j]`.
///
/// Applied to the substrate's ([`Atom::ESCAPE_TABLE`],
/// [`Atom::NAMED_ESCAPE_TABLE`], [`Atom::SELF_ESCAPE_TABLE`]) triple
/// at the module-level `const _: () = assert_char_pair_array_is_
/// concatenation_of_char_pair_array_and_char_array_diagonal::<5, 3,
/// 2>(&Atom::ESCAPE_TABLE, &Atom::NAMED_ESCAPE_TABLE,
/// &Atom::SELF_ESCAPE_TABLE);` witness below the helper. Pre-lift,
/// the identity `Atom::ESCAPE_TABLE == Atom::NAMED_ESCAPE_TABLE ++
/// diagonal(Atom::SELF_ESCAPE_TABLE)` lived ONLY implicitly at
/// `Atom::ESCAPE_TABLE`'s declaration site (positions `[0..3]`
/// indexing `Self::NAMED_ESCAPE_TABLE[0]`, `[1]`, `[2]`; positions
/// `[3..5]` materializing `(Self::SELF_ESCAPE_TABLE[0], Self::SELF_
/// ESCAPE_TABLE[0])` + `(Self::SELF_ESCAPE_TABLE[1], Self::SELF_
/// ESCAPE_TABLE[1])`). Post-lift, that identity binds at `cargo
/// check` time — a regression that reorders `Atom::ESCAPE_TABLE`'s
/// segments, drifts one entry across the three arrays, or changes
/// the diagonal-embedding shape at the tail fails the build rather
/// than the test suite. The five prior paired-array witnesses on
/// `Atom::ESCAPE_TABLE` bind INDIVIDUAL axes (pairwise-distinct,
/// bijective) OR CROSS-ROW column-projection bonds
/// (columns-equal-peer-scalars), but NONE bind the SEGMENTED
/// composite-construction identity that this helper closes.
///
/// Contract-strength peer to [`assert_char_pair_array_columns_equal_
/// char_arrays`] on the (segmented-cross-row-bond vs full-cross-row-
/// bond) axis: where the sibling binds the FULL two-column bond
/// against TWO peer scalar arrays at EVERY position, this helper
/// binds the SEGMENTED composite-construction bond against a peer
/// PAIRED array (head) and a peer SCALAR array (diagonal tail) split
/// at position `K`. The two helpers together close the
/// (paired-vs-peer, cross-row-projection) 2-dimensional surface on
/// the `(char, char)` row at ONE `const _` line per compound-bond
/// theorem — the full-column peer binds every position at the
/// (char, char) row of a paired array against TWO scalar peer
/// vocabularies; THIS peer binds the head segment against a paired
/// vocabulary and the diagonal tail against a scalar vocabulary
/// (embedded diagonally). Row-parallel to the SCALAR-row helpers on
/// the (element-type) axis — where those close INJECTIVITY /
/// COVERING / PERMUTATION on the scalar rows, this closes the
/// SEGMENTED-CONCATENATION corner on the PRODUCT-element row.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — e.g. a REPL / LSP
/// tokenizer that constructs a `[(char, char); N]` paired array at
/// runtime and wants to verify SEGMENTED-CONCATENATION structure
/// before consuming it — and the panic surfaces normally in that
/// path. Every panic site names the helper AND identifies the failed
/// AXIS distinctly so downstream diagnostics route regressions back
/// to (a) the helper by string search on
/// `"assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal"`
/// and (b) the specific segment/column by axis-prefix.
///
/// Adding a new paired substrate array declared as CONCATENATION of a
/// peer paired vocabulary with a DIAGONAL-embedded peer scalar
/// vocabulary: pair the declaration with `const _: () = assert_char_
/// pair_array_is_concatenation_of_char_pair_array_and_char_array_
/// diagonal::<N, K, M>(&Self::FOO_TABLE, &Self::FOO_HEAD,
/// &Self::FOO_DIAG_TAIL);` co-located after the composite's
/// declaration and the compound identity binds at compile time
/// WITHOUT a runtime concat-and-zip loop.
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the SEGMENTED composite-
///   construction identity becomes a TYPE-LEVEL theorem carried per
///   declaration triple rather than a runtime concat-and-zip loop
///   the developer must remember to write per triple.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs;
///   the (head-segment, diagonal-tail-segment) composition proof at
///   declaration site AND the peer-vocabulary consumers regenerate
///   through the SAME `const _` witness.
/// - THEORY.md §VI.1 — generation over composition; the SEGMENTED
///   concat-and-diagonal-embed sweep IS the generative shape. Every
///   new paired-array declared as a segmented concat with a
///   diagonal-embedded scalar tail adds ONE `const _` line to get
///   the compound theorem.
pub const fn assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal<
    const N: usize,
    const K: usize,
    const M: usize,
>(
    arr: &[(char, char); N],
    head: &[(char, char); K],
    tail_diag: &[char; M],
) {
    if K + M != N {
        panic!(
            "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal: \
             CARDINALITY-MISMATCH — the three const parameters `N`, \
             `K`, `M` must satisfy `K + M == N` so the peer paired \
             `head` (contributing positions `[0..K)` of the composite \
             `arr`) followed by the peer scalar `tail_diag` (embedded \
             diagonally as `(tail_diag[j], tail_diag[j])` at positions \
             `[K..N)`) exactly cover `arr`'s `N` positions. Fix at the \
             `const _` witness's turbofish by reconciling the three \
             arities against the composite's declared arity. The \
             CARDINALITY-MISMATCH gate distinguishes THIS failure from \
             every content-drift arm — a mistyped ARITY on the caller \
             side fails HERE before any per-position sweep begins, so \
             a subtle arity slip doesn't silently degenerate into a \
             truncated segment sweep."
        );
    }
    let mut i = 0;
    while i < K {
        if arr[i].0 as u32 != head[i].0 as u32 {
            panic!(
                "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal: \
                 HEAD-SEGMENT-LEFT-DIVERGENCE — the composite paired \
                 array `arr` carries a LEFT-column entry at some \
                 position in `[0, K)` (the HEAD segment) that does NOT \
                 byte-for-byte equal the peer paired `head` array's \
                 LEFT-column entry at the SAME position. The \
                 substrate's SEGMENTED-CONCATENATION contract on the \
                 (composite, head-segment) HEAD-arm LEFT column is \
                 broken; every consumer that reads `arr[0..K)` and the \
                 peer `head` array as INTERCHANGEABLE (any outer-\
                 dispatch pattern-matcher on the head sub-vocabulary \
                 that expects the composite's HEAD segment to project \
                 verbatim to the peer paired vocabulary's LEFT column) \
                 relies on this invariant. Fix at one of the two \
                 declaration sites (`arr[0..K)` or `head`) by \
                 reconciling the entry across the two arrays."
            );
        }
        if arr[i].1 as u32 != head[i].1 as u32 {
            panic!(
                "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal: \
                 HEAD-SEGMENT-RIGHT-DIVERGENCE — the composite paired \
                 array `arr` carries a RIGHT-column entry at some \
                 position in `[0, K)` (the HEAD segment) that does NOT \
                 byte-for-byte equal the peer paired `head` array's \
                 RIGHT-column entry at the SAME position. The \
                 substrate's SEGMENTED-CONCATENATION contract on the \
                 (composite, head-segment) HEAD-arm RIGHT column is \
                 broken; every consumer that reads the composite's \
                 head-segment RIGHT column as INTERCHANGEABLE with the \
                 peer paired vocabulary's RIGHT column relies on this \
                 invariant. Fix at one of the two declaration sites \
                 (`arr[0..K)` or `head`) by reconciling the entry."
            );
        }
        i += 1;
    }
    let mut j = 0;
    while j < M {
        if arr[K + j].0 as u32 != tail_diag[j] as u32 {
            panic!(
                "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal: \
                 DIAGONAL-TAIL-SEGMENT-LEFT-DIVERGENCE — the composite \
                 paired array `arr` carries a LEFT-column entry at \
                 some position in `[K, N)` (the DIAGONAL TAIL segment) \
                 that does NOT byte-for-byte equal the peer scalar \
                 `tail_diag` array's entry at the SAME diagonal-\
                 embedded position. The substrate's DIAGONAL-EMBEDDING \
                 contract on the (composite, tail-segment) TAIL-arm \
                 LEFT column is broken; every consumer that reads \
                 `arr[K..N)` and the peer scalar `tail_diag` array as \
                 diagonally interchangeable (any outer-dispatch \
                 pattern-matcher on the tail sub-vocabulary that \
                 expects `arr[K + j]` to be `(tail_diag[j], \
                 tail_diag[j])`) relies on this invariant. Fix at one \
                 of the two declaration sites (`arr[K..N)` or \
                 `tail_diag`) by reconciling the entry."
            );
        }
        if arr[K + j].1 as u32 != tail_diag[j] as u32 {
            panic!(
                "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal: \
                 DIAGONAL-TAIL-SEGMENT-RIGHT-DIVERGENCE — the \
                 composite paired array `arr` carries a RIGHT-column \
                 entry at some position in `[K, N)` (the DIAGONAL TAIL \
                 segment) that does NOT byte-for-byte equal the peer \
                 scalar `tail_diag` array's entry at the SAME \
                 diagonal-embedded position. The substrate's DIAGONAL-\
                 EMBEDDING contract on the (composite, tail-segment) \
                 TAIL-arm RIGHT column is broken; every consumer that \
                 reads the composite's tail-segment RIGHT column as \
                 diagonally interchangeable with `tail_diag[j]` relies \
                 on this invariant. Fix at one of the two declaration \
                 sites (`arr[K..N)` or `tail_diag`) by reconciling the \
                 entry."
            );
        }
        j += 1;
    }
}

// Compile-time SEGMENTED-CONCATENATION-with-DIAGONAL-TAIL witness —
// one `const _: () = assert_char_pair_array_is_concatenation_of_char_
// pair_array_and_char_array_diagonal::<5, 3, 2>(&…, &…, &…)` binding
// the (`Atom::ESCAPE_TABLE`, `Atom::NAMED_ESCAPE_TABLE`,
// `Atom::SELF_ESCAPE_TABLE`) three-way composite-construction bond on
// the substrate's Str-payload escape-table vocabulary.
// `Atom::ESCAPE_TABLE` (`[(char, char); 5]`) is CONSTRUCTED as
// `NAMED_ESCAPE_TABLE[0..=2]` (the HEAD segment) followed by two
// SELF-diagonal pairs `(SELF_ESCAPE_TABLE[0], SELF_ESCAPE_TABLE[0])` +
// `(SELF_ESCAPE_TABLE[1], SELF_ESCAPE_TABLE[1])` (the DIAGONAL TAIL
// segment). Pre-lift, the SEGMENTED composite identity lived ONLY as
// an implicit declaration-site expression that a refactor could
// silently drift by reordering the HEAD entries, drifting one entry
// across the three arrays, or changing the diagonal-embedding shape
// at the tail — the pre-existing `_within_char_pair_finite_set`,
// `_arrays_disjoint`, `_bijective`, `_pairwise_distinct`, and
// `_columns_equal_char_arrays` witnesses each bind ADJACENT axes but
// NONE bind the composite-construction structural identity. Post-
// lift, this const-eval witness binds that identity as a compile-
// time theorem so a regression that renames a source or decoded byte
// on ONE of the three arrays without updating the other two, OR
// reorders the HEAD segment's positions, OR breaks the diagonal-
// embedding at the TAIL, fails the build rather than the test suite.
// SIXTH witness on the SAME paired array in complementary posture to
// the FIVE prior const-eval sweeps — the SIX sweeps enforce
// complementary axes of the same substrate table at SIX stages of
// the toolchain, so a build that skips tests still catches
// composite-construction drift here.
const _: () =
    assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal::<5, 3, 2>(
        &Atom::ESCAPE_TABLE,
        &Atom::NAMED_ESCAPE_TABLE,
        &Atom::SELF_ESCAPE_TABLE,
    );

/// Compile-time contract verifier — panics at const evaluation time if
/// the sub-slice `full[START..START + M)` of the family-wide `[(char,
/// char); N]` paired substrate array `full` is NOT byte-for-byte equal
/// to the peer `[(char, char); M]` paired sub-array `sub` at the
/// offset-matched positions. Binds ONE compound (SLICE × PAIRED-
/// POSITIONWISE-EQUALITY) contract on the `(char, char)` product-
/// element row of the (element-type × contract-shape) matrix at the
/// (SUB-SLICE ARRAY-image) column — opens the FOURTH element-type row
/// of that column peer to the pre-existing (u8) sibling
/// [`assert_u8_array_slice_equals_u8_array`], (char) sibling
/// [`assert_char_array_slice_equals_char_array`], and (str) sibling
/// [`assert_str_array_slice_equals_str_array`]. Together the four
/// helpers close the (SUB-SLICE ARRAY-image) column across the FULL
/// (u8, char, str, (char, char)) element-type row set of the
/// (element-type × contract-shape) matrix.
///
/// Bounds preconditions: `START ≤ N` (inclusive upper bound —
/// `START == N` combined with `M == 0` is the LEGAL empty-slice-at-
/// right-endpoint corner) AND `M ≤ N - START` (inclusive upper bound —
/// `M == N - START` is the LEGAL exact-fit-to-right-endpoint corner).
/// The two bounds gates fire IN ORDER — `START` is validated FIRST so
/// the peer `M` gate can safely evaluate `N - START` without `usize`
/// underflow. A caller-side turbofish arity slip fails-loudly on the
/// specific bounds axis it violated BEFORE the positionwise sweep
/// reads `full[START + i]`, so a bounds slip doesn't silently
/// degenerate into a subtraction wrap-around OR a panic deeper in
/// `full[START + i]` bounds-checking.
///
/// Failure axes — the helper partitions its rejection surface into
/// FOUR disjoint arms, each with a DISTINCT axis-provenance prefix on
/// the panic message so downstream diagnostics route the drift back
/// to the specific gate (and, on the CONTENT arms, the specific
/// COLUMN of the paired sub-slice) that diverged:
///   1. `START-OUT-OF-BOUNDS` — `START > N`.
///   2. `SLICE-LENGTH-OUT-OF-BOUNDS` — `M > N - START` (the peer
///      `START` gate above guarantees `N - START` never underflows).
///   3. `CHAR-PAIR-SLICE-EQUALS-ARRAY-LEFT-COLUMN-VIOLATION` — some
///      `i ∈ [0..M)` where `full[START + i].0 != sub[i].0` (LEFT
///      column of the paired positionwise sweep).
///   4. `CHAR-PAIR-SLICE-EQUALS-ARRAY-RIGHT-COLUMN-VIOLATION` — some
///      `i ∈ [0..M)` where `full[START + i].1 != sub[i].1` (RIGHT
///      column of the paired positionwise sweep).
///
/// The two CONTENT arms split by COLUMN in the SAME style as the
/// sibling (char, char)-row [`assert_char_pair_array_columns_equal_
/// char_arrays`] helper's `LEFT-COLUMN-DIVERGENCE` /
/// `RIGHT-COLUMN-DIVERGENCE` split, so a diagnostic that names the
/// failed axis routes UNAMBIGUOUSLY to (a) this specific (char, char)-
/// row SLICE-EQUALS-ARRAY helper by string search on the axis substring
/// `-CHAR-PAIR-SLICE-EQUALS-ARRAY-` (distinguishing it from the sibling
/// `-CHAR-SLICE-EQUALS-ARRAY-` (char) row axis and the plain `-SLICE-
/// EQUALS-ARRAY-` (u8) row axis) and (b) the failed COLUMN by the
/// `-LEFT-COLUMN-` / `-RIGHT-COLUMN-` infix. The shared `-SLICE-EQUALS-
/// ARRAY-VIOLATION` suffix lets callers grep any of the FOUR element-
/// type variants by ONE substring.
///
/// Applied to the substrate's (`Atom::ESCAPE_TABLE`,
/// `Atom::NAMED_ESCAPE_TABLE`) pair at ONE module-level `const _: () =
/// assert_char_pair_array_slice_equals_char_pair_array::<5, 3, 0>(&
/// Atom::ESCAPE_TABLE, &Atom::NAMED_ESCAPE_TABLE);` witness below the
/// helper. `Atom::ESCAPE_TABLE[0..3]` (`[(char, char); 3]` HEAD
/// segment) is byte-for-byte equal to `Atom::NAMED_ESCAPE_TABLE`
/// verbatim by declaration intent — the outer `ESCAPE_TABLE` array's
/// first three initializer slots each spell an entry drawn directly
/// from `NAMED_ESCAPE_TABLE`'s corresponding slot. Pre-lift, this
/// HEAD-segment positionwise-composition identity was bound TRANSITIVELY
/// through the sibling [`assert_char_pair_array_is_concatenation_of_
/// char_pair_array_and_char_array_diagonal`]`::<5, 3, 2>` witness on the
/// same three-array triple — that sibling binds the FULL composite
/// `ESCAPE_TABLE == NAMED_ESCAPE_TABLE ++ diagonal(SELF_ESCAPE_TABLE)`
/// so the HEAD is transitively bound alongside the DIAGONAL TAIL.
/// Post-lift, the HEAD-segment identity binds INDEPENDENTLY on its
/// OWN axis at ONE additional `const _` line — a regression that
/// silently broke the diagonal-tail binding (e.g. by swapping the
/// diagonal embedding to an anti-diagonal `(SELF[1], SELF[0])`)
/// would trip the sibling witness's `DIAGONAL-TAIL-*` arm alone;
/// this new witness continues to guarantee the HEAD-segment identity
/// on the CHAR-PAIR-SLICE-EQUALS-ARRAY-* axis regardless of the
/// tail's shape, so a HEAD-only drift (e.g. reordering the three
/// NAMED entries in ESCAPE_TABLE's initializer while leaving
/// NAMED_ESCAPE_TABLE's order intact) trips THIS witness's LEFT-
/// COLUMN / RIGHT-COLUMN axis on its OWN axis-provenance vocabulary.
/// The two witnesses partition the drift-detection surface by SEGMENT
/// (HEAD vs DIAGONAL TAIL) and by AXIS-PROVENANCE (SLICE-EQUALS-ARRAY
/// vs SEGMENTED-CONCATENATION-with-DIAGONAL-TAIL), catching each
/// SEGMENT's drift on the axis best suited to route the fix back to
/// the SPECIFIC declaration site at fault.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — e.g. a REPL / LSP
/// tokenizer that constructs a paired sub-array at runtime and wants
/// to verify SLICE-EQUALS-ARRAY structure before consuming it — and
/// the panic surfaces normally in that path (pinned by
/// `assert_char_pair_array_slice_equals_char_pair_array_panics_at_
/// runtime_on_left_column_drift`,
/// `assert_char_pair_array_slice_equals_char_pair_array_panics_at_
/// runtime_on_right_column_drift`,
/// `assert_char_pair_array_slice_equals_char_pair_array_panics_at_
/// runtime_on_start_out_of_bounds`,
/// `assert_char_pair_array_slice_equals_char_pair_array_panics_at_
/// runtime_on_slice_length_out_of_bounds`, and the two axis-
/// provenance pins on the LEFT-COLUMN + RIGHT-COLUMN axes).
///
/// Adding a new family-wide `[(char, char); N]` substrate array whose
/// sub-slice is byte-for-byte equal to a peer paired sub-vocabulary's
/// canonical `[(char, char); M]` listing: pair the declaration with
/// `const _: () = assert_char_pair_array_slice_equals_char_pair_array::
/// <N, M, START>(&Self::FOO_TABLE, &Self::FOO_SUB_TABLE);` co-located
/// after the composite's declaration and the compound identity binds
/// at compile time.
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the SLICE-EQUALS-ARRAY
///   positionwise-composition contract on the `(char, char)` paired
///   vocabulary becomes a TYPE-LEVEL theorem the substrate carries
///   per (container, sub-carving) pair rather than a runtime iterator
///   sweep the developer must remember to write per pair.
/// - THEORY.md §III — the typescape; the (element-type × contract-
///   shape) matrix now carries the (SUB-SLICE ARRAY-image) column
///   at ALL FOUR element-type rows — the (u8), (char), (str), and
///   `(char, char)` rows each ship a peer const-fn helper. The FOUR
///   helpers close the SUB-SLICE ARRAY-image column of the matrix.
/// - THEORY.md §VI.1 — generation over composition; the paired
///   positionwise sweep IS the generative shape. Every new paired
///   composite declared as a positionwise-composition against a peer
///   paired sub-vocabulary adds ONE `const _` line to get the
///   compound theorem rather than re-deriving a runtime
///   `full[START + i] == sub[i]` per-position sweep.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs; the
///   SUB-SLICE positionwise-composition proof at declaration site AND
///   the peer-sub-vocabulary consumers that read the composite's sub-
///   slice regenerate through the SAME `const _` witness.
pub const fn assert_char_pair_array_slice_equals_char_pair_array<
    const N: usize,
    const M: usize,
    const START: usize,
>(
    full: &[(char, char); N],
    sub: &[(char, char); M],
) {
    if START > N {
        panic!(
            "assert_char_pair_array_slice_equals_char_pair_array: \
             START-OUT-OF-BOUNDS — the const parameter `START` sits \
             OUTSIDE the outer array's valid position range `[0..N]` \
             (inclusive upper bound: `START == N` combined with `M == \
             0` is the LEGAL empty-slice-at-right-endpoint corner). \
             Fix at the `const _` witness's turbofish by reconciling \
             `START` against the outer array's declared arity `N`. \
             The START-OUT-OF-BOUNDS gate fires FIRST — a mistyped \
             `START` on the caller side fails HERE before the peer \
             `SLICE-LENGTH-OUT-OF-BOUNDS` gate reads `N - START` \
             (which would underflow `usize` had this gate not caught \
             the slip), so a subtle bounds slip doesn't silently \
             degenerate into a subtraction wrap-around OR a panic \
             deeper in `full[START + i]` bounds-checking."
        );
    }
    if M > N - START {
        panic!(
            "assert_char_pair_array_slice_equals_char_pair_array: \
             SLICE-LENGTH-OUT-OF-BOUNDS — the peer sub-array's arity \
             `M` exceeds the outer array's tail cardinality `N - \
             START`, so the positionwise sweep `full[START + i]` for \
             `i ∈ [0..M)` would overrun the outer array's valid \
             position range `[0..N)` at some `i ∈ [N - START..M)`. \
             Fix at the `const _` witness's turbofish by reconciling \
             `M` against the outer array's tail cardinality `N - \
             START` OR by narrowing `START` to leave a longer tail. \
             The peer `START-OUT-OF-BOUNDS` gate above guarantees \
             `START ≤ N` so `N - START` never underflows `usize` at \
             this gate. The LEGAL exact-fit corner `M == N - START` \
             (the sub-array reaches EXACTLY to the outer array's \
             right endpoint) is accepted; the STRICT `M > N - START` \
             slip is what this gate rejects."
        );
    }
    let mut i = 0;
    while i < M {
        if full[START + i].0 as u32 != sub[i].0 as u32 {
            panic!(
                "assert_char_pair_array_slice_equals_char_pair_array: \
                 CHAR-PAIR-SLICE-EQUALS-ARRAY-LEFT-COLUMN-VIOLATION — \
                 the outer `[(char, char); N]` paired array `full` \
                 carries a LEFT-column entry at some position `START + \
                 i` (for `i ∈ [0..M)`) that does NOT byte-equal the \
                 peer `[(char, char); M]` paired sub-array `sub` at \
                 the offset-matched position `i`. The substrate's \
                 (SLICE × PAIRED-POSITIONWISE-EQUALITY) contract on \
                 the LEFT column of the sub-slice `full[START..START + \
                 M) == sub[..]` is broken; every consumer that reads \
                 `full[START..START + M)`'s LEFT column as a \
                 positionwise-aligned copy of the peer paired sub-\
                 vocabulary's LEFT column (the substrate's Str-payload \
                 escape-table HEAD segment `Atom::ESCAPE_TABLE[0..3] \
                 == Atom::NAMED_ESCAPE_TABLE` — a regression that \
                 reordered ESCAPE_TABLE's first three initializer \
                 entries away from NAMED_ESCAPE_TABLE's canonical \
                 order without updating NAMED_ESCAPE_TABLE trips \
                 HERE on the LEFT column; any future container-array \
                 paired sub-slice byte-for-byte equal to a peer \
                 paired sub-vocabulary's canonical `[(char, char); \
                 M]` listing) relies on this invariant. Fix at the \
                 ARRAY-DECLARATION site (the drifted `full[START + \
                 i].0` slot inside the slice segment) OR at the peer \
                 paired sub-array's arm listing — the choice depends \
                 on whether the drift is an unintended slot reorder \
                 in the outer array's slice OR in the sub-carving's \
                 own listing. The LEFT-COLUMN-* axis prefix routes \
                 the fix specifically to the LEFT column of the \
                 paired sweep — a RIGHT-column drift would trip the \
                 peer RIGHT-COLUMN-* axis arm below on its OWN \
                 distinct axis-provenance vocabulary."
            );
        }
        if full[START + i].1 as u32 != sub[i].1 as u32 {
            panic!(
                "assert_char_pair_array_slice_equals_char_pair_array: \
                 CHAR-PAIR-SLICE-EQUALS-ARRAY-RIGHT-COLUMN-VIOLATION \
                 — the outer `[(char, char); N]` paired array `full` \
                 carries a RIGHT-column entry at some position `START \
                 + i` (for `i ∈ [0..M)`) that does NOT byte-equal the \
                 peer `[(char, char); M]` paired sub-array `sub` at \
                 the offset-matched position `i`. The substrate's \
                 (SLICE × PAIRED-POSITIONWISE-EQUALITY) contract on \
                 the RIGHT column of the sub-slice `full[START..START \
                 + M) == sub[..]` is broken; every consumer that \
                 reads `full[START..START + M)`'s RIGHT column as a \
                 positionwise-aligned copy of the peer paired sub-\
                 vocabulary's RIGHT column (the substrate's Str-\
                 payload escape-table HEAD segment `Atom::ESCAPE_\
                 TABLE[0..3] == Atom::NAMED_ESCAPE_TABLE` — a \
                 regression that drifted a DECODED byte across \
                 ESCAPE_TABLE and NAMED_ESCAPE_TABLE without updating \
                 the other trips HERE on the RIGHT column; any \
                 future container-array paired sub-slice byte-for-\
                 byte equal to a peer paired sub-vocabulary's \
                 canonical `[(char, char); M]` listing) relies on \
                 this invariant. Fix at the ARRAY-DECLARATION site \
                 (the drifted `full[START + i].1` slot inside the \
                 slice segment) OR at the peer paired sub-array's \
                 arm listing — the choice depends on whether the \
                 drift is an unintended slot rewrite in the outer \
                 array's slice OR in the sub-carving's own listing. \
                 The RIGHT-COLUMN-* axis prefix routes the fix \
                 specifically to the RIGHT column of the paired \
                 sweep — a LEFT-column drift would trip the peer \
                 LEFT-COLUMN-* axis arm above on its OWN distinct \
                 axis-provenance vocabulary."
            );
        }
        i += 1;
    }
}

// Compile-time SLICE-EQUALS-ARRAY witness — the ONE `(container, sub-
// carving)` pair on the substrate whose ARRAY-LEVEL structure composes
// a paired container-array sub-slice byte-for-byte identical to a
// peer paired sub-carving's canonical `[(char, char); M]` listing.
// `Atom::ESCAPE_TABLE[0..3]` (the three-slot NAMED-escape HEAD segment
// of the outer five-slot Str-payload escape-table array) is byte-for-
// byte equal to `Atom::NAMED_ESCAPE_TABLE` verbatim — the outer
// ESCAPE_TABLE array's first three initializer slots each spell an
// entry drawn directly from NAMED_ESCAPE_TABLE's corresponding slot.
// Pre-lift, this HEAD-segment positionwise-composition identity was
// bound TRANSITIVELY through the sibling `assert_char_pair_array_is_
// concatenation_of_char_pair_array_and_char_array_diagonal::<5, 3, 2>`
// witness at line ~3909 above (that sibling binds the FULL composite
// `ESCAPE_TABLE == NAMED_ESCAPE_TABLE ++ diagonal(SELF_ESCAPE_TABLE)`
// so the HEAD segment is bound alongside the DIAGONAL TAIL through a
// single composite-construction proof); post-lift, the HEAD segment
// binds INDEPENDENTLY on the (SLICE × PAIRED-POSITIONWISE-EQUALITY)
// axis at ONE additional `const _` line, routing any HEAD-only drift
// (e.g. reordering ESCAPE_TABLE's first three initializer entries
// while leaving NAMED_ESCAPE_TABLE's order intact) through the
// CHAR-PAIR-SLICE-EQUALS-ARRAY-LEFT-COLUMN / -RIGHT-COLUMN axis-
// provenance vocabulary rather than the sibling's `HEAD-SEGMENT-
// LEFT-DIVERGENCE` / `HEAD-SEGMENT-RIGHT-DIVERGENCE` axis-
// provenance vocabulary. The two witnesses partition the drift-
// detection surface by SEGMENT and AXIS-PROVENANCE.
//
// Sibling posture to the FOUR (str)-row per-position witnesses on
// `crate::error::SexpShape::LABELS` in `error.rs` (four
// `assert_str_array_slice_equals_str_array::<12, {1,3,4,6,8,12},
// {0,1,7,8}>` witnesses that positionally decompose the twelve-slot
// LABELS parent array against its four sub-carvings' LABELS arrays)
// and to the TWO singleton + ONE four-slot (u8)-row witnesses on
// `SexpShape::HASH_DISCRIMINATORS` in this file. Those siblings each
// carry the sub-carving-projection SLICE-EQUALS-ARRAY sweep at the
// (u8) row and the (str) row of the (SUB-SLICE ARRAY-image) column;
// this witness opens the SAME sweep at the `(char, char)` product-
// element row on the SAME column. Together the (u8, char, str, (char,
// char)) FOUR-row column closure carries the (SUB-SLICE ARRAY-image)
// column of the (element-type × contract-shape) matrix across the
// FULL element-type row set the substrate declares family-wide
// arrays for at rustc time.
const _: () = assert_char_pair_array_slice_equals_char_pair_array::<5, 3, 0>(
    &Atom::ESCAPE_TABLE,
    &Atom::NAMED_ESCAPE_TABLE,
);

/// Compile-time contract verifier — panics at const evaluation time if
/// the family-wide `[char; N]` scalar substrate array `arr` is NOT byte-
/// for-byte equal to the CONCATENATION of the SELECTED COLUMN of the
/// peer paired `[(char, char); K]` array `head_table` (contributing the
/// FIRST `K` positions of `arr` verbatim as either
/// `head_table[i].0` — LEFT column when `take_right_column == false` —
/// or `head_table[i].1` — RIGHT column when `take_right_column == true`)
/// followed by the peer scalar `[char; M]` array `tail` (contributing
/// the REMAINING `M = N - K` positions verbatim at position `K + j`).
/// Binds ONE compound (SEGMENTED-CONCATENATION × PAIRED-COLUMN-
/// PROJECTION) contract clause on the (char) scalar-element row of the
/// (element-type × contract-shape) matrix at a fresh (concat-through-
/// paired-column-projection) column — an ORDERING-SENSITIVE SEGMENTED-
/// POSITIONWISE contract joining the pre-existing (pairwise-distinct),
/// (arrays-disjoint), and (within-char-finite-set) columns on the SAME
/// (char) scalar-element row.
///
/// Cardinality precondition: `K + M == N` — the caller passes the
/// three const parameters explicitly (`N`, `K`, `M`), and the helper's
/// FIRST arm fires at const-eval if the three fail to sum. A caller
/// who supplies mismatched arities (e.g. `<5, 3, 3>` — `K + M == 6 ≠
/// N == 5`) fails-loudly at the CARDINALITY-MISMATCH panic BEFORE the
/// sweep begins, so a mistyped ARITY doesn't degenerate into a silent
/// truncation of the scalar composite array. Sibling-shape to the
/// paired-row helper [`assert_char_pair_array_is_concatenation_of_
/// char_pair_array_and_char_array_diagonal`]'s `CARDINALITY-MISMATCH`
/// pre-arm on the SAME cardinality axis.
///
/// Failure axes — the helper partitions its rejection surface into
/// FOUR disjoint arms, each with a DISTINCT axis-provenance prefix on
/// the panic message so downstream diagnostics route the drift back
/// to the specific SEGMENT (and, on the HEAD arm, the specific
/// COLUMN) that diverged:
///   1. `CARDINALITY-MISMATCH` — `K + M != N`.
///   2. `HEAD-SEGMENT-LEFT-COLUMN-DIVERGENCE` — `take_right_column ==
///      false` AND some `i ∈ [0, K)` where `arr[i] != head_table[i].0`.
///   3. `HEAD-SEGMENT-RIGHT-COLUMN-DIVERGENCE` — `take_right_column ==
///      true` AND some `i ∈ [0, K)` where `arr[i] != head_table[i].1`.
///   4. `TAIL-SEGMENT-DIVERGENCE` — some `j ∈ [0, M)` where
///      `arr[K + j] != tail[j]` (INDEPENDENT of `take_right_column`
///      since the tail is a scalar `[char; M]` array projected verbatim,
///      not through a paired column).
///
/// Applied to the substrate's ([`Atom::ESCAPE_SOURCES`],
/// [`Atom::NAMED_ESCAPE_TABLE`], [`Atom::SELF_ESCAPE_TABLE`]) triple
/// (LEFT-column projection) AND the ([`Atom::ESCAPE_DECODED`],
/// [`Atom::NAMED_ESCAPE_TABLE`], [`Atom::SELF_ESCAPE_TABLE`]) triple
/// (RIGHT-column projection) at TWO module-level `const _: () =
/// assert_char_array_is_concatenation_of_char_pair_array_column_and_
/// char_array::<5, 3, 2>(&…, &Atom::NAMED_ESCAPE_TABLE,
/// &Atom::SELF_ESCAPE_TABLE, take_right_column);` witnesses below
/// the helper. Pre-lift, the composition law
/// ```ignore
/// ESCAPE_SOURCES  == [NAMED_ESCAPE_TABLE[0].0, NAMED_ESCAPE_TABLE[1].0,
///                     NAMED_ESCAPE_TABLE[2].0, SELF_ESCAPE_TABLE[0],
///                     SELF_ESCAPE_TABLE[1]]
/// ESCAPE_DECODED  == [NAMED_ESCAPE_TABLE[0].1, NAMED_ESCAPE_TABLE[1].1,
///                     NAMED_ESCAPE_TABLE[2].1, SELF_ESCAPE_TABLE[0],
///                     SELF_ESCAPE_TABLE[1]]
/// ```
/// lived ONLY as PROSE at [`Atom::ESCAPE_SOURCES`]'s and
/// [`Atom::ESCAPE_DECODED`]'s docstrings (each explicitly names the
/// "NAMED-column prefix + SELF-column suffix" partition) plus as an
/// implicit transitive consequence of the pre-existing
/// (`_columns_equal_char_arrays` on `ESCAPE_TABLE` against the two
/// scalar peer columns) + (`_is_concatenation_of_char_pair_array_and_
/// char_array_diagonal` on `ESCAPE_TABLE` against `NAMED_ESCAPE_TABLE`
/// and diagonal-embedded `SELF_ESCAPE_TABLE`) witness pair. Neither
/// pre-existing witness DIRECTLY binds the scalar-projection identity
/// on `ESCAPE_SOURCES` and `ESCAPE_DECODED` at the char-array level
/// — the two scalar arrays could be independently mutated (e.g.
/// reorder `ESCAPE_SOURCES`'s five entries so its LEFT-column is no
/// longer NAMED-source-prefix + SELF-suffix in the canonical order)
/// while both prior witnesses continue to hold on the paired
/// `ESCAPE_TABLE`. Post-lift, that scalar-projection identity binds
/// at `cargo check` time — a regression that reorders EITHER of the
/// two scalar arrays' entries away from the "NAMED-column-prefix +
/// SELF-suffix" partition, drifts one entry across NAMED_ESCAPE_TABLE
/// and its scalar-column projection, or breaks the SELF-suffix
/// verbatim-embedding at the tail, fails the build rather than the
/// test suite.
///
/// Contract-strength peer to [`assert_char_pair_array_is_
/// concatenation_of_char_pair_array_and_char_array_diagonal`] on the
/// (scalar-vs-paired composite element type) axis: where the sibling
/// binds the paired composite's SEGMENTED-CONCATENATION identity
/// against a paired HEAD and a DIAGONAL-EMBEDDED scalar TAIL at the
/// (char, char) row, this helper binds the SCALAR composite's
/// SEGMENTED-CONCATENATION identity against a SELECTED COLUMN of a
/// paired HEAD and a VERBATIM scalar TAIL at the (char) row. The two
/// helpers together close the CROSS-ROW SEGMENTED-CONCATENATION
/// surface across the (char, char) × (char) element-type product:
///   * `[(char, char); N] == [(char, char); K] ++ diagonal([char; M])`
///     at the paired-row diagonal-tail helper (existing);
///   * `[char; N] == col(paired [(char, char); K]) ++ [char; M]` at
///     the scalar-row column-projection helper (this one).
///
/// Both helpers compose against the SAME
/// ([`Atom::NAMED_ESCAPE_TABLE`], [`Atom::SELF_ESCAPE_TABLE`]) peer
/// pair — the paired-row helper reads `NAMED_ESCAPE_TABLE`'s BOTH
/// columns verbatim into `ESCAPE_TABLE[0..3]` + a diagonal embedding
/// of `SELF_ESCAPE_TABLE` at `ESCAPE_TABLE[3..5]`; this scalar-row
/// helper reads ONE column of `NAMED_ESCAPE_TABLE` into `ESCAPE_
/// SOURCES[0..3]` / `ESCAPE_DECODED[0..3]` + `SELF_ESCAPE_TABLE`
/// verbatim into positions `[3..5]`. The two-witness closure over
/// `take_right_column ∈ {false, true}` bonds the (LEFT, RIGHT)
/// scalar-column projection pair at ONE const-eval sweep per column,
/// binding TWO substrate composition laws through the SAME primitive.
///
/// The `take_right_column: bool` parameter routes the head-segment
/// sweep to the corresponding column of the paired `head_table`:
///   * `false` selects LEFT (`head_table[i].0`) — the pattern-SOURCE
///     column (the byte the reader sees BEFORE decoding an escape).
///   * `true` selects RIGHT (`head_table[i].1`) — the pattern-DECODED
///     column (the byte the reader emits AFTER decoding an escape).
///
/// The runtime bool composes with const-eval so BOTH substrate
/// witnesses (LEFT for `ESCAPE_SOURCES`, RIGHT for `ESCAPE_DECODED`)
/// share ONE primitive definition — halving the per-helper source
/// surface while keeping the per-column panic message DISTINCT via
/// the two `HEAD-SEGMENT-LEFT-COLUMN-DIVERGENCE` /
/// `HEAD-SEGMENT-RIGHT-COLUMN-DIVERGENCE` axes.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — e.g. a REPL / LSP
/// tokenizer that constructs a scalar `[char; N]` composite from a
/// paired-column projection AND a scalar peer tail at runtime and
/// wants to verify SEGMENTED-CONCATENATION structure before consuming
/// it. Every panic site names the helper AND identifies the failed
/// AXIS distinctly so downstream diagnostics route regressions back
/// to (a) the helper by string search on
/// `"assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array"`
/// and (b) the specific segment/column by axis-prefix. The four axis-
/// provenance strings (`CARDINALITY-MISMATCH`, `HEAD-SEGMENT-LEFT-
/// COLUMN-DIVERGENCE`, `HEAD-SEGMENT-RIGHT-COLUMN-DIVERGENCE`, `TAIL-
/// SEGMENT-DIVERGENCE`) are chosen DISTINCT from every sibling
/// helper's axis vocabulary (`HEAD-SEGMENT-LEFT-DIVERGENCE` /
/// `HEAD-SEGMENT-RIGHT-DIVERGENCE` / `DIAGONAL-TAIL-SEGMENT-LEFT-
/// DIVERGENCE` / `DIAGONAL-TAIL-SEGMENT-RIGHT-DIVERGENCE` on the
/// paired-row diagonal-tail sibling; `LEFT-COLUMN-DIVERGENCE` /
/// `RIGHT-COLUMN-DIVERGENCE` on the paired-row `_columns_equal_char_
/// arrays` sibling) so a diagnostic that names the failed axis routes
/// UNAMBIGUOUSLY to (a) this specific (char) scalar-row
/// column-projection concatenation helper, (b) the failed SEGMENT
/// (HEAD vs TAIL), (c) the failed COLUMN on the HEAD segment (LEFT
/// vs RIGHT). The `-COLUMN-` infix distinguishes this helper's HEAD
/// arms from the sibling paired-row diagonal-tail helper's HEAD arms
/// on any downstream substring search.
///
/// Adding a new scalar `[char; N]` substrate array declared as
/// CONCATENATION of a SELECTED COLUMN of a peer paired `[(char,
/// char); K]` vocabulary with a peer scalar `[char; M]` tail (e.g. a
/// future extension to `Atom::decode_str_escape` whose SOURCE or
/// DECODED SPAN grows through a new NAMED-column-prefix + SELF-suffix
/// partition): pair the declaration with `const _: () = assert_char_
/// array_is_concatenation_of_char_pair_array_column_and_char_array::
/// <N, K, M>(&Self::FOO_SPAN, &Self::FOO_TABLE, &Self::FOO_TAIL,
/// take_right_column);` co-located after the composite's
/// declaration and the compound identity binds at compile time
/// WITHOUT a runtime concat-and-project loop.
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the SEGMENTED composite-
///   construction identity on the CROSS-ROW (paired → scalar) column-
///   projection axis becomes a TYPE-LEVEL theorem carried per
///   declaration triple rather than a runtime concat-and-project loop
///   the developer must remember to write per triple.
/// - THEORY.md §III — the typescape; the (element-type × contract-
///   shape) matrix now carries the CROSS-ROW (paired-column ⊕
///   scalar-tail → scalar-composite) segmented-concatenation corner
///   at ONE peer const-fn helper. Combined with the pre-existing
///   (char, char)-row diagonal-tail sibling, the two helpers close
///   the CROSS-ROW SEGMENTED-CONCATENATION face of the substrate's
///   Str-payload escape-table product-vocabulary.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs; the
///   (paired-column-head-segment, scalar-tail-segment) composition
///   proof at declaration site AND the peer-vocabulary consumers
///   regenerate through the SAME `const _` witness at the (char)
///   scalar row.
/// - THEORY.md §VI.1 — generation over composition; the paired-
///   column-project + scalar-verbatim-copy sweep IS the generative
///   shape. Every new scalar-composite declared as a segmented
///   concatenation-through-column-projection adds ONE `const _` line
///   to get the compound theorem.
///
/// Frontier inspiration: MLIR's typed IR-rewriter pattern of
/// projecting a wider tuple-typed operation into its per-column
/// scalar residual through a rewrite pass. Where MLIR routes the
/// projection through a Pass-driven rewrite that fires at IR
/// compilation, this helper routes the projection through a rustc
/// const-eval-time proof obligation at every scalar-composite
/// declaration site — the composition law binds as a type-level
/// theorem at `cargo check` rather than as an IR-rewrite-time check
/// deferred to a compilation stage the substrate's `pub const`
/// declarations never enter.
pub const fn assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array<
    const N: usize,
    const K: usize,
    const M: usize,
>(
    arr: &[char; N],
    head_table: &[(char, char); K],
    tail: &[char; M],
    take_right_column: bool,
) {
    if K + M != N {
        panic!(
            "assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array: \
             CARDINALITY-MISMATCH — the three const parameters `N`, \
             `K`, `M` must satisfy `K + M == N` so the SELECTED column \
             projection of the peer paired `head_table` (contributing \
             positions `[0..K)` of the composite scalar `arr`) followed \
             by the peer scalar `tail` (contributing positions `[K..N)` \
             of `arr` verbatim) exactly cover `arr`'s `N` positions. \
             Fix at the `const _` witness's turbofish by reconciling \
             the three arities against the composite's declared arity. \
             The CARDINALITY-MISMATCH gate distinguishes THIS failure \
             from every content-drift arm — a mistyped ARITY on the \
             caller side fails HERE before any per-position sweep \
             begins, so a subtle arity slip doesn't silently degenerate \
             into a truncated segment sweep."
        );
    }
    let mut i = 0;
    while i < K {
        if take_right_column {
            if arr[i] as u32 != head_table[i].1 as u32 {
                panic!(
                    "assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array: \
                     HEAD-SEGMENT-RIGHT-COLUMN-DIVERGENCE — the \
                     composite scalar array `arr` carries an entry at \
                     some position in `[0, K)` (the HEAD segment) that \
                     does NOT byte-for-byte equal the peer paired \
                     `head_table` array's RIGHT-column entry at the \
                     SAME position (i.e. `arr[i] != head_table[i].1`). \
                     The substrate's SEGMENTED-CONCATENATION-through-\
                     PAIRED-COLUMN-PROJECTION contract on the \
                     (composite scalar, head-segment) HEAD-arm RIGHT \
                     column is broken; every consumer that reads \
                     `arr[0..K)` and the RIGHT-column projection of \
                     `head_table` as INTERCHANGEABLE (any outer-\
                     dispatch pattern-matcher on the head sub-\
                     vocabulary that expects the composite's HEAD \
                     segment to project verbatim to the peer paired \
                     vocabulary's RIGHT column) relies on this \
                     invariant. Fix at one of the two declaration \
                     sites (`arr[0..K)` or `head_table`) by reconciling \
                     the entry across the two arrays."
                );
            }
        } else if arr[i] as u32 != head_table[i].0 as u32 {
            panic!(
                "assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array: \
                 HEAD-SEGMENT-LEFT-COLUMN-DIVERGENCE — the composite \
                 scalar array `arr` carries an entry at some position \
                 in `[0, K)` (the HEAD segment) that does NOT byte-for-\
                 byte equal the peer paired `head_table` array's LEFT-\
                 column entry at the SAME position (i.e. `arr[i] != \
                 head_table[i].0`). The substrate's SEGMENTED-\
                 CONCATENATION-through-PAIRED-COLUMN-PROJECTION \
                 contract on the (composite scalar, head-segment) \
                 HEAD-arm LEFT column is broken; every consumer that \
                 reads `arr[0..K)` and the LEFT-column projection of \
                 `head_table` as INTERCHANGEABLE (any outer-dispatch \
                 pattern-matcher on the head sub-vocabulary that \
                 expects the composite's HEAD segment to project \
                 verbatim to the peer paired vocabulary's LEFT column) \
                 relies on this invariant. Fix at one of the two \
                 declaration sites (`arr[0..K)` or `head_table`) by \
                 reconciling the entry across the two arrays."
            );
        }
        i += 1;
    }
    let mut j = 0;
    while j < M {
        if arr[K + j] as u32 != tail[j] as u32 {
            panic!(
                "assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array: \
                 TAIL-SEGMENT-DIVERGENCE — the composite scalar array \
                 `arr` carries an entry at some position in `[K, N)` \
                 (the TAIL segment) that does NOT byte-for-byte equal \
                 the peer scalar `tail` array's entry at the SAME \
                 position offset (i.e. `arr[K + j] != tail[j]`). The \
                 substrate's SEGMENTED-CONCATENATION-through-PAIRED-\
                 COLUMN-PROJECTION contract on the (composite scalar, \
                 tail-segment) TAIL-arm is broken; every consumer that \
                 reads `arr[K..N)` and the peer scalar `tail` array as \
                 verbatim-interchangeable relies on this invariant. \
                 Fix at one of the two declaration sites (`arr[K..N)` \
                 or `tail`) by reconciling the entry. The TAIL-SEGMENT \
                 arm is INDEPENDENT of `take_right_column` because the \
                 tail is a scalar array projected verbatim into the \
                 composite rather than routed through a paired-column \
                 projection at the head."
            );
        }
        j += 1;
    }
}

// Compile-time SEGMENTED-CONCATENATION-through-PAIRED-COLUMN-PROJECTION
// witnesses — two `const _: () = assert_char_array_is_concatenation_
// of_char_pair_array_column_and_char_array::<5, 3, 2>(&…, &Atom::
// NAMED_ESCAPE_TABLE, &Atom::SELF_ESCAPE_TABLE, take_right_column)`
// lines binding the (`Atom::ESCAPE_SOURCES`, `Atom::NAMED_ESCAPE_TABLE`,
// `Atom::SELF_ESCAPE_TABLE`) LEFT-column-projection triple AND the
// (`Atom::ESCAPE_DECODED`, `Atom::NAMED_ESCAPE_TABLE`,
// `Atom::SELF_ESCAPE_TABLE`) RIGHT-column-projection triple on the
// substrate's Str-payload escape-table product-vocabulary at ONE
// const-eval sweep per scalar-column projection. `Atom::ESCAPE_SOURCES`
// (`[char; 5]`) is CONSTRUCTED as `NAMED_ESCAPE_TABLE`'s LEFT-column
// projection at positions `[0..3]` followed by `SELF_ESCAPE_TABLE`
// verbatim at positions `[3..5]`; `Atom::ESCAPE_DECODED` (`[char; 5]`)
// is CONSTRUCTED as `NAMED_ESCAPE_TABLE`'s RIGHT-column projection at
// positions `[0..3]` followed by `SELF_ESCAPE_TABLE` verbatim at
// positions `[3..5]` (SELF's pattern-EQUALS-value property collapses
// the SELF-column-projection into SELF-verbatim on BOTH scalar
// composite arrays). Pre-lift, the two scalar-projection identities
// lived ONLY as PROSE at [`Atom::ESCAPE_SOURCES`]'s and
// [`Atom::ESCAPE_DECODED`]'s docstrings AND as implicit transitive
// consequences of the pre-existing (`_columns_equal_char_arrays` on
// `ESCAPE_TABLE` against the two scalar peer columns) +
// (`_is_concatenation_of_char_pair_array_and_char_array_diagonal` on
// `ESCAPE_TABLE` against `NAMED_ESCAPE_TABLE` and diagonal-embedded
// `SELF_ESCAPE_TABLE`) witness pair — neither pre-existing witness
// DIRECTLY binds the scalar-projection identity on the two `[char; 5]`
// scalar composite arrays at the char-array level. Post-lift, the two
// scalar-projection identities bind at `cargo check` time — a
// regression that reorders EITHER scalar composite's five entries so
// its NAMED-column-prefix + SELF-suffix partition breaks, drifts one
// entry across NAMED_ESCAPE_TABLE and its scalar-column projection, or
// silently drops a SELF-suffix entry from EITHER scalar composite,
// fails the build rather than the test suite. Sibling to the pre-
// existing (`_pairwise_distinct` on `ESCAPE_SOURCES` +
// `_pairwise_distinct` on `ESCAPE_DECODED` +
// `_within_char_finite_set` on `ESCAPE_SOURCES` +
// `_within_char_finite_set` on `ESCAPE_DECODED`) witnesses above on
// the SAME two scalar arrays — the four prior witnesses bind SET-level
// axes (INJECTIVITY, SUBSET-EMBEDDING) at the scalar-composite level
// without pinning the SEGMENTED-CONCATENATION structural identity;
// these two new witnesses close that structural identity as compile-
// time theorems on the SAME two scalar arrays. The four SET-level
// axes on the two scalar arrays combine with the two SEGMENTED-
// CONCATENATION axes here to give downstream consumers a SIX-witness
// closure on each scalar composite (four SET-level axes plus the
// SEGMENTED structural axis routing through EITHER the LEFT-column or
// RIGHT-column projection of the peer paired vocabulary).
const _: () = assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array::<5, 3, 2>(
    &Atom::ESCAPE_SOURCES,
    &Atom::NAMED_ESCAPE_TABLE,
    &Atom::SELF_ESCAPE_TABLE,
    false,
);
const _: () = assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array::<5, 3, 2>(
    &Atom::ESCAPE_DECODED,
    &Atom::NAMED_ESCAPE_TABLE,
    &Atom::SELF_ESCAPE_TABLE,
    true,
);

/// Compile-time contract verifier — panics at const evaluation time if
/// the distinct-values set of `arr` does not equal exactly the inclusive
/// range `{LO..=HI}` on the substrate's `u8` cache-key vocabulary. Binds
/// TWO conjunct clauses at ONE `const _` line:
///   1. RANGE-BOUND: every entry lies within `[LO, HI]` — no byte
///      outside the target partition. A regression that drifts ONE
///      entry above `HI` or below `LO` (e.g. lifts a fresh entry at
///      `7u8` on a `{0..=6}` array) fails-loudly at const-eval.
///   2. FULL-COVERAGE: every byte in `[LO..=HI]` appears at least once
///      in `arr` — no byte inside the target partition missing. A
///      regression that silently unifies two entries onto ONE byte,
///      leaving another byte in the range unreached (e.g. drops the
///      `Nil` arm's `0u8` from `SexpShape::HASH_DISCRIMINATORS` in
///      favour of a redundant `1u8`), fails-loudly at const-eval too.
///
/// The RANGE-COVERAGE contract is a NON-INJECTIVE peer of the
/// pre-existing pairwise-DISTINCTNESS contract
/// ([`assert_u8_array_pairwise_distinct`]) on the SAME `u8` cache-key
/// vocabulary: where distinctness is the INJECTIVITY axis (every entry
/// unique), range-coverage is the SURJECTIVITY-onto-a-range axis (every
/// range byte reached, entries CAN duplicate). Applied to arrays where
/// duplicates are load-bearing by construction — [`SexpShape::
/// HASH_DISCRIMINATORS`](crate::error::SexpShape::HASH_DISCRIMINATORS)
/// (`[u8; 12]` covering `{0..=6}` with SIX atomic-shape arms all
/// collapsing to the outer Atom marker byte `1u8`) is the archetype
/// case, intentionally omitted from the distinctness sweep per the
/// twelve-shape → seven-byte collapse rule documented on the
/// pairwise-distinct helper above; this range-coverage helper binds
/// the outer-partition contract at compile time despite the six-fold
/// collapse.
///
/// The invariant is load-bearing for the outer-`Sexp` cache-key
/// algebra's SPAN across the shape-level projection surface. The
/// twelve-arm sweep of `SexpShape::HASH_DISCRIMINATORS` MUST cover
/// exactly the outer discriminator space `{0..=6}` — no byte outside
/// (a `7u8` drift would introduce an unreachable cache slot for
/// [`crate::macro_expand::Expander::cache`]), no byte inside missing
/// (a `2u8` drop would silently unhash every `Sexp::List(_)` through
/// whatever cache slot the drift routes to). Every future family-wide
/// `[u8; N]` array whose distinct-value set is an intentionally-
/// closed inclusive range participates in the SAME compile-time
/// guarantee via one `const _` line.
///
/// Adding a new family-wide `[u8; N]` range-covering array to the
/// substrate: pair the declaration with `const _: () =
/// assert_u8_array_covers_inclusive_range::<N, LO, HI>(&Self::FOO_
/// ARRAY);` co-located after the array's declaration and the range-
/// coverage contract binds at compile time. The rustc-forced arity
/// `[u8; N]` composes with this const-eval sweep so cardinality AND
/// range-bound AND full-coverage are ALL compile-time theorems on the
/// SAME array.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — pinned by
/// `assert_u8_array_covers_inclusive_range_panics_at_runtime_on_
/// out_of_range_entry` + `assert_u8_array_covers_inclusive_range_
/// panics_at_runtime_on_missing_range_byte`. Both panic sites carry
/// axis-provenance strings so downstream diagnostics (`cargo check`
/// const-eval error output, test-suite failure reports) route the
/// drift back to the failed axis (RANGE-BOUND vs. FULL-COVERAGE) by
/// string search — halving the search space for the operator
/// debugging the drift.
///
/// Cross-argument constraint: `LO <= HI` is required — a caller who
/// passes `LO > HI` fails-loudly at the first `LO..=HI` sweep step
/// (the `while cur <= HI` guard rejects immediately) with a
/// well-defined "empty range" outcome that is nonetheless surfaced as
/// a full-coverage failure since `arr` must then be empty (`N == 0`).
/// The three-parameter shape `(N, LO, HI)` composes rustc's forced
/// arity `[u8; N]` with the two const-parameter bounds so ALL THREE
/// invariants (cardinality, min-bound, max-bound) are compile-time
/// theorems on the SAME `const _` line.
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the family-wide range-
///   coverage contract on the `u8` cache-key vocabulary becomes a
///   TYPE-LEVEL theorem the substrate carries per array declaration
///   rather than a runtime test the developer must remember to write
///   per array (one range-bound sweep + one full-coverage sweep).
/// - THEORY.md §V.3 — three-pillar attestation; the outer-`Sexp`
///   cache-key partition is the `intent_hash` composition axis —
///   binding the range-coverage arrays on the typed algebra makes
///   attestation-key drift a compile error rather than a silent
///   BLAKE3 mis-hash on any consumer keyed on `Hash for Sexp`. A
///   regression that drops a byte from the outer partition (or adds
///   an out-of-range byte) fails the build before it can silently
///   invalidate a cached expansion or a Sekiban audit-trail metric
///   keyed on the outer discriminator space.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   range-and-coverage sweep IS the generative shape. Every new
///   closed-set discriminator array whose distinct-value set is an
///   intentionally-closed inclusive range adds ONE `const _` line to
///   get the range-coverage theorem rather than re-deriving two
///   per-array runtime iterator sweeps (one for the range bound, one
///   for the coverage completeness).
///
/// Element-type sibling posture to the four pre-existing const-fn
/// contract verifiers ([`assert_char_array_pairwise_distinct`],
/// [`assert_str_array_pairwise_distinct`],
/// [`assert_u8_array_pairwise_distinct`],
/// [`assert_char_pair_array_bijective`]): where the four
/// distinctness/bijectivity helpers close the INJECTIVITY axis of the
/// substrate's typed-array vocabulary, this range-coverage helper
/// opens the SURJECTIVITY-onto-a-range axis on the SAME `u8` cache-key
/// element type — extending the family-wide contract-verifier surface
/// past the closed-set distinctness axis onto the closed-set covering
/// axis.
pub const fn assert_u8_array_covers_inclusive_range<const N: usize, const LO: u8, const HI: u8>(
    arr: &[u8; N],
) {
    let mut i = 0;
    while i < N {
        if arr[i] < LO || arr[i] > HI {
            panic!(
                "assert_u8_array_covers_inclusive_range: family-wide \
                 u8 array carries an OUT-OF-RANGE entry at some \
                 position — the entry's byte lies outside the target \
                 inclusive range `[LO, HI]`. The substrate's RANGE-\
                 BOUND contract on the array is broken; every \
                 consumer that expects the array's entries to \
                 partition an outer cache-key space (Hash for Sexp's \
                 outer discriminator space, StructuralKind / \
                 AtomKind / QuoteForm sub-carving spaces) relies on \
                 the entries staying within the target range",
            );
        }
        i += 1;
    }
    let mut cur = LO;
    loop {
        let mut k = 0;
        let mut found = false;
        while k < N {
            if arr[k] == cur {
                found = true;
                break;
            }
            k += 1;
        }
        if !found {
            panic!(
                "assert_u8_array_covers_inclusive_range: family-wide \
                 u8 array is MISSING a byte from the target inclusive \
                 range `[LO, HI]` — every byte in the range must \
                 appear at least once in the array. The substrate's \
                 FULL-COVERAGE contract on the array is broken; every \
                 consumer that expects the array's distinct-value set \
                 to span the target range (SexpShape's twelve-shape → \
                 seven-byte outer collapse across `{{0..=6}}`, the \
                 sub-carvings' partition-span contracts) relies on \
                 every range byte being reached",
            );
        }
        if cur == HI {
            break;
        }
        cur += 1;
    }
}

// Compile-time range-coverage witnesses — one `const _: () =
// assert_u8_array_covers_inclusive_range::<N, LO, HI>(&…)` per
// family-wide `[u8; N]` hash-discriminator array on the substrate's
// closed-set outer algebras whose distinct-value set is an
// intentionally-closed inclusive range AND WHOSE JOINT (INJECTIVITY,
// SURJECTIVITY, ARITY) CONTRACT DOES NOT BIND THROUGH THE STRONGER
// COMPOUND `assert_u8_array_permutes_inclusive_range` HELPER BELOW.
// Each invocation is const-evaluated at `cargo check` time; a
// regression that silently drifts an entry above HI, below LO, OR
// silently drops a range byte from the distinct-value set fails the
// build rather than the test suite. Sibling to the runtime
// `_span_outer_partition_*` / `_covers_*` tests at `error.rs`'s
// tests module — the two enforce the same theorem at TWO stages of
// the toolchain, so a build that skips tests still catches the
// regression here, and a build that runs tests catches it a second
// time as a safety net if the const-eval sweep is ever silently
// dropped. The three permutation-shaped sub-carvings
// (`AtomKind::HASH_DISCRIMINATORS`, `QuoteForm::HASH_DISCRIMINATORS`,
// `UnquoteForm::HASH_DISCRIMINATORS`) bind SURJECTIVITY-onto-a-range
// through the stronger compound `assert_u8_array_permutes_inclusive_
// range` helper below — the compound helper composes injectivity ∧
// surjectivity ∧ arity-cardinality-match at ONE `const _` line per
// array, halving the per-array witness surface at strictly stronger
// contract strength. Only `SexpShape::HASH_DISCRIMINATORS` remains
// on this single-axis SURJECTIVITY sweep because its intentionally-
// non-injective twelve-shape → seven-byte collapse means DISTINCTNESS
// DOES NOT hold (the six atomic-shape arms all collapse to `1u8`)
// yet range-coverage of `{0..=6}` DOES hold (every outer byte
// reached) — it CANNOT bind a permutation contract on any range
// corner. `StructuralKind::HASH_DISCRIMINATORS` covers the non-
// inclusive-range partition `{0, 2}` (gap at `1u8` where the
// atomic-carve outer marker lives, per the outer-`Sexp` carve
// semantics) — intentionally OMITTED from this range-coverage sweep
// since its distinct-value set is not a contiguous inclusive range;
// it binds SURJECTIVITY through the sibling non-contiguous-corner
// helper `assert_u8_array_covers_finite_set` below.
const _: () = assert_u8_array_covers_inclusive_range::<12, 0, 6>(
    &crate::error::SexpShape::HASH_DISCRIMINATORS,
);

/// Compile-time contract verifier — panics at const evaluation time if
/// any entry of `arr` falls OUTSIDE the inclusive range `[LO, HI]` on
/// the substrate's `u8` cache-key vocabulary. Binds ONE conjunct clause
/// at ONE `const _` line:
///
/// * RANGE-SUBSET-VIOLATION: every entry in `arr` lies in `[LO..=HI]` —
///   the array's distinct-value set is a SUBSET of the target inclusive
///   range. A regression that drifts ONE entry to a byte OUTSIDE the
///   range (e.g. lifts a `[u8; 2]` sub-carve of the outer-`Sexp` cache-
///   key `[0..=6]` partition to `[0u8, 7u8]`, drifting past the outer-
///   discriminator space's upper endpoint) fails-loudly at const-eval.
///
/// Contract-strength peer to [`assert_u8_array_covers_inclusive_range`]
/// on the (equality-vs-subset) axis: where `_covers_inclusive_range`
/// binds `arr`'s distinct-value set FULLY COVERS `[LO..=HI]` (every
/// entry is in the range AND every range byte is reached — the RANGE-
/// BOUND arm ∧ the FULL-COVERAGE arm), this helper binds ONLY the
/// RANGE-BOUND arm read in isolation (`arr ⊆ [LO..=HI]` without the
/// FULL-COVERAGE clause) — a strictly WEAKER contract for arrays
/// intentionally covering only a PROPER SUBSET of the target range.
///
/// Contiguity-axis peer to [`assert_u8_array_within_u8_finite_set`]:
/// where the finite-set SUBSET-only sibling binds `arr ⊆ set` at the
/// non-contiguous-finite-set corner (`set` is any `[u8; M]` —
/// contiguous, gapped, singleton, or scattered), this helper binds
/// `arr ⊆ [LO..=HI]` at the contiguous-range corner (target super-
/// set is a contiguous inclusive range parameterised by the `LO/HI`
/// const generics rather than a runtime-provided literal array). The
/// two helpers together close the (equality-vs-subset) × (contiguity)
/// 2×2 = 4-corner face of the substrate's `u8` array vocabulary at
/// compile time: (equality, contiguous) at
/// [`assert_u8_array_covers_inclusive_range`], (equality, finite-
/// set) at [`assert_u8_array_covers_finite_set`], (subset,
/// contiguous) at THIS helper, (subset, finite-set) at
/// [`assert_u8_array_within_u8_finite_set`]. Prefer the tighter
/// [`assert_u8_array_covers_inclusive_range`] when the array's
/// distinct-value set intentionally EQUALS the target range; this
/// helper is for the strictly-weaker SUBSET corner where `arr`
/// covers only a PROPER SUBSET of `[LO..=HI]`. Prefer
/// [`assert_u8_array_within_u8_finite_set`] when the target super-
/// set is NON-contiguous — this range-based helper cannot express
/// gaps within the target.
///
/// The invariant is load-bearing for the substrate's OUTER-`Sexp`
/// cache-key partition-embedding contract on the ONE outer discri-
/// minator array whose parent-range embedding is NOT ALREADY compile-
/// time-enforced through a tighter contract:
/// [`crate::error::StructuralKind::HASH_DISCRIMINATORS`] (`[u8; 2]`
/// = `[0, 2]`, the non-contiguous two-of-seven structural-residual
/// sub-carving covering `{0, 2}` with a gap at `1u8` where the
/// atomic-carve outer marker lives) MUST be a SUBSET of `[0..=6]`
/// (the outer-`Sexp` cache-key discriminator space defined by
/// [`crate::error::SexpShape::HASH_DISCRIMINATORS`]'s twelve-shape
/// → seven-byte collapse). Pre-lift the array bound SURJECTIVITY
/// through
/// `assert_u8_array_permutes_finite_set::<2, 2>(&StructuralKind::HASH_DISCRIMINATORS, &[0u8, 2u8])`
/// — this compound witness binds a permutation of the FINITE-SET
/// `{0, 2}` but leaves the OUTER-RANGE embedding UNCONSTRAINED at
/// compile time. A coordinated regression that drifted BOTH
/// `StructuralKind::LIST_HASH_DISCRIMINATOR` from `2u8` to (say)
/// `8u8` AND updated the finite-set literal from `&[0u8, 2u8]` to
/// `&[0u8, 8u8]` in lockstep at the `_permutes_finite_set` call site
/// would pass the finite-set-permutation witness (the drifted pair
/// is a permutation of the drifted set) but VIOLATE the outer-
/// `[0..=6]` partition semantic — `8u8` falls OUTSIDE the twelve-
/// shape SexpShape hash arm's reach. Post-lift the ARRAY-LEVEL
/// RANGE-SUBSET witness catches the coordinated finite-set drift
/// at const-eval time; the panic message routes operator attention
/// to the ARRAY-DECLARATION site as the drift origin. The runtime
/// per-role scalar alias-chain pins in `error.rs`'s test module
/// survive as sibling checks (a distinct failure mode: a drift
/// that KEPT the byte within `[0..=6]` but ROUTED to the wrong
/// per-role outer marker still passes the ARRAY-level range-
/// subset check but fails the per-role scalar pin) — together the
/// two pins bind the outer-partition embedding at TWO stages of
/// the toolchain.
///
/// The three OTHER family-wide outer-`Sexp` discriminator arrays
/// (`SexpShape`, `QuoteForm`, `UnquoteForm`) are intentionally
/// OMITTED from this range-SUBSET sweep because their outer-
/// `[0..=6]` embedding is ALREADY compile-time-enforced through
/// TIGHTER contracts on their respective sub-ranges:
/// [`crate::error::SexpShape::HASH_DISCRIMINATORS`] covers `[0..=6]`
/// exactly via [`assert_u8_array_covers_inclusive_range::<12, 0, 6>`]
/// (equality tighter than subset — the covers witness implies the
/// subset witness); [`QuoteForm::HASH_DISCRIMINATORS`] permutes
/// `[3..=6]` via [`assert_u8_array_permutes_inclusive_range::<4, 3, 6>`]
/// (a permutation of `[3..=6]` — which is a subset of `[0..=6]` by
/// numeric inclusion — implies `⊆ [0..=6]`);
/// [`crate::error::UnquoteForm::HASH_DISCRIMINATORS`] permutes
/// `[5..=6]` via [`assert_u8_array_permutes_inclusive_range::<2, 5, 6>`]
/// (same, doubly transitive through QuoteForm's parent-range
/// containment). Adding redundant SUBSET-of-`[0..=6]` witnesses on
/// those three would double-bind claims strictly weaker than what
/// the tighter permutes / covers contracts already prove.
///
/// Every future family-wide `[u8; N]` typed-range-subset carving on
/// the substrate's closed-set outer algebras whose target-superset
/// IS a contiguous inclusive range (e.g. any further intentionally-
/// closed sub-carving of the `[0..=6]` outer-`Sexp` partition whose
/// distinct-value set is intentionally NON-CONTIGUOUS within the
/// target range) participates in the SAME compile-time guarantee
/// via one `const _` line.
///
/// Adding a new family-wide `[u8; N]` range-embedded array to the
/// substrate: pair the declaration with `const _: () =
/// assert_u8_array_within_inclusive_range::<N, LO, HI>(&Self::
/// FOO_ARRAY);` co-located after the array's declaration and the
/// RANGE-SUBSET contract binds at compile time. The rustc-forced
/// arity `[u8; N]` composes with this const-eval sweep so both
/// cardinality-N AND every-entry-in-range are compile-time theorems
/// on the SAME array.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — pinned by
/// `assert_u8_array_within_inclusive_range_panics_at_runtime_on_entry_above_hi`,
/// `assert_u8_array_within_inclusive_range_panics_at_runtime_on_entry_below_lo`,
/// `assert_u8_array_within_inclusive_range_panics_at_runtime_on_terminal_out_of_range_entry`,
/// and
/// `assert_u8_array_within_inclusive_range_panic_message_names_the_helper_and_range_subset_violation_axis`.
/// The panic site carries the axis-provenance string
/// `"RANGE-SUBSET-VIOLATION"` chosen DISTINCT from every sibling
/// helper's axis vocabulary (`"duplicate"` on the ARRAY-side pairwise-
/// distinct sibling; `"OUT-OF-SET"` / `"SET-BYTE-MISSING"` on the
/// covers-finite-set sibling; `"OUT-OF-RANGE"` / `"MISSING"` on the
/// covers-inclusive-range sibling; `"SUBSET-VIOLATION"` on the finite-
/// set SUBSET-only sibling; `"ARITY-MISMATCH"` on both `_permutes_*`
/// compound helpers; `"SET-NOT-PAIRWISE-DISTINCT"` on the SET-side
/// well-formedness sibling) so a diagnostic that names the failed
/// axis routes UNAMBIGUOUSLY to THIS specific range SUBSET-embedding
/// helper. The `"RANGE-"` prefix disambiguates from the finite-set
/// peer's bare `"SUBSET-VIOLATION"`; the `"-VIOLATION"` suffix is
/// shared with the finite-set peer so callers can grep either
/// SUBSET-embedding sibling by `"VIOLATION"` alone or route to the
/// specific contiguity corner by the `"RANGE-"` / bare-`"SUBSET-"`
/// disambiguator prefix.
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the family-wide range-
///   subset-embedding contract on the `u8` cache-key vocabulary
///   becomes a TYPE-LEVEL theorem the substrate carries per
///   (array, range) pair rather than a transitively-implied claim
///   the developer must trust to hold across sibling witnesses
///   drifting in lockstep.
/// - THEORY.md §V.3 — three-pillar attestation; the outer-`Sexp`
///   cache-key `[0..=6]` partition is the `intent_hash` composition
///   axis — binding the range-subset embedding on the typed algebra
///   makes a coordinated drift outside the parent range a compile
///   error rather than a silent BLAKE3 mis-hash on any
///   `Expander::cache` consumer keyed on the sub-carving.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   range-membership-only sweep IS the generative shape. Every new
///   closed-set discriminator array whose distinct-value set is an
///   intentional SUBSET of a contiguous inclusive range on the
///   substrate adds ONE `const _` line to get the range-subset-
///   embedding theorem rather than re-deriving a per-embedding
///   runtime iterator sweep at each call site.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs;
///   the RANGE-SUBSET embedding proof at declaration site AND the
///   parent [`assert_u8_array_covers_inclusive_range`] proof on the
///   parent-range-covering array regenerate through the SAME
///   `const _` witness at the SUBSET-embedded array level.
///
/// Frontier inspiration: Lean 4's `Set.Icc` (closed interval) combined
/// with `Set.subset_Icc_iff` giving the equivalence `s ⊆ Icc a b ↔
/// ∀ x ∈ s, a ≤ x ∧ x ≤ b` — the substrate primitive here embeds
/// the same interval-subset relation as a rustc const-eval-time proof
/// obligation at every `assert_u8_array_within_inclusive_range` call
/// site rather than as a Lean tactic invocation deferred to
/// `elab_command`. TLA+'s `\A x \in S : LO <= x /\ x <= HI` first-
/// class quantified-interval-subset relation composes similarly at
/// TLC model-checking time. Coq's `Included A (Ensembles.Included U
/// (fun x => LO <= x <= HI))` predicate encodes the same per-element
/// containment. Translation through pleme-io primitives: the RANGE-
/// SUBSET embedding predicate binds through ONE forward sweep
/// (`LO ≤ arr[i] ≤ HI`) at const-eval time on a rustc-forced-arity
/// `[u8; N]` × two `u8` const generics — no `Ord` / `Eq` / `Hash`
/// supertrait bound, no allocation, no set carrier.
///
/// # Panics
///
/// Panics if any `arr[i]` satisfies `arr[i] < LO || arr[i] > HI`.
pub const fn assert_u8_array_within_inclusive_range<const N: usize, const LO: u8, const HI: u8>(
    arr: &[u8; N],
) {
    let mut i = 0;
    while i < N {
        if arr[i] < LO || arr[i] > HI {
            panic!(
                "assert_u8_array_within_inclusive_range: RANGE-\
                 SUBSET-VIOLATION — the family-wide u8 array `arr` \
                 carries an entry at some position whose byte falls \
                 OUTSIDE the target inclusive range `[LO, HI]`. The \
                 substrate's RANGE-SUBSET-EMBEDDING contract on the \
                 array is broken; every consumer that expects the \
                 array's distinct-value set to embed within the \
                 target inclusive range (`StructuralKind::HASH_\
                 DISCRIMINATORS ⊂ [0..=6]` on the outer-`Sexp` \
                 cache-key partition; any future typed-range-subset \
                 embedding on the substrate's closed-set outer \
                 algebras) relies on every array entry staying \
                 inside the target range. Fix at the ARRAY-\
                 DECLARATION site (the `arr` under verification, \
                 NOT the `LO`/`HI` const parameters specifying the \
                 target range) by dropping the offending entry OR \
                 by widening `[LO..=HI]` to cover it — the choice \
                 depends on whether the drift is an unintended \
                 overshoot outside the parent range or an \
                 intentional extension of the range vocabulary"
            );
        }
        i += 1;
    }
}

// Compile-time RANGE-SUBSET-embedding witness — the ONE family-wide
// `[u8; N]` HASH_DISCRIMINATORS array on the substrate whose distinct-
// value set is an intentionally-closed PROPER SUBSET of a contiguous
// inclusive range NOT ALREADY BOUND by a TIGHTER `_covers_inclusive_
// range` / `_permutes_inclusive_range` witness on a sub-range:
// `StructuralKind::HASH_DISCRIMINATORS` (`[u8; 2]` = `[0, 2]`, the
// non-contiguous two-of-seven structural-residual sub-carving covering
// `{0, 2}` with a gap at `1u8` where the atomic-carve outer marker
// lives) MUST be a SUBSET of `[0..=6]` (the outer-`Sexp` cache-key
// discriminator space defined by `SexpShape::HASH_DISCRIMINATORS`'s
// twelve-shape → seven-byte collapse). Pre-lift the array bound
// SURJECTIVITY through `assert_u8_array_permutes_finite_set::<2, 2>(
// &StructuralKind::HASH_DISCRIMINATORS, &[0u8, 2u8])` (module-level
// `const _` further down in this file) — this compound witness binds
// a permutation of the FINITE-SET `{0, 2}` but leaves the OUTER-RANGE
// embedding UNCONSTRAINED at compile time. A coordinated regression
// that drifted BOTH `StructuralKind::LIST_HASH_DISCRIMINATOR` from
// `2u8` to (say) `8u8` AND updated the finite-set literal from
// `&[0u8, 2u8]` to `&[0u8, 8u8]` at the `_permutes_finite_set` call
// site would pass the finite-set-permutation witness (the drifted
// pair is a permutation of the drifted set) but VIOLATE the outer-
// `Sexp` `[0..=6]` partition semantic every `Hash for Sexp` consumer
// relies on. Post-lift this ARRAY-LEVEL RANGE-SUBSET witness catches
// the coordinated finite-set drift at const-eval time — the panic
// message routes operator attention to the ARRAY-DECLARATION site
// as the drift origin. The three OTHER family-wide outer-`Sexp`
// discriminator arrays (`SexpShape`, `QuoteForm`, `UnquoteForm`) are
// intentionally OMITTED from this range-SUBSET sweep because their
// outer-`[0..=6]` embedding is ALREADY compile-time-enforced through
// TIGHTER contracts on their respective sub-ranges (SexpShape covers
// `[0..=6]` exactly; QuoteForm permutes `[3..=6]`; UnquoteForm
// permutes `[5..=6]`) — adding redundant SUBSET-of-`[0..=6]`
// witnesses on those three would double-bind claims strictly weaker
// than what the tighter permutes / covers contracts already prove.
const _: () = assert_u8_array_within_inclusive_range::<2, 0, 6>(
    &crate::error::StructuralKind::HASH_DISCRIMINATORS,
);

/// Compile-time WELL-FORMEDNESS contract verifier on a caller-provided
/// TARGET-SET spec `set` — panics at const evaluation time (or at
/// runtime for dynamic callers) with the axis-provenance-named
/// `"SET-NOT-PAIRWISE-DISTINCT"` message iff `set` carries a duplicate
/// entry across two positions.
///
/// Closes the pre-existing caller-side WELL-FORMEDNESS gap on the
/// finite-set corner of the substrate's `u8` cache-key contract
/// lattice: pre-lift, both [`assert_u8_array_covers_finite_set`] and
/// [`assert_u8_array_permutes_finite_set`] documented (but did NOT
/// enforce) the pairwise-distinctness of the caller-provided target
/// `set` spec as a well-formedness *precondition* — a malformed set
/// (e.g. `[0u8, 2u8, 2u8]` at `M = 3`) silently passed BOTH covers-
/// helper arms on any `arr` that partitioned the DISTINCT-value subset
/// `{0, 2}` (post-lift `assert_u8_array_covers_finite_set` calls into
/// this helper as its FIRST arm; a malformed set now fails-loudly at
/// const-eval with a SET-side panic message BEFORE the OUT-OF-SET /
/// SET-BYTE-MISSING arms fire). The pigeonhole invariants both
/// downstream covers/permutes helpers rely on (`N == M` in the
/// permutation helper forces exact-set-partitioning) assume `set`
/// is well-formed AS a mathematical finite set; this helper turns
/// that assumption into a compile-time theorem the substrate
/// carries per call site rather than a docstring-level responsibility
/// the operator must remember to keep in lockstep across every
/// finite-set-covering call site.
///
/// Element-type sibling posture to [`assert_u8_array_pairwise_distinct`]:
/// the ARRAY sibling closes pairwise-distinctness on the ARRAY side of
/// the finite-set-coverage / permutation-of-finite-set compound
/// contracts (`arr` MUST be pairwise-distinct for the SURJECTIVITY
/// arm of the permutation helper to imply full-set-coverage by
/// pigeonhole); this SET sibling closes pairwise-distinctness on the
/// caller-provided TARGET-SET spec side (the SET spec MUST itself be
/// pairwise-distinct as a mathematical set — a `[u8; M]` literal that
/// silently duplicates a byte is not really a set of cardinality `M`
/// but of cardinality `< M`, and every downstream pigeonhole argument
/// gets a phantom-`M` inflating the arity check). The two helpers
/// together close BOTH sides of the pairwise-distinctness axis on
/// the finite-set-coverage compound tier: `arr` (the array under
/// verification) AND `set` (the caller-provided target-set spec).
///
/// The invariant is load-bearing for `StructuralKind::HASH_DISCRIMINATORS`'
/// permutation-of-finite-set witness at
/// [`assert_u8_array_permutes_finite_set`]'s module-level `const _`
/// invocation — the caller passes `&[0u8, 2u8]` as the target-set
/// spec; a regression at the CALL SITE that silently duplicated a
/// byte (e.g. `&[0u8, 0u8]` or `&[2u8, 2u8]`) would render the
/// permutation contract unsound: the pigeonhole `N == M` arity check
/// would still hold on the substrate's `[u8; 2]` array but the
/// intended set-cardinality is really `1`, so a permutation of
/// `{0, 2}` (via `arr = [0u8, 2u8]`) would silently mis-verify as
/// a permutation of `{0}` or `{2}`. Post-lift the well-formedness
/// check at the top of the compound helper's delegation chain
/// catches the SET-side drift at const-eval time with a message
/// routing operator attention to the CALLER'S SPEC rather than to
/// a downstream symptom.
///
/// Panic-message provenance: the axis-name string
/// `"SET-NOT-PAIRWISE-DISTINCT"` is chosen DISTINCT from every
/// sibling helper's axis-provenance vocabulary (`"duplicate"` on
/// [`assert_u8_array_pairwise_distinct`]'s ARRAY-side sweep;
/// `"OUT-OF-RANGE"` / `"MISSING"` on
/// [`assert_u8_array_covers_inclusive_range`];
/// `"OUT-OF-SET"` / `"SET-BYTE-MISSING"` on
/// [`assert_u8_array_covers_finite_set`];
/// `"ARITY-MISMATCH"` on the two compound `_permutes_*` helpers)
/// so a diagnostic that names the failed axis routes UNAMBIGUOUSLY
/// to (a) this specific SET-side well-formedness helper, and (b)
/// the CALLER'S TARGET-SET SPEC as the drift site rather than the
/// downstream `arr` under verification. The two-element prefix
/// `"SET-"` is shared with the sibling covers-finite-set arm's
/// `"SET-BYTE-MISSING"` — both are SET-side drifts, disambiguated
/// by the trailing `"NOT-PAIRWISE-DISTINCT"` vs. `"BYTE-MISSING"`
/// noun to disambiguate the specific SET-side axis.
///
/// Adding a new family-wide `[u8; N]` finite-set-covering array to
/// the substrate: no new call site needed at this level — every
/// invocation of [`assert_u8_array_covers_finite_set`] or
/// [`assert_u8_array_permutes_finite_set`] delegates through this
/// helper as its FIRST arm, so the well-formedness contract on the
/// caller-provided target-set spec binds at compile time as a side-
/// effect of the primary covers/permutes contract. Callers CAN also
/// invoke this helper directly at runtime to verify a dynamically-
/// constructed target-set spec's well-formedness before passing it
/// into the covers/permutes helpers — pinned by the negative
/// runtime pins (`_panics_at_runtime_on_binary_collision`,
/// `_panics_at_runtime_on_non_adjacent_collision`,
/// `_panics_at_runtime_on_terminal_collision`).
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the caller-side target-set
///   well-formedness contract becomes a TYPE-LEVEL theorem the
///   substrate carries per call site rather than a docstring-level
///   responsibility the developer must remember to keep in lockstep
///   with every downstream covers/permutes invocation.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs; the
///   set-well-formedness proof at the CALLER's site AND the covers/
///   permutes helpers' downstream pigeonhole arguments regenerate
///   through the SAME `const _` witness at each call site.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   set-pairwise-distinct sweep IS the generative shape. Every
///   downstream call to `assert_u8_array_covers_finite_set` or
///   `assert_u8_array_permutes_finite_set` now composes the set-
///   well-formedness precondition through the delegation chain
///   rather than the developer re-deriving a per-call-site
///   pairwise-distinct sweep on the target-set literal.
///
/// Compound sibling posture to the constituent
/// [`assert_u8_array_pairwise_distinct`] on the (verifier-target-
/// side) axis: the two helpers close the pairwise-distinctness axis
/// on the TWO complementary sides of the finite-set-coverage
/// compound tier — ARRAY side (`arr` in the covers/permutes
/// helpers) and SET side (`set` in the covers/permutes helpers).
/// Every intentionally-closed finite-set-covering `[u8; N]` array
/// on the substrate now binds pairwise-distinctness on BOTH the
/// ARRAY under verification AND the caller-provided target-set
/// spec at compile time.
pub const fn assert_u8_finite_set_pairwise_distinct<const M: usize>(set: &[u8; M]) {
    let mut i = 0;
    while i < M {
        let mut j = i + 1;
        while j < M {
            if set[i] == set[j] {
                panic!(
                    "assert_u8_finite_set_pairwise_distinct: SET-NOT-\
                     PAIRWISE-DISTINCT — the caller-provided target \
                     FINITE-SET spec `set` for a downstream `assert_u8_\
                     array_covers_finite_set` / `assert_u8_array_\
                     permutes_finite_set` invocation carries a DUPLICATE \
                     entry across two positions. A mathematical finite \
                     set carries each element at most once, so a `[u8; \
                     M]` literal with `M` positions but fewer than `M` \
                     DISTINCT values is not a well-formed finite set of \
                     cardinality `M` — every downstream pigeonhole \
                     argument (`N == M` arity check in the permutation \
                     helper; SET-BYTE-MISSING coverage arm in the \
                     covers helper) gets a PHANTOM-`M` inflating the \
                     effective cardinality and silently mis-verifies \
                     the intended finite-set-coverage / permutation \
                     contract. Fix at the SET-DECLARATION site (the \
                     `&[...]` literal passed as the `set` argument, NOT \
                     the `arr` argument being verified) by removing the \
                     duplicate byte from the target-set spec"
                );
            }
            j += 1;
        }
        i += 1;
    }
}

/// Compile-time contract verifier — panics at const evaluation time if
/// any entry of `arr` is NOT a member of `set` on the substrate's `u8`
/// cache-key vocabulary. Binds ONE conjunct clause at ONE `const _`
/// line:
///
/// * SUBSET-VIOLATION: every entry in `arr` appears in `set` — the
///   array's distinct-value set is a SUBSET of the target finite
///   partition `set`. A regression that drifts ONE entry to a byte
///   NOT in the set (e.g. lifts a fresh `7u8` entry into
///   `UnquoteForm::HASH_DISCRIMINATORS`, drifting the two-of-four
///   substitution-subset carving OUTSIDE its parent superset
///   `QuoteForm::HASH_DISCRIMINATORS = [3, 4, 5, 6]`) fails-loudly
///   at const-eval.
///
/// SET-side well-formedness delegation: [`assert_u8_finite_set_pairwise_distinct`]
/// is called at the top of the helper — a malformed `set` (e.g.
/// `[0u8, 2u8, 2u8]`) is not a well-formed finite set of cardinality
/// `M` and would silently mis-verify the intended subset contract on
/// any `arr` embedded in the DISTINCT-value subset. Placed FIRST so
/// drift on the CALLER'S TARGET-SET SPEC routes to the SET-side
/// well-formedness axis rather than to a downstream SUBSET-VIOLATION
/// symptom on `arr`. A well-formed `set` passes this arm as a no-op —
/// const-eval-elidable at rustc-time on the substrate call site.
///
/// Contract-strength peer to [`assert_u8_array_covers_finite_set`] on
/// the (equality-vs-subset) axis: where `_covers_finite_set` binds
/// arr's distinct-value set EQUALS `set` (arr's entries ⊆ set AND
/// set ⊆ arr's entries — the OUT-OF-SET arm ∧ the SET-BYTE-MISSING
/// arm), this helper binds ONLY arr ⊆ set (the OUT-OF-SET arm read
/// in isolation without the SET-BYTE-MISSING arm) — a strictly
/// WEAKER contract for arrays that intentionally cover only a
/// PROPER SUBSET of the target partition rather than the whole
/// partition. The RANGE analog of this SUBSET-only helper is the
/// RANGE-BOUND arm of [`assert_u8_array_covers_inclusive_range`]
/// read in isolation (arr ⊆ `[LO..=HI]` without the FULL-COVERAGE
/// clause) — no substrate call site currently exercises the range
/// analog on its own because every substrate range-family array
/// either fully covers its assigned range (the three permutation-
/// shaped `_permutes_inclusive_range` arrays: `AtomKind`,
/// `QuoteForm`, `UnquoteForm`) or fully covers it non-injectively
/// (`SexpShape::HASH_DISCRIMINATORS`). The finite-set analog of this
/// SUBSET-only helper is exactly the primitive this lift adds.
///
/// The invariant is load-bearing for the outer-`Sexp` cache-key
/// algebra's SUBSTITUTION-SUBSET embedding.
/// [`crate::error::UnquoteForm::HASH_DISCRIMINATORS`] (`[u8; 2]` —
/// the two-of-four substitution-subset carving covering `Unquote`
/// / `UnquoteSplice`) MUST be a SUBSET of
/// [`QuoteForm::HASH_DISCRIMINATORS`] (`[u8; 4]` — the four-arm
/// quote-family superset carving covering `Quote` / `Quasiquote` /
/// `Unquote` / `UnquoteSplice`). Pre-lift the subset embedding was
/// pinned ONLY at runtime via
/// `unquote_form_per_role_hash_discriminators_alias_quote_form_per_role_hash_discriminators_byte_for_byte`
/// (in `error.rs`, checking per-role scalar byte-equality between
/// the two `pub(crate) const UnquoteForm::*_HASH_DISCRIMINATOR`
/// constants and their `QuoteForm::*_HASH_DISCRIMINATOR`
/// namesakes) — the theorem held only after `cargo test` scheduled
/// the pin. Post-lift the ARRAY-LEVEL subset containment binds at
/// rustc time — a regression that re-inlined either UnquoteForm
/// per-role alias to a fresh literal byte NOT in the QuoteForm
/// superset (e.g. `7u8`) fails at `cargo check` BEFORE any test
/// scheduler runs. The runtime per-role scalar alias-chain pin
/// survives as a sibling check (a distinct failure mode: a drift
/// that KEPT the byte in the superset but ROUTED the alias to the
/// WRONG QuoteForm arm still passes the ARRAY-level subset check
/// but fails the scalar per-role pin) — together the two pins
/// bind the substitution-subset embedding at TWO stages of the
/// toolchain, const-time on the ARRAYS and test-time on the per-
/// role scalar aliases.
///
/// Every future family-wide `[u8; N]` typed-subset carving on the
/// substrate's closed-set outer algebras (a hypothetical
/// name-punctuation-subset of a keyword vocabulary, a strict
/// numeric-vs-string atomic-payload subset of `AtomKind`, or any
/// further sub-carving of the `{0..=6}` outer-`Sexp` cache-key
/// partition) participates in the SAME compile-time guarantee via
/// one `const _` line.
///
/// Adding a new family-wide `[u8; N]` subset-embedded array to the
/// substrate: pair the declaration with `const _: () =
/// assert_u8_array_within_u8_finite_set::<N, M>(&Self::FOO_ARRAY,
/// &Other::SUPERSET_ARRAY);` co-located after the array's
/// declaration and the SUBSET contract binds at compile time. The
/// rustc-forced arities `[u8; N]` and `[u8; M]` compose with this
/// const-eval sweep so BOTH cardinality-pair AND every-entry-in-
/// superset are compile-time theorems on the SAME (subset, superset)
/// array pair. Prefer [`assert_u8_array_covers_finite_set`] when
/// the array's distinct-value set is intentionally EQUAL to the
/// target partition; this helper is for the strictly-weaker SUBSET
/// corner where `arr` covers only a PROPER SUBSET of `set`.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — pinned by
/// `assert_u8_array_within_u8_finite_set_panics_at_runtime_on_out_of_set_entry`
/// and
/// `assert_u8_array_within_u8_finite_set_panic_message_names_the_helper_and_subset_violation_axis`.
/// The panic site carries the `"SUBSET-VIOLATION"` axis-provenance
/// string chosen DISTINCT from every sibling helper's axis
/// vocabulary (`"duplicate"` on the ARRAY-side pairwise-distinct
/// sibling; `"OUT-OF-SET"` / `"SET-BYTE-MISSING"` on the
/// covers-finite-set sibling; `"OUT-OF-RANGE"` / `"MISSING"` on
/// the covers-inclusive-range sibling; `"ARITY-MISMATCH"` on both
/// `_permutes_*` compound helpers; `"SET-NOT-PAIRWISE-DISTINCT"`
/// on the SET-side well-formedness sibling) so a diagnostic that
/// names the failed axis routes UNAMBIGUOUSLY to THIS specific
/// SUBSET-embedding helper.
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the family-wide subset-
///   embedding contract on the `u8` cache-key vocabulary becomes a
///   TYPE-LEVEL theorem the substrate carries per (subset, superset)
///   array pair rather than a runtime test the developer must
///   remember to write per embedding.
/// - THEORY.md §V.3 — three-pillar attestation; the outer-`Sexp`
///   cache-key partition is the `intent_hash` composition axis —
///   binding the subset-embedding arrays on the typed algebra
///   makes a substitution-subset drift outside the parent superset
///   a compile error rather than a silent BLAKE3 mis-hash on any
///   `Expander::cache` consumer keyed on the subset carving.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   set-membership-only sweep IS the generative shape. Every new
///   closed-set discriminator array whose distinct-value set is an
///   intentional SUBSET of another substrate array adds ONE
///   `const _` line to get the subset-embedding theorem rather
///   than re-deriving a per-embedding runtime iterator sweep at
///   each call site.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs;
///   the SUBSET-embedding proof at declaration site AND the per-
///   role scalar alias-chain composition through
///   `UnquoteForm::V_HASH_DISCRIMINATOR = QuoteForm::V_HASH_DISCRIMINATOR`
///   regenerate through the SAME `const _` witness at the ARRAY
///   level.
///
/// Frontier inspiration: Lean 4's `Finset.instHasSubsetFinset :
/// (⊆) : Finset α → Finset α → Prop` as a decidable relation on
/// `Finset α` combined with `Finset.subset_iff` unfolding the
/// relation to per-element membership — the substrate primitive
/// here embeds the same subset relation as a rustc const-eval-time
/// proof obligation at every `assert_u8_array_within_u8_finite_set`
/// call site rather than as a Lean tactic invocation deferred to
/// `elab_command`. TLA+'s `S \subseteq T` first-class relation on
/// specification sets composes similarly at TLC model-checking
/// time. Coq's `Ensembles.Included : Ensemble U -> Ensemble U ->
/// Prop` capturing the same per-element containment predicate.
/// Translation through pleme-io primitives: the SUBSET-embedding
/// predicate binds through ONE forward sweep (`arr[i] in set`) at
/// const-eval time on a rustc-forced-arity `[u8; N]` × `[u8; M]`
/// pair — no `Ord` / `Eq` / `Hash` supertrait bound, no
/// `HashSet`-shape carrier, no allocation. The delegation-first
/// ordering (SET-well-formedness before SUBSET-VIOLATION) matches
/// Lean's `Finset`-forward reasoning: prove the SET is well-formed
/// AS a finite set, then reason about arrays embedded in it.
pub const fn assert_u8_array_within_u8_finite_set<const N: usize, const M: usize>(
    arr: &[u8; N],
    set: &[u8; M],
) {
    // Delegate target-set well-formedness to the sibling SET-side
    // pairwise-distinctness helper FIRST. Placed BEFORE the SUBSET-
    // VIOLATION sweep below because a malformed `set` (e.g. `[0u8,
    // 2u8, 2u8]`) is not a well-formed finite set of cardinality
    // `M` and silently mis-verifies the intended subset contract on
    // any `arr` embedded in the DISTINCT-value subset. Routes drift
    // on the CALLER'S TARGET-SET SPEC to the SET-side well-formedness
    // axis rather than to a downstream SUBSET-VIOLATION symptom on
    // `arr`. A well-formed `set` passes this arm as a no-op — the
    // sweep is const-eval-elidable and costs zero at rustc-time on
    // the one substrate call site.
    assert_u8_finite_set_pairwise_distinct(set);
    let mut i = 0;
    while i < N {
        let mut j = 0;
        let mut found = false;
        while j < M {
            if arr[i] == set[j] {
                found = true;
                break;
            }
            j += 1;
        }
        if !found {
            panic!(
                "assert_u8_array_within_u8_finite_set: SUBSET-\
                 VIOLATION — the family-wide u8 array `arr` carries \
                 an entry at some position whose byte is NOT a \
                 member of the target finite superset partition \
                 `set`. The substrate's SUBSET-EMBEDDING contract \
                 on the array is broken; every consumer that \
                 expects the array's distinct-value set to be a \
                 subset of the target finite partition \
                 (`UnquoteForm::HASH_DISCRIMINATORS ⊂ \
                 QuoteForm::HASH_DISCRIMINATORS` on the outer-\
                 `Sexp` cache-key substitution-subset carving; any \
                 future typed-subset embedding on the substrate's \
                 closed-set outer algebras) relies on every array \
                 entry staying within the target superset. Fix at \
                 the ARRAY-DECLARATION site (the `arr` under \
                 verification, NOT the `set` argument specifying \
                 the target superset) by dropping the offending \
                 entry OR by extending `set` to cover it — the \
                 choice depends on whether the drift is an \
                 unintended overshoot outside the parent superset \
                 or an intentional extension of the superset \
                 vocabulary"
            );
        }
        i += 1;
    }
}

// Compile-time SUBSET-embedding witness — the ONE family-wide
// `[u8; N]` HASH_DISCRIMINATORS array on the substrate whose
// distinct-value set is an intentionally-closed PROPER SUBSET of
// another substrate array's distinct-value set:
// `UnquoteForm::HASH_DISCRIMINATORS` (`[u8; 2]` = `[5, 6]`, the
// two-of-four substitution-subset carving covering
// `Unquote` / `UnquoteSplice`) MUST be a SUBSET of
// `QuoteForm::HASH_DISCRIMINATORS` (`[u8; 4]` = `[3, 4, 5, 6]`, the
// four-arm quote-family superset carving covering
// `Quote` / `Quasiquote` / `Unquote` / `UnquoteSplice`). Pre-lift
// the subset embedding was pinned ONLY at runtime via the per-role
// alias-chain check
// `unquote_form_per_role_hash_discriminators_alias_quote_form_per_role_hash_discriminators_byte_for_byte`
// (in `error.rs`, checking scalar-per-role byte-equality between
// the two `UnquoteForm::*_HASH_DISCRIMINATOR` constants and their
// `QuoteForm::*_HASH_DISCRIMINATOR` namesakes). Post-lift the
// ARRAY-LEVEL subset embedding binds at rustc time via ONE
// `const _` witness on the two arrays directly; a drift that
// re-inlined either UnquoteForm alias to a fresh literal byte NOT
// in the QuoteForm superset (e.g. `7u8`) would fail at `cargo
// check` BEFORE any test scheduler runs. The runtime per-role
// alias-chain pin survives as a sibling check for the scalar
// aliases (a distinct failure mode: a drift that KEPT the byte in
// the superset but ROUTED the alias to the WRONG QuoteForm arm
// still passes the ARRAY-level subset check but fails the scalar
// per-role pin); together with this const witness the
// substitution-subset embedding theorem is enforced at BOTH stages
// of the toolchain — const-time on the ARRAYS, test-time on the
// scalar per-role aliases.
const _: () = assert_u8_array_within_u8_finite_set::<2, 4>(
    &crate::error::UnquoteForm::HASH_DISCRIMINATORS,
    &QuoteForm::HASH_DISCRIMINATORS,
);

// Compile-time TIGHTENING witness — the (u8)-row analog of the
// (str)-row three-witness SUB-AS-SLICE cluster in `error.rs`
// (`assert_str_array_slice_equals_str_array::<4, 2, 2>` on the
// `UnquoteForm::{LABELS, MARKERS, IAC_FORGE_TAGS} ⊂
// QuoteForm::{LABELS, PREFIXES, IAC_FORGE_TAGS}` sub-carve). The
// pre-existing SUBSET-embedding witness above binds `UnquoteForm::
// HASH_DISCRIMINATORS ⊂ QuoteForm::HASH_DISCRIMINATORS` at the SET
// level (`{5, 6} ⊂ {3, 4, 5, 6}`); this witness tightens the
// binding to POSITIONWISE SLICE-EQUALS on the SAME sub-carve —
// `QuoteForm::HASH_DISCRIMINATORS[2..4] == UnquoteForm::HASH_
// DISCRIMINATORS[..]` byte-for-byte in canonical slot order.
//
// Two failure axes survive the SET-level SUBSET witness above that
// this POSITIONWISE witness rejects at rustc time:
//   1. Sub-array SLOT REORDER: a regression that swaps
//      `UnquoteForm::HASH_DISCRIMINATORS` from `[UNQUOTE_HASH_
//      DISCRIMINATOR, SPLICE_HASH_DISCRIMINATOR]` (`[5, 6]`) to
//      `[SPLICE_HASH_DISCRIMINATOR, UNQUOTE_HASH_DISCRIMINATOR]`
//      (`[6, 5]`) preserves the SUBSET witness (both bytes still
//      appear in the superset) — but silently misaligns every
//      consumer indexing the sub-array by slot ordinal (the
//      `UnquoteForm::hash_discriminator` per-variant projection at
//      `error.rs`'s `UnquoteForm` inherent impl, the runtime
//      partition test
//      `unquote_form_hash_discriminators_align_with_quote_form_
//      hash_discriminators_by_projection`).
//   2. Superset SLOT REORDER that leaves sub-array bytes still
//      present but at different positions: a regression that
//      reorders `QuoteForm::HASH_DISCRIMINATORS` from `[3, 4, 5,
//      6]` to any permutation that leaves `{5, 6}` non-contiguous
//      or non-tail (e.g. `[5, 3, 6, 4]`) preserves the SUBSET
//      witness (both sub-array bytes still appear in the superset,
//      just at scattered non-`[2..4)` positions) — but the sub-
//      carving no longer sits at the tail of the superset's four-
//      arm declaration listing, breaking the compositional
//      invariant that `QuoteForm::HASH_DISCRIMINATORS[2..4] ==
//      UnquoteForm::HASH_DISCRIMINATORS` presumes.
//
// Sibling posture: the (str)-row tightening cluster at `error.rs`
// (three `assert_str_array_slice_equals_str_array::<4, 2, 2>`
// witnesses on the `LABELS` / `MARKERS↔PREFIXES` / `IAC_FORGE_TAGS`
// vocabulary triple) closes the SLICE-EQUALS column on the SAME
// (UnquoteForm ⊂ QuoteForm) 2-of-4 sub-carve at the STR element-
// type row; this witness closes the SAME column at the U8 element-
// type row. Together the four-witness cluster (three str + one u8)
// exhausts the (element-type × vocabulary-axis) matrix of the
// substitution-subset carving at the SLICE-EQUALS positionwise-
// composition contract.
//
// Composition with the sibling FULL-ARRAY LITERAL witnesses at
// lines 6961..=6976 below: those two witnesses independently pin
// `QuoteForm::HASH_DISCRIMINATORS == [3u8, 4, 5, 6]` and
// `UnquoteForm::HASH_DISCRIMINATORS == [5u8, 6]` against their
// literal byte listings. This SLICE-EQUALS witness composes with
// them — a drift on EITHER array's literal listing fails first at
// the peer FULL-ARRAY witness; a drift on the sub-carving's
// contiguous-tail placement inside the superset that leaves BOTH
// literal listings intact (e.g. a fifth quote-family variant
// landing at an interior position of `QuoteForm::HASH_DISCRIMINATORS`
// shifting UNQUOTE/UNQUOTE_SPLICE off `[2..4)`) fails HERE at the
// SUB-AS-SLICE witness. Sibling to the JOINT permutation witness
// `assert_scalar_plus_two_u8_arrays_permute_inclusive_range::<2, 4,
// 0, 6>` at line 7029 — that witness binds the outer partition
// `{0..=6} = {OUTER} ⊕ StructuralKind::HASH_DISCRIMINATORS ⊕
// QuoteForm::HASH_DISCRIMINATORS` as a bijection; this witness
// binds the sub-carving `UnquoteForm::HASH_DISCRIMINATORS` to a
// SPECIFIC contiguous slice of that quote-family carving.
const _: () = assert_u8_array_slice_equals_u8_array::<4, 2, 2>(
    &QuoteForm::HASH_DISCRIMINATORS,
    &crate::error::UnquoteForm::HASH_DISCRIMINATORS,
);

/// Compile-time contract verifier — panics at const evaluation time if
/// the distinct-values sets of `a` and `b` share any byte on the
/// substrate's `u8` cache-key vocabulary. Binds ONE conjunct clause:
/// U8-DISJOINTNESS-VIOLATION — no entry in `a` may appear as an entry
/// in `b` (symmetric across the two array arguments).
///
/// Row-dual peer to [`assert_char_arrays_disjoint`] on the (element-
/// type) axis of the (subset, disjointness) 2-corner face of the
/// (contract-shape) axis: where the (char) sibling closes the reader-
/// boundary `char` disjointness corner at compile time, this (u8)
/// sibling closes the outer-`Sexp` cache-key `u8` disjointness corner
/// on the SAME element-type row. Together the two helpers close the
/// (element-type × contract-shape) 2×2 = 4-corner face at ONE peer
/// const-fn helper per corner rather than at a per-pair runtime
/// iterator sweep per call site. Contract-orthogonal peer to
/// [`assert_u8_array_within_u8_finite_set`] on the (subset-vs-
/// disjointness) axis of the (contract-shape) axis on the SAME (u8)
/// row: where the SUBSET-EMBEDDING sibling binds `arr ⊆ set`, this
/// DISJOINTNESS sibling binds `a ∩ b = ∅` on the SAME element type.
///
/// The disjointness relation is SYMMETRIC (unlike the SUBSET-EMBEDDING
/// relation, which distinguishes `arr` from `set`) so the two
/// arguments carry NO axis-provenance role split — either drift site
/// (a byte in `a` that aliases a byte in `b`, OR a byte in `b` that
/// aliases a byte in `a`) surfaces at the U8-DISJOINTNESS-VIOLATION
/// panic with the OFFENDING arm named by BOTH position indices
/// (`a[i]` AND `b[j]`) rather than by only one side of the pair.
///
/// SYMMETRY IN THE NESTED SWEEP: the inner `while j < M` sweep visits
/// every position of `b` per outer `i` and panics at the FIRST
/// cross-array collision (`a[i] == b[j]`). Because the relation is
/// symmetric and the two-loop sweep visits every `(i, j) ∈ [0, N) ×
/// [0, M)` pair, swapping `a` and `b` at the call site produces the
/// SAME verdict — the helper does NOT gratuitously depend on argument
/// order. A future call site that intends to name a SPECIFIC drift
/// side can still route its own preferred first-mention by picking
/// the argument order that serves its diagnostic story; the helper
/// itself carries no such preference.
///
/// The invariant is load-bearing for the outer-`Sexp` cache-key
/// algebra's JOINT PARTITION contract at [`Hash for Sexp`]: the
/// outer-`Sexp` discriminator space `{0..=6}` MUST partition across
/// the three closed-set sub-carvings ([`crate::error::StructuralKind::HASH_DISCRIMINATORS`]
/// at `{0, 2}`, [`AtomKind::OUTER_HASH_DISCRIMINATOR`] scalar at `{1}`,
/// [`QuoteForm::HASH_DISCRIMINATORS`] at `{3, 4, 5, 6}`) with NO
/// overlap — otherwise two structurally-distinct outer-`Sexp` variants
/// would silently mis-hash through the same cache-key byte and the
/// substrate's `Expander::cache` would leak macro-expansion hits
/// across carvings. Pre-lift the substrate carried these array-vs-
/// array disjointness relations at runtime tests
/// (`structural_kind_hash_discriminator_disjoint_from_atom_outer_carve_byte_and_quote_form_hash_discriminator_partition`
/// on the (StructuralKind, QuoteForm) pair;
/// `unquote_form_hash_discriminator_partitions_disjointly_from_non_substitution_carvings`
/// on the (UnquoteForm, StructuralKind) pair); post-lift the ARRAY-
/// LEVEL disjointness of the pinned pairs binds at rustc time via one
/// `const _` line per pair. A regression that silently drifted
/// `StructuralKind::LIST_HASH_DISCRIMINATOR` from `2u8` to `3u8`
/// (colliding with `QuoteForm::QUOTE_HASH_DISCRIMINATOR`), or drifted
/// `QuoteForm::QUOTE_HASH_DISCRIMINATOR` from `3u8` to `0u8`
/// (colliding with `StructuralKind::NIL_HASH_DISCRIMINATOR`), fails at
/// `cargo check` BEFORE any test scheduler runs. Sibling to the
/// pairwise-distinctness witnesses above — those pin INJECTIVITY on
/// each individual `[u8; N]` HASH_DISCRIMINATORS array, this pins
/// DISJOINTNESS across PAIRS of arrays on the SAME outer-`Sexp`
/// cache-key byte space.
///
/// Adding a new family-wide `[u8; N]` sub-vocabulary whose distinct-
/// values set must remain disjoint from another substrate `[u8; M]`
/// array's distinct-values set: pair the declaration with `const _:
/// () = assert_u8_arrays_disjoint::<N, M>(&Self::FOO_ARRAY,
/// &Other::BAR_ARRAY);` co-located after the array's declaration and
/// the DISJOINTNESS contract binds at compile time. The rustc-forced
/// arities `[u8; N]` and `[u8; M]` compose with this const-eval
/// sweep so BOTH cardinality-pair AND cross-array disjointness are
/// compile-time theorems on the SAME (a, b) u8-array pair.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — pinned by
/// `assert_u8_arrays_disjoint_panics_at_runtime_on_collision` and
/// `assert_u8_arrays_disjoint_panic_message_names_the_helper_and_u8_disjointness_violation_axis`.
/// The panic site carries the `"U8-DISJOINTNESS-VIOLATION"` axis-
/// provenance string chosen DISTINCT from every sibling helper's axis
/// vocabulary (`"duplicate"` on the ARRAY-side pairwise-distinct
/// sibling; `"CHAR-DISJOINTNESS-VIOLATION"` on the (char) row-dual
/// DISJOINTNESS sibling; `"CHAR-SUBSET-VIOLATION"` on the (char)
/// SUBSET-embedding sibling; `"SUBSET-VIOLATION"` on the (u8) finite-
/// set SUBSET-only sibling; `"RANGE-SUBSET-VIOLATION"` on the (u8)
/// range SUBSET-only sibling; `"OUT-OF-SET"` / `"SET-BYTE-MISSING"`
/// on the (u8) covers-finite-set sibling; `"OUT-OF-RANGE"` /
/// `"MISSING"` on the (u8) covers-inclusive-range sibling;
/// `"ARITY-MISMATCH"` on both (u8) `_permutes_*` compound helpers;
/// `"SET-NOT-PAIRWISE-DISTINCT"` on the (u8) SET-side well-formedness
/// sibling) so a diagnostic that names the failed axis routes
/// UNAMBIGUOUSLY to THIS specific u8 DISJOINTNESS helper. The `"U8-"`
/// prefix disambiguates from the (char) DISJOINTNESS sibling; the
/// shared `"-VIOLATION"` suffix lets callers grep either row's
/// DISJOINTNESS or SUBSET-embedding sibling by `"VIOLATION"` alone or
/// route to the specific contract-shape by the axis stem
/// (`"DISJOINTNESS"` vs `"SUBSET"`).
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the family-wide cross-array
///   disjointness contract on the outer-`Sexp` cache-key `u8`
///   vocabulary becomes a TYPE-LEVEL theorem the substrate carries
///   per (a, b) u8-array pair rather than a runtime test the
///   developer must remember to write per pair.
/// - THEORY.md §III — the typescape; the (element-type × contract-
///   shape) 2×2 = 4-corner matrix is now closed at ONE peer const-fn
///   helper per corner — [`assert_char_array_within_char_finite_set`]
///   on the (char, subset) corner, [`assert_char_arrays_disjoint`] on
///   the (char, disjointness) corner,
///   [`assert_u8_array_within_u8_finite_set`] on the (u8, subset)
///   corner, and this helper on the (u8, disjointness) corner.
/// - THEORY.md §V.3 — three-pillar attestation; the outer-`Sexp`
///   cache-key partition is the substrate's `intent_hash` composition
///   axis — binding the ARRAY-vs-ARRAY disjointness pairs at compile
///   time makes a joint-partition-overlap drift a compile error
///   rather than a silent BLAKE3 mis-hash on any `Expander::cache` or
///   `Sekiban` audit-trail metric keyed on the outer discriminator
///   space.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   cross-array membership sweep IS the generative shape. Every new
///   closed-set `u8` sub-vocabulary array whose distinct-values set is
///   an intentionally-disjoint peer of another substrate `u8` array
///   adds ONE `const _` line to get the disjointness theorem rather
///   than re-deriving a per-pair runtime iterator sweep at each call
///   site.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs; the
///   DISJOINTNESS proof at declaration site AND the outer-`Sexp`
///   cache-key JOINT PARTITION contract regenerate through the SAME
///   `const _` witnesses at the ARRAY level.
///
/// Frontier inspiration: Lean 4's `Finset.Disjoint : Finset α →
/// Finset α → Prop` as a decidable relation on `Finset α` combined
/// with `Finset.disjoint_iff_ne`'s characterisation `∀ a ∈ s, ∀ b ∈
/// t, a ≠ b` — this substrate primitive embeds the same disjointness
/// relation as a rustc const-eval-time proof obligation at every
/// `assert_u8_arrays_disjoint` call site rather than as a Lean tactic
/// invocation deferred to `elab_command`. Coq's `Ensembles.Disjoint :
/// Ensemble U -> Ensemble U -> Prop` captures the same relation as a
/// Prop-level predicate. Translation through pleme-io primitives: the
/// DISJOINTNESS predicate binds through the same nested `(i, j)`
/// sweep as the (char) row-dual peer, monomorphised to the concrete
/// `[u8; N] × [u8; M]` element-type realisation — no `Ord` / `Eq` /
/// `Hash` supertrait bound, no `HashSet`-shape carrier, no allocation.
pub const fn assert_u8_arrays_disjoint<const N: usize, const M: usize>(a: &[u8; N], b: &[u8; M]) {
    let mut i = 0;
    while i < N {
        let mut j = 0;
        while j < M {
            if a[i] == b[j] {
                panic!(
                    "assert_u8_arrays_disjoint: U8-DISJOINTNESS-\
                     VIOLATION — the two family-wide u8 arrays `a` \
                     and `b` share an entry at some (i, j) position \
                     pair. The substrate's CROSS-ARRAY DISJOINTNESS \
                     contract on the pair is broken; every consumer \
                     that partitions the two arrays' distinct-values \
                     sets into disjoint sub-vocabularies of the outer-\
                     `Sexp` cache-key `u8` algebra (the outer-`Sexp` \
                     joint-partition contract at `Hash for Sexp`: \
                     `StructuralKind::HASH_DISCRIMINATORS` at `{{0, 2}}` \
                     disjoint from `QuoteForm::HASH_DISCRIMINATORS` at \
                     `{{3, 4, 5, 6}}` disjoint from `UnquoteForm::HASH_\
                     DISCRIMINATORS` at `{{5, 6}}` on the non-parent \
                     carvings; any future typed-disjointness pair on \
                     the substrate's outer-`Sexp` cache-key `u8` \
                     algebras) relies on the two arrays' distinct-\
                     values sets NOT sharing a byte. Fix at WHICHEVER \
                     ARRAY-DECLARATION site drifted (the symmetric \
                     disjointness relation carries no built-in axis-\
                     provenance role split between `a` and `b`) by \
                     dropping the offending entry from one array OR \
                     re-shaping the partition to route the shared \
                     entry to a single sub-vocabulary"
                );
            }
            j += 1;
        }
        i += 1;
    }
}

// Compile-time DISJOINTNESS witnesses — the TWO substrate-pinned
// (a, b) `[u8; N] × [u8; M]` pairs whose distinct-values sets are
// intentionally-closed disjoint sub-vocabularies of the outer-`Sexp`
// cache-key `u8` algebra. Pre-lift the two disjointness relations
// lived only as runtime tests
// (`structural_kind_hash_discriminator_disjoint_from_atom_outer_carve_byte_and_quote_form_hash_discriminator_partition`
// on pair 1, sweeping `StructuralKind::hash_discriminator`'s `{0, 2}`
// against `QuoteForm::hash_discriminator`'s `{3, 4, 5, 6}` through
// per-variant `Vec<u8>` collection into a HashSet-shape overlap
// check; `unquote_form_hash_discriminator_partitions_disjointly_from_non_substitution_carvings`
// on pair 2, sweeping `UnquoteForm::hash_discriminator`'s `{5, 6}`
// against `StructuralKind::hash_discriminator`'s `{0, 2}` through the
// same HashSet-shape `is_disjoint` check); post-lift the ARRAY-LEVEL
// disjointness of the pinned pairs binds at rustc time via one
// `const _` line per pair. A regression that silently drifted
// `StructuralKind::LIST_HASH_DISCRIMINATOR` from `2u8` to `3u8`
// (colliding with `QuoteForm::QUOTE_HASH_DISCRIMINATOR`), or drifted
// `QuoteForm::QUOTE_HASH_DISCRIMINATOR` from `3u8` to `0u8`
// (colliding with `StructuralKind::NIL_HASH_DISCRIMINATOR`), or
// drifted `UnquoteForm::UNQUOTE_HASH_DISCRIMINATOR` from `5u8` to
// `2u8` (colliding with `StructuralKind::LIST_HASH_DISCRIMINATOR`)
// fails at `cargo check` BEFORE any test scheduler runs.
//
// Note on pair 2 (`UnquoteForm::HD` vs `StructuralKind::HD`): the
// disjointness is FORMALLY IMPLIED by pair 1 (`StructuralKind::HD` vs
// `QuoteForm::HD`) composed with the pre-existing SUBSET-embedding
// witness `assert_u8_array_within_u8_finite_set::<2, 4>(&UnquoteForm::HD,
// &QuoteForm::HD)` (transitivity of subset-through-disjoint: `X ⊂ Y ∧
// Y ∩ Z = ∅ ⇒ X ∩ Z = ∅`). Post-lift the direct pair-2 witness pins
// the substitution-subset drift mode DIRECTLY at rustc time rather
// than through a two-hop const-time inference — a drift that broke
// the pair-2 disjointness EITHER by drifting `UnquoteForm::HD` out of
// the parent superset OR by drifting `StructuralKind::HD` into the
// parent superset surfaces at THIS witness with the exact drifting
// arm identified. The redundant witness stays intentional: it mirrors
// the runtime pin's structure (a direct-per-pair check rather than a
// composed-through-parent check) so the runtime-vs-const witness
// pairs stay in one-to-one correspondence and a runtime pin has an
// EXACT const-time peer without pair-mapping ambiguity.
const _: () = assert_u8_arrays_disjoint::<2, 4>(
    &crate::error::StructuralKind::HASH_DISCRIMINATORS,
    &QuoteForm::HASH_DISCRIMINATORS,
);
const _: () = assert_u8_arrays_disjoint::<2, 2>(
    &crate::error::UnquoteForm::HASH_DISCRIMINATORS,
    &crate::error::StructuralKind::HASH_DISCRIMINATORS,
);

/// Compile-time contract verifier — panics at const evaluation time if
/// the distinct-values set of `arr` does not equal exactly the distinct-
/// values set of `set` on the substrate's `u8` cache-key vocabulary.
/// Binds TWO conjunct clauses at ONE `const _` line:
///   1. OUT-OF-SET: every entry in `arr` appears in `set` — no byte
///      outside the target finite partition. A regression that drifts
///      ONE entry to a byte NOT in the set (e.g. lifts a fresh entry at
///      `3u8` on a `{0, 2}` array) fails-loudly at const-eval.
///   2. SET-BYTE-MISSING: every byte in `set` appears at least once in
///      `arr` — no byte inside the target finite partition missing. A
///      regression that silently unifies two entries onto ONE byte,
///      leaving another set byte unreached (e.g. drops the `Nil` arm's
///      `0u8` from `StructuralKind::HASH_DISCRIMINATORS` in favour of
///      a redundant `2u8`), fails-loudly at const-eval too.
///
/// Generalises [`assert_u8_array_covers_inclusive_range`] along the
/// (contiguity) axis: where the range helper closes the SURJECTIVITY
/// axis at the contiguous corner (the target partition is an inclusive
/// `[LO, HI]` range), this finite-set helper closes the SURJECTIVITY
/// axis at the arbitrary-finite-set corner (the target partition is
/// any `[u8; M]` — contiguous, gapped, singleton, or scattered). The
/// contiguous-range helper stays as the tighter idiom for arrays whose
/// distinct-value set happens to be a contiguous inclusive range; this
/// finite-set helper binds the arrays whose distinct-value set is
/// NON-contiguous and therefore cannot be expressed as `[LO..=HI]`.
///
/// The invariant is load-bearing for the outer-`Sexp` cache-key
/// algebra's SPAN across the structural-residual sub-carve.
/// [`crate::error::StructuralKind::HASH_DISCRIMINATORS`] (`[u8; 2]`
/// covering `{0, 2}` with a gap at `1u8` where the atomic-carve outer
/// marker lives) is the archetype non-contiguous case — its
/// distinct-value set is a two-element finite set that is NOT a
/// contiguous inclusive range, so the range helper cannot bind. This
/// finite-set helper binds the structural-residual sub-carve's
/// surjectivity contract at compile time despite the intentional
/// gap: a regression that drops the `Nil` arm's `0u8` (or the `List`
/// arm's `2u8`) — or lifts a fresh `1u8` colliding with the outer-
/// carve atomic marker byte — fails the build. Every future family-
/// wide `[u8; N]` array whose distinct-value set is an intentionally-
/// closed FINITE (possibly non-contiguous) partition participates in
/// the SAME compile-time guarantee via one `const _` line.
///
/// Adding a new family-wide `[u8; N]` finite-set-covering array to
/// the substrate: pair the declaration with `const _: () =
/// assert_u8_array_covers_finite_set::<N, M>(&Self::FOO_ARRAY,
/// &[…the M target-set bytes…]);` co-located after the array's
/// declaration and the finite-set-coverage contract binds at compile
/// time. The rustc-forced arity `[u8; N]` composes with this
/// const-eval sweep so cardinality AND every-entry-in-set AND
/// every-set-byte-reached are ALL compile-time theorems on the SAME
/// array. Prefer the tighter [`assert_u8_array_covers_inclusive_range`]
/// when the target set IS a contiguous inclusive range — this helper
/// is the fallback for the non-contiguous corner.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — pinned by
/// `assert_u8_array_covers_finite_set_panics_at_runtime_on_
/// out_of_set_entry` + `assert_u8_array_covers_finite_set_panics_at_
/// runtime_on_missing_set_byte`. Both panic sites carry axis-provenance
/// strings ("OUT-OF-SET" vs. "SET-BYTE-MISSING") so downstream
/// diagnostics (`cargo check` const-eval error output, test-suite
/// failure reports) route the drift back to the failed axis by string
/// search — halving the search space for the operator debugging the
/// drift. The two axis-provenance strings are chosen DISTINCT from
/// the sibling [`assert_u8_array_covers_inclusive_range`]'s
/// ("OUT-OF-RANGE" vs. "MISSING") so a diagnostic that names the
/// failed axis routes UNAMBIGUOUSLY to the failed HELPER too.
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the family-wide finite-set-
///   coverage contract on the `u8` cache-key vocabulary becomes a
///   TYPE-LEVEL theorem the substrate carries per array declaration
///   rather than a runtime test the developer must remember to write
///   per non-contiguous partition.
/// - THEORY.md §V.3 — three-pillar attestation; the outer-`Sexp`
///   cache-key partition is the `intent_hash` composition axis —
///   binding the finite-set-covering arrays on the typed algebra makes
///   attestation-key drift a compile error rather than a silent
///   BLAKE3 mis-hash on any consumer keyed on `Hash for Sexp`. A
///   regression that drops a byte from the structural-residual
///   sub-carve (or drifts an entry into the atomic-carve gap at `1u8`)
///   fails the build before it can silently invalidate a cached
///   expansion or a Sekiban audit-trail metric keyed on the outer
///   discriminator space.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   set-membership + set-coverage sweep IS the generative shape.
///   Every new closed-set discriminator array whose distinct-value set
///   is an intentionally-closed finite (possibly non-contiguous)
///   partition adds ONE `const _` line to get the finite-set-coverage
///   theorem rather than re-deriving two per-array runtime iterator
///   sweeps (one for the set-membership bound, one for the set-
///   coverage completeness).
///
/// Contiguity-axis sibling posture to
/// [`assert_u8_array_covers_inclusive_range`]: the two helpers close
/// the SURJECTIVITY axis of the substrate's typed `u8` array
/// vocabulary at the TWO complementary corners of the (contiguity)
/// axis. Combined with the four pre-existing const-fn contract
/// verifiers ([`assert_char_array_pairwise_distinct`],
/// [`assert_str_array_pairwise_distinct`],
/// [`assert_u8_array_pairwise_distinct`],
/// [`assert_char_pair_array_bijective`]) closing the INJECTIVITY axis,
/// the substrate now carries a complete `(injectivity, surjectivity)`
/// compile-time cache-key contract lattice: every family-wide `[u8; N]`
/// discriminator array binds AT LEAST ONE axis, and the four
/// intentionally-injective + range-covering arrays
/// (`AtomKind`, `QuoteForm`, `UnquoteForm` HASH_DISCRIMINATORS +
/// `SexpShape::HASH_DISCRIMINATORS` on the range-only arm) bind BOTH
/// axes.
pub const fn assert_u8_array_covers_finite_set<const N: usize, const M: usize>(
    arr: &[u8; N],
    set: &[u8; M],
) {
    // Delegate target-set well-formedness to the sibling SET-side
    // pairwise-distinctness helper FIRST. Placed BEFORE the OUT-OF-SET
    // and SET-BYTE-MISSING sweeps below because a malformed `set`
    // (e.g. `[0u8, 2u8, 2u8]`) inflates the effective cardinality
    // used by the SET-BYTE-MISSING sweep with a PHANTOM-`M` and
    // silently mis-verifies the intended finite-set-coverage contract.
    // Routes drift on the CALLER'S TARGET-SET SPEC to the SET-side
    // well-formedness axis rather than to a downstream OUT-OF-SET /
    // SET-BYTE-MISSING symptom on `arr`. A well-formed `set` passes
    // this arm as a no-op — the sweep is const-eval-elidable and
    // costs zero at rustc-time on a substrate with only one such
    // call site.
    assert_u8_finite_set_pairwise_distinct(set);
    let mut i = 0;
    while i < N {
        let mut j = 0;
        let mut found = false;
        while j < M {
            if arr[i] == set[j] {
                found = true;
                break;
            }
            j += 1;
        }
        if !found {
            panic!(
                "assert_u8_array_covers_finite_set: family-wide u8 \
                 array carries an OUT-OF-SET entry at some position — \
                 the entry's byte is absent from the target finite \
                 partition `set`. The substrate's SET-MEMBERSHIP \
                 contract on the array is broken; every consumer that \
                 expects the array's entries to partition an outer \
                 cache-key space (Hash for Sexp's outer discriminator \
                 space, StructuralKind's non-contiguous sub-carving of \
                 `{{0, 2}}` around the atomic-carve gap at `1u8`) \
                 relies on the entries staying within the target set",
            );
        }
        i += 1;
    }
    let mut j = 0;
    while j < M {
        let mut k = 0;
        let mut found = false;
        while k < N {
            if arr[k] == set[j] {
                found = true;
                break;
            }
            k += 1;
        }
        if !found {
            panic!(
                "assert_u8_array_covers_finite_set: family-wide u8 \
                 array is SET-BYTE-MISSING a byte from the target \
                 finite partition `set` — every byte in the set must \
                 appear at least once in the array. The substrate's \
                 FULL-COVERAGE contract on the array is broken; every \
                 consumer that expects the array's distinct-value set \
                 to span the target finite partition (StructuralKind's \
                 `{{0, 2}}` two-arm sub-carve, any future non-\
                 contiguous partition-span contract) relies on every \
                 set byte being reached",
            );
        }
        j += 1;
    }
}

// Compile-time finite-set-coverage on family-wide `[u8; N]` hash-
// discriminator arrays no longer surfaces at this level as DIRECT
// witnesses — the ONE family-wide `[u8; N]` HASH_DISCRIMINATORS array
// whose distinct-value set is an intentionally-closed non-contiguous
// finite partition (`StructuralKind::HASH_DISCRIMINATORS` (`[u8; 2]`)
// covering `{0, 2}` with the load-bearing gap at `1u8` where the
// atomic-carve outer marker byte lives) now binds SURJECTIVITY through
// the stronger COMPOUND (INJECTIVITY ∧ SURJECTIVITY ∧ ARITY)
// `assert_u8_array_permutes_finite_set` helper defined below, which
// delegates through THIS helper for the SET-MEMBERSHIP + FULL-
// COVERAGE arms — the helper is now purely a delegation target.
// Binding the compound witness makes the (StructuralKind sub-carve,
// atomic-carve marker byte) disjointness a compile-time theorem: a
// regression that lifted a fresh `1u8` entry into
// `StructuralKind::HASH_DISCRIMINATORS` would silently collide with
// `AtomKind::OUTER_HASH_DISCRIMINATOR = 1u8` on the outer-`Sexp`
// cache-key partition and fail the build at the compound helper's
// delegation call to THIS helper's `"OUT-OF-SET"` arm rather than
// surfacing as a silent BLAKE3 mis-hash on any consumer keyed on
// `Hash for Sexp`.
//
// Adding a new family-wide `[u8; N]` non-contiguous-finite-set-covering
// HASH_DISCRIMINATORS array: prefer the compound
// `assert_u8_array_permutes_finite_set` helper below which binds
// INJECTIVITY ∧ SURJECTIVITY ∧ ARITY at ONE `const _` line if the
// array is a PERMUTATION of the target set; fall back to a DIRECT
// `const _: () = assert_u8_array_covers_finite_set::<N, M>(&Self::
// FOO_ARRAY, &[…set…]);` witness at this level ONLY for an array with
// a LOOSER contract (e.g. an intentionally-non-injective mapping onto
// the target set — no substrate array currently exercises this
// posture). Sibling to the runtime `_span_*` / `_covers_*` tests at
// `error.rs`'s tests module — those enforce the same theorem at
// `cargo test` time through direct runtime calls to this helper, so
// the theorem is still bound at TWO stages of the toolchain (compile
// time through the delegated path inside the compound helper, test
// time through the direct runtime calls). Contiguity-axis peer to the
// four `assert_u8_array_covers_inclusive_range` witnesses above:
// those close the contiguous-range corner of the SURJECTIVITY-only
// axis at the four range-covering HASH_DISCRIMINATORS arrays;
// `StructuralKind::HASH_DISCRIMINATORS` was the sole array closing the
// non-contiguous-finite-set corner of the SURJECTIVITY-only axis, and
// now instead binds through the stronger compound helper's
// non-contiguous corner.

/// Compile-time contract verifier — panics at const evaluation time if
/// `arr` is not a PERMUTATION of the inclusive integer range `[LO..=HI]`
/// on the substrate's `u8` cache-key vocabulary. Binds THREE conjunct
/// clauses at ONE `const _` line:
///   1. ARITY-MISMATCH: `N` MUST equal `HI - LO + 1` — a bijection
///      between `[0..N)` and `[LO..=HI]` forces the cardinality equality
///      by pigeonhole. A regression that adds a spurious duplicate entry
///      to a HASH_DISCRIMINATORS array (bumping `N` past the range's
///      cardinality) fails-loudly at this arm with the ARITY-MISMATCH-
///      provenance panic message. Delegated to no sibling — this arm is
///      the compound helper's unique contribution.
///   2. Range-membership: every entry in `arr` lies in `[LO, HI]` —
///      delegated to [`assert_u8_array_covers_inclusive_range`] (which
///      ALSO sweeps the FULL-COVERAGE axis; both axes bind through the
///      one delegation call).
///   3. Pairwise-distinctness: every pair of entries is distinct —
///      delegated to [`assert_u8_array_pairwise_distinct`].
///
/// (1) ∧ (2) ∧ (3) jointly imply the array's entries EXACTLY partition
/// the range: `N` distinct entries chosen from a range of cardinality
/// `N` MUST equal the entire range by pigeonhole. The single compound
/// invocation therefore binds the same theorem as the pair
/// `assert_u8_array_pairwise_distinct(&arr) + assert_u8_array_covers_
/// inclusive_range::<N, LO, HI>(&arr)` PLUS the arity-mismatch check
/// (1) that neither weak sibling carries alone — a strictly stronger
/// contract at HALF the per-array witness-line surface.
///
/// Compression: pre-lift, each of the three intentionally-permutation-
/// shaped HASH_DISCRIMINATORS arrays ([`AtomKind::HASH_DISCRIMINATORS`],
/// [`QuoteForm::HASH_DISCRIMINATORS`],
/// [`crate::error::UnquoteForm::HASH_DISCRIMINATORS`]) bound its
/// permutation contract at TWO `const _` lines (one
/// `assert_u8_array_pairwise_distinct` for INJECTIVITY, one
/// `assert_u8_array_covers_inclusive_range` for SURJECTIVITY-onto-a-
/// range) — six witness lines total across the three arrays. Post-lift
/// each array binds the same theorem PLUS the arity-mismatch check at
/// ONE `const _` line — three witness lines total, a 2:1 compression.
/// [`crate::error::StructuralKind::HASH_DISCRIMINATORS`] stays on the
/// weak-pair contract because its distinct-value set `{0, 2}` is
/// NON-contiguous (gap at `1u8` where the atomic-carve outer marker
/// lives) — the non-contiguous corner binds through
/// `assert_u8_array_pairwise_distinct` + `assert_u8_array_covers_
/// finite_set` instead, awaiting a future `assert_u8_array_permutes_
/// finite_set` compound helper on the non-contiguous corner of the
/// (contiguity) axis. [`crate::error::SexpShape::HASH_DISCRIMINATORS`]
/// stays on the range-coverage-only contract because its twelve-shape →
/// seven-byte collapse means INJECTIVITY DOES NOT hold — so it CANNOT
/// bind a permutation contract on any range corner.
///
/// The invariant is load-bearing for the three permutation-shaped
/// sub-carvings' outer-`Sexp` cache-key partition binding. Each of the
/// three arrays MUST bijectively permute its assigned range corner of
/// `{0..=6}` so `Hash for Sexp`'s outer discriminator hash sequence
/// stays injective on each sub-partition: [`AtomKind::HASH_DISCRIMINATORS`]
/// permutes `{0..=5}` on the nested atomic-payload carve inside `Hash
/// for Atom`; [`QuoteForm::HASH_DISCRIMINATORS`] permutes `{3..=6}` on
/// the quote-family arms of `Hash for Sexp`; UnquoteForm permutes
/// `{5..=6}` on the substitution-subset of the quote-family. A
/// regression that silently unified two arm's cache-key bytes on ANY
/// of the three arrays — OR lifted a fresh N+1 entry drifting `N` above
/// the range's cardinality — would silently invalidate every cached
/// `Sexp` participating in `Expander::cache`. The compound witness
/// catches all three drift modes at COMPILE time.
///
/// Adding a new family-wide `[u8; N]` permutation-of-range array to
/// the substrate: pair the declaration with `const _: () =
/// assert_u8_array_permutes_inclusive_range::<N, LO, HI>(&Self::
/// FOO_ARRAY);` co-located after the array's declaration and the
/// permutation contract binds at compile time. The rustc-forced arity
/// `[u8; N]` composes with this const-eval sweep so cardinality AND
/// arity-cardinality-match AND range-membership AND pairwise-
/// distinctness AND (by pigeonhole) full range-coverage are ALL
/// compile-time theorems on the SAME array from ONE `const _` line.
/// Prefer this compound helper over the weak-pair pattern for any
/// array whose distinct-value set is intentionally EXACTLY a
/// contiguous inclusive range with the array acting as a permutation
/// of it — the two weak helpers stay as the fallback for arrays with
/// LOOSER contracts (e.g. `SexpShape::HASH_DISCRIMINATORS`'s
/// intentionally-non-injective twelve → seven collapse binds only the
/// coverage weak sibling).
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — pinned by the four negative
/// runtime pins (`_panics_at_runtime_on_arity_below_cardinality`,
/// `_panics_at_runtime_on_arity_above_cardinality`,
/// `_panics_at_runtime_on_duplicate`,
/// `_panics_at_runtime_on_out_of_range`) that jointly exercise each of
/// the three failure arms.
///
/// The ARITY-MISMATCH panic site carries an axis-provenance string
/// ("ARITY-MISMATCH") chosen DISTINCT from every sibling helper's axis
/// strings ("OUT-OF-RANGE" / "MISSING" on the range-coverage helper;
/// "OUT-OF-SET" / "SET-BYTE-MISSING" on the finite-set-coverage
/// helper) so downstream diagnostics that name the failed axis route
/// UNAMBIGUOUSLY to (a) this compound helper, and (b) the specific
/// arm — a permutation-shaped drift that fails ARITY-MISMATCH is
/// distinct from a range-coverage-drift that fails OUT-OF-RANGE or
/// MISSING at the delegated coverage helper. The two delegated helpers
/// each panic with THEIR OWN provenance strings so drift on the
/// range-membership or pairwise-distinctness arm surfaces with the
/// respective sibling helper's message body.
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the family-wide permutation-
///   of-range contract on the `u8` cache-key vocabulary becomes a
///   TYPE-LEVEL theorem the substrate carries per array declaration
///   at ONE `const _` line rather than at TWO per-axis `const _` lines
///   the developer must remember to keep in lockstep across every
///   permutation-shaped HASH_DISCRIMINATORS array.
/// - THEORY.md §V.3 — three-pillar attestation; the outer-`Sexp`
///   cache-key partition is the `intent_hash` composition axis —
///   binding the permutation-shaped sub-carvings' arrays on the typed
///   algebra makes cardinality drift a compile error rather than a
///   silent `Hash for Sexp` mis-hash on a caller keyed on a
///   permutation-shaped sub-carve.
/// - THEORY.md §VI.1 — generation over composition; the compound
///   arity-check + range-coverage + pairwise-distinctness sweep IS
///   the generative shape. Every new closed-set discriminator array
///   whose distinct-value set is an intentionally-closed contiguous
///   inclusive range with the array acting as a permutation of it
///   adds ONE `const _` line to get the permutation theorem rather
///   than re-deriving TWO per-axis `const _` lines (one for
///   injectivity, one for surjectivity) that would silently drift out
///   of lockstep if one was updated without the other.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs; the
///   compound permutation proof at declaration site AND the three
///   consumer sites (nested atomic-payload carve inside `Hash for
///   Atom`, quote-family arms of `Hash for Sexp`, substitution-subset
///   of the quote-family) regenerate through the SAME `const _`
///   witness at each of the three permutation-shaped arrays.
///
/// Compound sibling posture to the constituent weak helpers on the
/// (axis-count) axis:
/// [`assert_u8_array_pairwise_distinct`] closes the SINGLE-axis
/// INJECTIVITY corner; [`assert_u8_array_covers_inclusive_range`]
/// closes the SINGLE-axis SURJECTIVITY-onto-range corner; this
/// compound helper closes the DOUBLE-axis (INJECTIVITY ∧ SURJECTIVITY
/// ∧ ARITY) corner on the range side of the (contiguity) axis. The
/// non-contiguous compound corner (INJECTIVITY ∧ SURJECTIVITY ∧ ARITY
/// on a finite non-contiguous set) is a future lift's target — the
/// only pre-existing arm that would bind is
/// [`crate::error::StructuralKind::HASH_DISCRIMINATORS`], currently
/// held by the two-weak-witness pattern.
pub const fn assert_u8_array_permutes_inclusive_range<
    const N: usize,
    const LO: u8,
    const HI: u8,
>(
    arr: &[u8; N],
) {
    // Arity check FIRST — pigeonhole forces `N == HI - LO + 1` on a
    // bijection between `[0..N)` and `[LO..=HI]`. Placing this arm
    // FIRST gives cleaner provenance: a drift that grows the array
    // past the range cardinality would ALSO fail either the
    // out-of-range arm (if the extra entry lies outside `[LO, HI]`)
    // OR the pairwise-distinct arm (if it duplicates within range),
    // but the ARITY-MISMATCH-named panic message routes the operator
    // to the CARDINALITY axis directly rather than to a downstream
    // symptom on either weak-axis helper.
    let expected_cardinality = (HI - LO) as usize + 1;
    if N != expected_cardinality {
        panic!(
            "assert_u8_array_permutes_inclusive_range: family-wide u8 \
             array's ARITY-MISMATCH — the compile-time array cardinality \
             `N` does not equal the target inclusive range's cardinality \
             `HI - LO + 1`. A bijection between `[0..N)` and `[LO..=HI]` \
             forces `N == HI - LO + 1` by pigeonhole — an array whose \
             arity drifts above the range's cardinality CANNOT stay both \
             pairwise-distinct AND within the range (extras must \
             duplicate OR fall outside), and one whose arity drifts \
             below CANNOT reach every range byte. The substrate's \
             PERMUTATION contract on the array is broken at the ARITY \
             axis; every consumer that expects the array's entries to \
             bijectively permute the target range (AtomKind / QuoteForm \
             / UnquoteForm sub-carving spaces on their permutation-\
             shaped range corners on Hash for Sexp's outer discriminator \
             partition) relies on this cardinality equality"
        );
    }
    // Delegate pairwise-distinctness to the sibling injectivity
    // helper SECOND (before the range-coverage delegation). Order
    // matters for provenance-preservation on the failure modes: with
    // `N == HI - LO + 1` (post-arity-check), a duplicate entry
    // pigeonhole-forces a missing range byte AND vice-versa — the
    // two axes are logically equivalent given arity-cardinality
    // match. Placing pairwise-distinct BEFORE covers-range routes a
    // duplicate to the sibling's `"duplicate"`-named panic on the
    // INJECTIVITY axis (rather than to the covers-range sibling's
    // `"MISSING"`-named panic on the SURJECTIVITY axis which would
    // fire downstream on the pigeonhole-forced coverage failure).
    // Choosing INJECTIVITY-provenance as the primary duplicate-
    // surfacing arm matches operator expectations: a "duplicate
    // entry" diagnosis names the CAUSE (two entries alias) rather
    // than a downstream SYMPTOM (a range byte is unreached because
    // its slot is duplicated).
    assert_u8_array_pairwise_distinct(arr);
    // Delegate range-membership + full-range-coverage to the sibling
    // covers-range helper THIRD. Given the two prior arms
    // (arity-cardinality-match + pairwise-distinct), the covers-
    // range helper's SECOND (`"MISSING"`) arm becomes unreachable
    // by pigeonhole: `N` distinct entries chosen from a range of
    // cardinality `N` MUST equal the range. Only the FIRST
    // (`"OUT-OF-RANGE"`) arm surfaces in practice — a drift that
    // lifts an entry outside `[LO, HI]` while staying pairwise-
    // distinct panics with the sibling's `"OUT-OF-RANGE"` provenance.
    // The delegated coverage sweep at the second arm is kept for
    // DEFENSE-IN-DEPTH: a regression that silently dropped the
    // pairwise-distinct delegation above would leave a duplicate
    // uncaught by the compound helper's OWN body, but the covers-
    // range sibling's MISSING check would then catch it as a
    // safety-net symptom.
    assert_u8_array_covers_inclusive_range::<N, LO, HI>(arr);
}

/// Compile-time contract verifier — panics at const evaluation time if
/// `arr` is not a PERMUTATION of the caller-supplied FINITE SET `set`
/// on the substrate's `u8` cache-key vocabulary. NON-CONTIGUOUS-FINITE-
/// SET peer of the pre-existing [`assert_u8_array_permutes_inclusive_range`]
/// sibling on the (contiguity) axis of the substrate's compound
/// (INJECTIVITY ∧ SURJECTIVITY ∧ ARITY) permutation verifiers: where
/// the sibling closes the CONTIGUOUS-INCLUSIVE-RANGE corner (at the
/// three permutation-shaped range-covering HASH_DISCRIMINATORS arrays
/// [`AtomKind::HASH_DISCRIMINATORS`] / [`QuoteForm::HASH_DISCRIMINATORS`]
/// / [`crate::error::UnquoteForm::HASH_DISCRIMINATORS`]), this closes
/// the NON-CONTIGUOUS-FINITE-SET corner (at the one permutation-shaped
/// non-contiguous-covering HASH_DISCRIMINATORS array
/// [`crate::error::StructuralKind::HASH_DISCRIMINATORS`], whose
/// distinct-value set `{0, 2}` is intentionally NON-contiguous with a
/// gap at `1u8` where the atomic-carve outer marker
/// [`AtomKind::OUTER_HASH_DISCRIMINATOR`] lives). Binds FOUR conjunct
/// clauses at ONE `const _` line:
///
///   1. SET-NOT-PAIRWISE-DISTINCT: the caller-provided TARGET-SET
///      spec `set` MUST itself be pairwise-distinct — a mathematical
///      finite set of cardinality `M` cannot carry a duplicate entry.
///      Post-lift the pre-lift caveat "assuming `set` is itself
///      pairwise-distinct — a well-formedness responsibility on the
///      caller-provided target spec" is now a compile-time theorem
///      the substrate carries per call site rather than a docstring-
///      level responsibility the operator must remember to keep in
///      lockstep with every downstream covers/permutes invocation.
///      Delegated to [`assert_u8_finite_set_pairwise_distinct`] at
///      the TOP of the delegation chain (before the ARITY arm below
///      because a malformed `set` renders the pigeonhole invariants
///      the ARITY arm relies on unsound with a PHANTOM-`M`).
///   2. ARITY-MISMATCH: `N` MUST equal `M` — a bijection between
///      `[0..N)` and the target set `set` (whose cardinality now
///      provably equals `M` post-clause-1's well-formedness check)
///      forces the cardinality equality by pigeonhole. A regression
///      that adds a spurious duplicate entry to a HASH_DISCRIMINATORS
///      array (bumping `N` past the set's cardinality) fails-loudly at
///      this arm with the ARITY-MISMATCH-provenance panic message.
///      Delegated to no sibling — this arm is the compound helper's
///      unique contribution.
///   3. Pairwise-distinctness: every pair of entries is distinct —
///      delegated to [`assert_u8_array_pairwise_distinct`].
///   4. Set-membership + full-set-coverage: every entry lies in `set`
///      AND every set byte is reached — delegated to
///      [`assert_u8_array_covers_finite_set`] (which sweeps BOTH the
///      SET-MEMBERSHIP and FULL-COVERAGE arms, AND re-runs clause 1's
///      SET-WELL-FORMEDNESS delegation as defense-in-depth; all three
///      bind through the one delegation call).
///
/// (1) ∧ (2) ∧ (3) ∧ (4) jointly imply the array's entries EXACTLY
/// partition the set: `N == M` distinct entries chosen from a set of
/// cardinality `M` (proven-well-formed by clause 1) MUST equal the set
/// by pigeonhole. The single compound invocation therefore binds
/// the same theorem as the pair `assert_u8_array_pairwise_distinct(
/// &arr) + assert_u8_array_covers_finite_set::<N, M>(&arr, &set)` PLUS
/// the arity-mismatch check (1) that neither weak sibling carries
/// alone — a strictly stronger contract at HALF the per-array
/// witness-line surface.
///
/// Compression: pre-lift,
/// [`crate::error::StructuralKind::HASH_DISCRIMINATORS`] (`[u8; 2]`
/// permuting the non-contiguous partition `{0, 2}`) bound its
/// permutation-of-finite-set contract at TWO `const _` lines (one
/// `assert_u8_array_pairwise_distinct` for INJECTIVITY, one
/// `assert_u8_array_covers_finite_set` for SURJECTIVITY-onto-set) —
/// two scattered per-axis witness lines that would silently drift out
/// of lockstep if one was updated without the other. Post-lift the
/// array binds the same theorem PLUS the arity-mismatch check at ONE
/// `const _` line — a 2:1 compression at strictly stronger contract
/// strength, symmetric to the sibling
/// [`assert_u8_array_permutes_inclusive_range`]'s 2:1 compression on
/// the three range-covering permutation-shaped arrays. Together the
/// two compound helpers close the WHOLE compound tier of the
/// substrate's `u8` array vocabulary: `StructuralKind` (on the non-
/// contiguous corner) plus `AtomKind` / `QuoteForm` / `UnquoteForm`
/// (on the contiguous corner) — four permutation-shaped arrays across
/// both contiguity postures now bind their compound
/// (INJECTIVITY ∧ SURJECTIVITY ∧ ARITY) permutation contract at ONE
/// `const _` line each. [`crate::error::SexpShape::HASH_DISCRIMINATORS`]
/// stays on the range-coverage-only single-axis sibling helper because
/// its intentionally-non-injective twelve-shape → seven-byte collapse
/// means INJECTIVITY does not hold — it CANNOT bind a permutation
/// contract on any contiguity corner.
///
/// The invariant is load-bearing for `StructuralKind`'s non-contiguous
/// sub-carve `{0, 2}` on the outer-`Sexp` cache-key partition:
/// `Sexp::Nil` and `Sexp::List(_)` MUST map bijectively to `{0u8, 2u8}`
/// so `Hash for Sexp`'s outer discriminator hash sequence stays
/// injective on the structural-residual sub-partition. The intentional
/// gap at `1u8` — where the atomic-carve outer marker
/// [`AtomKind::OUTER_HASH_DISCRIMINATOR`] lives — is EXACTLY the
/// reason StructuralKind CANNOT bind through the sibling
/// [`assert_u8_array_permutes_inclusive_range`] helper (its distinct-
/// value set is not a contiguous inclusive range). This compound
/// helper is the non-contiguous corner where StructuralKind's compound
/// contract binds at ONE line. A regression that silently unified two
/// StructuralKind arms' cache-key bytes (a duplicate on the
/// INJECTIVITY arm), OR lifted a fresh entry into the atomic-carve
/// gap at `1u8` (a drift on the SET-MEMBERSHIP arm), OR dropped an
/// entry making the set non-covering (a drift on the SET-BYTE-MISSING
/// arm), OR bumped `N` past the set cardinality (a drift on the ARITY
/// arm), would silently invalidate every cached `Sexp::List(_)` /
/// `Sexp::Nil` participating in `Expander::cache` — pre-lift these
/// four modes were caught only at runtime by the sibling helpers'
/// runtime tests + the pre-lift weak `const _` pair, post-lift the
/// compound `const _` witness catches all four drift modes at COMPILE
/// time at ONE line.
///
/// Adding a new family-wide `[u8; N]` permutation-of-finite-set array
/// to the substrate: pair the declaration with `const _: () =
/// assert_u8_array_permutes_finite_set::<N, M>(&Self::FOO_ARRAY,
/// &[…set…]);` co-located after the array's declaration and the
/// permutation-of-finite-set contract binds at compile time. The
/// rustc-forced arity `[u8; N]` composes with this const-eval sweep so
/// cardinality AND arity-cardinality-match AND set-membership AND
/// pairwise-distinctness AND (by pigeonhole) full set-coverage are
/// ALL compile-time theorems on the SAME array from ONE `const _`
/// line. Prefer this compound helper over the weak-pair pattern for
/// any array whose distinct-value set is intentionally EXACTLY the
/// given finite set with the array acting as a permutation of it —
/// the two weak helpers stay as the fallback for arrays with LOOSER
/// contracts. Prefer the tighter
/// [`assert_u8_array_permutes_inclusive_range`] sibling when the
/// target finite set IS a contiguous inclusive range — this helper is
/// the fallback for the non-contiguous corner.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — pinned by the four
/// negative runtime pins
/// (`_panics_at_runtime_on_arity_below_cardinality`,
/// `_panics_at_runtime_on_arity_above_cardinality`,
/// `_panics_at_runtime_on_duplicate`,
/// `_panics_at_runtime_on_out_of_set`) that jointly exercise each of
/// the three failure arms.
///
/// The ARITY-MISMATCH panic site carries the same axis-provenance
/// string `"ARITY-MISMATCH"` as the sibling
/// [`assert_u8_array_permutes_inclusive_range`]'s ARITY arm — the two
/// compound permutation helpers SHARE the arity axis-name because the
/// axis is the SAME (a cardinality-equality contract), but the HELPER
/// name in the panic message routes UNAMBIGUOUSLY to the SPECIFIC
/// contiguity corner (`"assert_u8_array_permutes_finite_set"` vs.
/// `"assert_u8_array_permutes_inclusive_range"`) — string search on
/// the axis PLUS the helper name jointly disambiguates the failed
/// (helper, axis) pair. The two delegated helpers each panic with
/// THEIR OWN provenance strings so drift on the pairwise-distinctness
/// or set-coverage arm surfaces with the respective sibling helper's
/// message body (`"duplicate"` on the INJECTIVITY axis; `"OUT-OF-SET"`
/// / `"SET-BYTE-MISSING"` on the SURJECTIVITY axis).
///
/// Theory grounding:
/// - THEORY.md §V.1 — knowable platform; the family-wide permutation-
///   of-finite-set contract on the `u8` cache-key vocabulary becomes
///   a TYPE-LEVEL theorem the substrate carries per array declaration
///   at ONE `const _` line rather than at TWO per-axis `const _` lines
///   the developer must remember to keep in lockstep across every
///   permutation-of-finite-set-shaped HASH_DISCRIMINATORS array.
/// - THEORY.md §V.3 — three-pillar attestation; the outer-`Sexp`
///   cache-key partition is the `intent_hash` composition axis —
///   binding the non-contiguous permutation-shaped sub-carvings'
///   arrays on the typed algebra makes cardinality drift a compile
///   error rather than a silent `Hash for Sexp` mis-hash on a caller
///   keyed on a non-contiguous permutation-shaped sub-carve.
/// - THEORY.md §VI.1 — generation over composition; the compound
///   arity-check + set-coverage + pairwise-distinctness sweep IS the
///   generative shape. Every new closed-set discriminator array whose
///   distinct-value set is an intentionally-closed non-contiguous
///   finite partition with the array acting as a permutation of it
///   adds ONE `const _` line to get the permutation theorem rather
///   than re-deriving TWO per-axis `const _` lines (one for
///   injectivity, one for surjectivity) that would silently drift out
///   of lockstep if one was updated without the other.
/// - THEORY.md §II.1 invariant 5 — composition preserves proofs; the
///   compound permutation-of-finite-set proof at declaration site AND
///   the consumer site (`StructuralKind` sub-carve inside
///   `Hash for Sexp` on `Sexp::Nil` / `Sexp::List(_)`) regenerate
///   through the SAME `const _` witness.
///
/// Compound sibling posture on the (contiguity) axis:
/// [`assert_u8_array_permutes_inclusive_range`] closes the CONTIGUOUS-
/// INCLUSIVE-RANGE corner (three arrays); this helper closes the
/// NON-CONTIGUOUS-FINITE-SET corner (one array). The two together
/// close the whole (INJECTIVITY ∧ SURJECTIVITY ∧ ARITY) compound tier
/// of the substrate's `u8` array vocabulary on both contiguity
/// postures — every intentionally-closed permutation-shaped `[u8; N]`
/// HASH_DISCRIMINATORS array on the substrate now binds its compound
/// permutation contract at ONE `const _` line regardless of whether
/// the target is a contiguous inclusive range or an arbitrary
/// non-contiguous finite set.
pub const fn assert_u8_array_permutes_finite_set<const N: usize, const M: usize>(
    arr: &[u8; N],
    set: &[u8; M],
) {
    // Delegate target-set well-formedness to the sibling SET-side
    // pairwise-distinctness helper FIRST — even BEFORE the ARITY
    // check below. A malformed `set` (e.g. `[0u8, 2u8, 2u8]` at
    // `M = 3`) with a duplicate entry inflates the effective
    // cardinality with a PHANTOM-`M` and renders the pigeonhole
    // invariants unsound: an `arr` of arity `N == M` that is
    // pairwise-distinct and within-set would silently mis-verify
    // as a permutation of a cardinality-`M` set when it is really
    // covering a cardinality-`< M` set. Placing this arm FIRST
    // routes drift on the CALLER'S TARGET-SET SPEC to the SET-side
    // well-formedness axis rather than to a downstream ARITY-
    // MISMATCH / duplicate / OUT-OF-SET symptom on `arr` (three
    // of which would surface DEPENDING on how the caller's mistake
    // interacts with the `arr` under verification, producing
    // inconsistent operator diagnostics for the SAME underlying
    // root cause). The helper's own body re-runs this check via
    // the delegated `assert_u8_array_covers_finite_set` call at
    // the third arm below as defense-in-depth against a regression
    // that silently dropped this delegation at the top; the two
    // calls jointly bind the SET-side well-formedness contract at
    // TWO stages of the compound helper's delegation chain.
    assert_u8_finite_set_pairwise_distinct(set);
    // ARITY-MISMATCH check SECOND — pigeonhole forces `N == M` on a
    // bijection between `[0..N)` and `set` (given the SET-side
    // well-formedness delegated above; the pre-lift docstring's
    // "assuming `set` is itself pairwise-distinct" caveat is now a
    // compile-time theorem the substrate carries per call site).
    // Placing this arm HERE (after well-formedness) gives cleaner
    // provenance: a drift that grows the array past the set
    // cardinality would ALSO fail either the pairwise-distinct arm
    // (if the extra entry duplicates a within-set byte) OR the
    // covers-finite-set arm's `"OUT-OF-SET"` axis (if the extra
    // entry lies outside `set`), but the ARITY-MISMATCH-named panic
    // message routes the operator to the CARDINALITY axis directly
    // rather than to a downstream symptom on either weak-axis helper.
    if N != M {
        panic!(
            "assert_u8_array_permutes_finite_set: family-wide u8 array's \
             ARITY-MISMATCH — the compile-time array cardinality `N` \
             does not equal the target finite set's cardinality `M`. A \
             bijection between `[0..N)` and the target set forces `N \
             == M` by pigeonhole (given `set`'s well-formedness \
             delegated to `assert_u8_finite_set_pairwise_distinct` \
             at the top of this helper before the ARITY arm) — an \
             array whose arity \
             drifts above the set's cardinality CANNOT stay both \
             pairwise-distinct AND within the set (extras must \
             duplicate OR fall outside), and one whose arity drifts \
             below CANNOT reach every set byte. The substrate's \
             PERMUTATION-of-FINITE-SET contract on the array is broken \
             at the ARITY axis; every consumer that expects the \
             array's entries to bijectively permute the target set \
             (StructuralKind's `{{0, 2}}` non-contiguous sub-carving \
             on Hash for Sexp's outer discriminator partition around \
             the atomic-carve gap at `1u8`) relies on this cardinality \
             equality"
        );
    }
    // Delegate pairwise-distinctness to the sibling injectivity
    // helper SECOND (before the finite-set-coverage delegation). Order
    // matters for provenance-preservation on the failure modes: with
    // `N == M` (post-arity-check) and `set` well-formed, a duplicate
    // entry in `arr` pigeonhole-forces a missing set byte AND vice-
    // versa — the two axes are logically equivalent given arity-
    // cardinality-match. Placing pairwise-distinct BEFORE covers-
    // finite-set routes a duplicate to the sibling's `"duplicate"`-
    // named panic on the INJECTIVITY axis (rather than to the
    // covers-finite-set sibling's `"SET-BYTE-MISSING"`-named panic
    // on the SURJECTIVITY axis which would fire downstream on the
    // pigeonhole-forced coverage failure). Matches the sibling
    // `assert_u8_array_permutes_inclusive_range`'s ordering: name
    // the CAUSE (duplicate) rather than the pigeonhole-forced
    // downstream SYMPTOM (SET-BYTE-MISSING).
    assert_u8_array_pairwise_distinct(arr);
    // Delegate set-membership + full-set-coverage to the sibling
    // covers-finite-set helper THIRD. Given the two prior arms
    // (arity-cardinality-match + pairwise-distinct on `arr`), the
    // covers-finite-set helper's SECOND (`"SET-BYTE-MISSING"`) arm
    // becomes unreachable by pigeonhole assuming `set` is well-
    // formed: `N == M` distinct entries chosen from a set of
    // cardinality `M` MUST equal the set. Only the FIRST
    // (`"OUT-OF-SET"`) arm surfaces in practice — a drift that lifts
    // an entry outside `set` while staying pairwise-distinct panics
    // with the sibling's `"OUT-OF-SET"` provenance. The delegated
    // coverage sweep at the second arm is kept for DEFENSE-IN-DEPTH:
    // a regression that silently dropped the pairwise-distinct
    // delegation above would leave a duplicate uncaught by the
    // compound helper's OWN body, but the covers-finite-set
    // sibling's `"SET-BYTE-MISSING"` check would then catch it as a
    // safety-net symptom.
    assert_u8_array_covers_finite_set::<N, M>(arr, set);
}

// Compile-time permutation-of-finite-set witness — one `const _: () =
// assert_u8_array_permutes_finite_set::<N, M>(&…, &[…])` per family-
// wide `[u8; N]` hash-discriminator array on the substrate's closed-
// set outer algebras whose distinct-value set is an intentionally-
// closed non-contiguous finite partition with the array acting as a
// permutation of it. Each invocation is const-evaluated at `cargo
// check` time; a regression that silently drifts the array's
// cardinality away from the set's cardinality OR silently collides
// two entries OR silently drifts an entry outside the set (including
// the archetype drift into the intentional gap at `1u8`) fails the
// build rather than the test suite. Compression peer to the pre-lift
// `assert_u8_array_pairwise_distinct` + `assert_u8_array_covers_
// finite_set` weak-witness pair on the (axis-count) axis: those bound
// `StructuralKind::HASH_DISCRIMINATORS`' invariants at TWO `const _`
// lines (one per axis); this compound helper binds the same theorem
// PLUS the arity-cardinality-equality contract at ONE `const _`
// line — a 2:1 compression at strictly stronger contract strength.
// Contiguity-axis peer to the three `assert_u8_array_permutes_
// inclusive_range` witnesses above: those close the contiguous-
// inclusive-range corner of the compound tier at the three
// permutation-shaped range-covering HASH_DISCRIMINATORS arrays
// (`AtomKind`, `QuoteForm`, `UnquoteForm`); this closes the non-
// contiguous-finite-set corner at the ONE non-contiguous-covering
// permutation-shaped array (`StructuralKind`). Together the two
// compound helpers close the WHOLE compound (INJECTIVITY ∧
// SURJECTIVITY ∧ ARITY) tier of the substrate's `u8` array vocabulary
// on both contiguity postures — every intentionally-closed
// permutation-shaped `[u8; N]` HASH_DISCRIMINATORS array on the
// substrate now binds its compound permutation contract at ONE
// `const _` line regardless of whether the target is a contiguous
// inclusive range or an arbitrary non-contiguous finite set.
const _: () = assert_u8_array_permutes_finite_set::<2, 2>(
    &crate::error::StructuralKind::HASH_DISCRIMINATORS,
    &[0u8, 2u8],
);

/// Compile-time compound (INJECTIVITY ∧ SURJECTIVITY ∧ ARITY) JOINT
/// permutation-of-inclusive-range verifier for a `(scalar, [u8; M], [u8; N])`
/// triple — the (`scalar-plus-two-arrays`) corner of the (carving-shape)
/// axis peer to [`assert_u8_array_permutes_inclusive_range`]'s
/// (`single-array`) corner. Panics at const-eval time (or at runtime for
/// dynamic callers) with an axis-provenance-named message iff the joint
/// union `{scalar} ∪ arr_a ∪ arr_b` fails ANY of:
///
///   1. ARITY-MISMATCH — `1 + M + N != HI - LO + 1`. A joint bijection
///      between `[0..1+M+N)` and `[LO..=HI]` forces the cardinality
///      equality by pigeonhole. Placed FIRST so the panic message routes
///      the operator directly to the CARDINALITY axis rather than to a
///      downstream range-membership or count-exactly-once symptom.
///   2. SCALAR-OUT-OF-RANGE — `scalar < LO || scalar > HI`.
///   3. FIRST-ARRAY-OUT-OF-RANGE — any `arr_a[i] < LO || arr_a[i] > HI`.
///   4. SECOND-ARRAY-OUT-OF-RANGE — any `arr_b[j] < LO || arr_b[j] > HI`.
///   5. JOINT-MISSING — some byte in `[LO..=HI]` occurs ZERO times across
///      `{scalar} ∪ arr_a ∪ arr_b`. Given post-arity + post-in-range, this
///      is equivalent to JOINT-duplicate on some OTHER range byte by
///      pigeonhole, but the message routes to the SURJECTIVITY axis for
///      the specific missing byte.
///   6. JOINT-duplicate — some byte in `[LO..=HI]` occurs TWO or more times
///      across `{scalar} ∪ arr_a ∪ arr_b` (either cross-carving between
///      scalar and one array, cross-carving between the two arrays, OR
///      intra-carving inside a single array). Given post-arity +
///      post-in-range, this is equivalent to JOINT-MISSING on some other
///      range byte by pigeonhole, but the message routes to the
///      INJECTIVITY axis for the specific duplicated byte.
///
/// Arms 5 and 6 fuse into ONE `sweep [LO..=HI] and count exactly once` loop
/// — a byte with `count == 0` witnesses the SURJECTIVITY failure, a byte
/// with `count >= 2` witnesses the INJECTIVITY failure. The two logical
/// axes are equivalent given post-arity + post-in-range but the fused
/// sweep routes provenance to whichever byte violates first, matching the
/// (`"MISSING"` / `"duplicate"`) provenance vocabulary the sibling helpers
/// [`assert_u8_array_covers_inclusive_range`] and
/// [`assert_u8_array_pairwise_distinct`] use on the SINGLE-array corner.
///
/// Compression peer to a hypothetical decomposition through the three
/// pre-existing single-array helpers (`assert_u8_array_pairwise_distinct`
/// each on `[scalar]`/`arr_a`/`arr_b` + `assert_u8_array_covers_
/// inclusive_range` on the concatenation) on the (axis-count) axis: those
/// would need explicit concatenation at rustc time (impossible without
/// runtime `Vec`) OR three per-array + one joint-distinctness call
/// (four+ `const _` lines PLUS threading the joint check through a bespoke
/// primitive); this compound helper binds the SAME joint theorem PLUS the
/// scalar-plus-two-arrays cardinality-equality contract at ONE `const _`
/// line — the compression is 4:1 at strictly stronger contract strength on
/// the (scalar + two arrays) shape corner. Sibling posture on the
/// (carving-shape) axis of the substrate-primitive matrix:
///   * (single-array, permutes-range) — [`assert_u8_array_permutes_inclusive_range`]
///   * (scalar-plus-two-arrays, permutes-range) — THIS helper.
///
/// The load-bearing invariant this helper pins: the outer-`Sexp` cache-key
/// discriminator space `{0..=6}` partitions across the SUBSTRATE'S THREE
/// carvings — [`AtomKind::OUTER_HASH_DISCRIMINATOR`] (scalar `1u8` for
/// `Sexp::Atom(_)`), [`crate::error::StructuralKind::HASH_DISCRIMINATORS`]
/// (`[u8; 2]` at `{0, 2}` for `Sexp::Nil`/`Sexp::List(_)`),
/// [`QuoteForm::HASH_DISCRIMINATORS`] (`[u8; 4]` at `{3, 4, 5, 6}` for the
/// four quote-family variants). Post-lift the JOINT permutation binds at
/// rustc time via ONE `const _` witness; a drift at ANY of the three
/// carvings (renumbered atomic marker, extra `StructuralKind` variant with
/// a byte outside `{0, 2}`, collision between `QuoteForm` and the atomic
/// marker) becomes a compile error rather than a `sexp_shape_hash_
/// discriminator_partitions_by_three_way_carving_disjointly` /
/// `structural_kind_hash_discriminator_disjoint_from_atom_outer_carve_
/// byte_and_quote_form_hash_discriminator_partition` runtime-test
/// regression.
///
/// Theory anchor: THEORY.md §II.1 invariant 5 — composition preserves
/// proofs; the joint carving's compound permutation contract composes
/// through the three sub-algebras' `HASH_DISCRIMINATOR`s and the const-fn
/// contract preserves the joint permutation-of-range proof across `rustc`
/// invocations byte-for-byte. THEORY.md §III — the typescape; the joint-
/// partition property becomes a TYPE-level theorem on the substrate rather
/// than a per-carving test-time invariant. THEORY.md §V.3 — three-pillar
/// attestation; the outer-`Sexp` cache-key partition is the substrate's
/// outer `Sexp` `intent_hash` composition axis — binding the joint
/// permutation at rustc time makes attestation-key drift a compile error
/// rather than a silent BLAKE3 mis-hash.
pub const fn assert_scalar_plus_two_u8_arrays_permute_inclusive_range<
    const M: usize,
    const N: usize,
    const LO: u8,
    const HI: u8,
>(
    scalar: u8,
    arr_a: &[u8; M],
    arr_b: &[u8; N],
) {
    // ARITY-MISMATCH check FIRST — pigeonhole forces `1 + M + N ==
    // HI - LO + 1` on a joint bijection between `[0..1+M+N)` and
    // `[LO..=HI]`. Placing this arm FIRST gives cleaner provenance:
    // a drift that grows the joint cardinality past the range
    // cardinality would ALSO fail either the out-of-range arm OR
    // the joint-duplicate arm, but the ARITY-MISMATCH-named panic
    // routes the operator to the CARDINALITY axis directly rather
    // than to a downstream symptom on the other axes.
    let expected_cardinality = (HI - LO) as usize + 1;
    if 1 + M + N != expected_cardinality {
        panic!(
            "assert_scalar_plus_two_u8_arrays_permute_inclusive_range: \
             family-wide (scalar, [u8; M], [u8; N]) triple's ARITY-\
             MISMATCH — the compile-time joint cardinality `1 + M + N` \
             does not equal the target inclusive range's cardinality \
             `HI - LO + 1`. A joint bijection between `[0..1+M+N)` and \
             `[LO..=HI]` forces `1 + M + N == HI - LO + 1` by pigeonhole \
             — a joint carving whose cardinality drifts above the \
             range's CANNOT stay both jointly-pairwise-distinct AND \
             within the range (extras must duplicate OR fall outside), \
             and one whose cardinality drifts below CANNOT reach every \
             range byte. The substrate's JOINT PERMUTATION contract on \
             the outer-`Sexp` cache-key partition (AtomKind's outer \
             marker + StructuralKind + QuoteForm carvings jointly \
             covering `{{0..=6}}`) is broken at the ARITY axis; every \
             consumer that expects the joint carving to bijectively \
             permute the target range (Hash for Sexp's outer \
             discriminator partition, the three-carving-plus-atom-\
             marker joint disjointness contract) relies on this \
             cardinality equality"
        );
    }
    // SCALAR-OUT-OF-RANGE arm.
    if scalar < LO || scalar > HI {
        panic!(
            "assert_scalar_plus_two_u8_arrays_permute_inclusive_range: \
             family-wide (scalar, [u8; M], [u8; N]) triple's scalar \
             carries an OUT-OF-RANGE byte — the scalar lies outside \
             the target inclusive range `[LO, HI]`. The substrate's \
             RANGE-BOUND contract on the joint carving is broken at \
             the scalar carving's arm; every consumer that expects the \
             scalar-plus-two-arrays joint image to partition an outer \
             cache-key space (Hash for Sexp's outer discriminator \
             `{{0..=6}}`) relies on the scalar staying within the \
             target range"
        );
    }
    // FIRST-ARRAY-OUT-OF-RANGE arm.
    let mut i = 0;
    while i < M {
        if arr_a[i] < LO || arr_a[i] > HI {
            panic!(
                "assert_scalar_plus_two_u8_arrays_permute_inclusive_range: \
                 family-wide (scalar, [u8; M], [u8; N]) triple's first \
                 array carries an OUT-OF-RANGE entry at some position — \
                 the entry's byte lies outside the target inclusive \
                 range `[LO, HI]`. The substrate's RANGE-BOUND contract \
                 on the joint carving is broken at the first-array \
                 carving's arm",
            );
        }
        i += 1;
    }
    // SECOND-ARRAY-OUT-OF-RANGE arm.
    let mut j = 0;
    while j < N {
        if arr_b[j] < LO || arr_b[j] > HI {
            panic!(
                "assert_scalar_plus_two_u8_arrays_permute_inclusive_range: \
                 family-wide (scalar, [u8; M], [u8; N]) triple's second \
                 array carries an OUT-OF-RANGE entry at some position — \
                 the entry's byte lies outside the target inclusive \
                 range `[LO, HI]`. The substrate's RANGE-BOUND contract \
                 on the joint carving is broken at the second-array \
                 carving's arm",
            );
        }
        j += 1;
    }
    // JOINT-DISTINCTNESS ∧ JOINT-SURJECTIVITY fused via sweep-and-count.
    // Given post-arity + post-in-range, the two logical axes are
    // equivalent by pigeonhole but the fused sweep routes provenance to
    // whichever byte violates first with the sibling helpers'
    // (`"MISSING"` / `"duplicate"`) vocabulary preserved.
    let mut b = LO;
    loop {
        let mut count: u32 = 0;
        if scalar == b {
            count += 1;
        }
        let mut i = 0;
        while i < M {
            if arr_a[i] == b {
                count += 1;
            }
            i += 1;
        }
        let mut j = 0;
        while j < N {
            if arr_b[j] == b {
                count += 1;
            }
            j += 1;
        }
        if count == 0 {
            panic!(
                "assert_scalar_plus_two_u8_arrays_permute_inclusive_range: \
                 family-wide (scalar, [u8; M], [u8; N]) triple is JOINT-\
                 MISSING a byte from the target inclusive range \
                 `[LO, HI]` — every byte in the range must appear at \
                 least once across the joint union `{{scalar}} ∪ arr_a \
                 ∪ arr_b`. The substrate's JOINT FULL-COVERAGE contract \
                 on the outer-`Sexp` cache-key partition is broken; the \
                 SURJECTIVITY axis of the joint permutation fails on \
                 the specific missing range byte",
            );
        }
        if count >= 2 {
            panic!(
                "assert_scalar_plus_two_u8_arrays_permute_inclusive_range: \
                 family-wide (scalar, [u8; M], [u8; N]) triple carries a \
                 JOINT duplicate byte — some byte in `[LO, HI]` appears \
                 TWO or more times across the joint union `{{scalar}} ∪ \
                 arr_a ∪ arr_b` (either cross-carving between scalar and \
                 an array, cross-carving between the two arrays, OR \
                 intra-carving inside a single array). The substrate's \
                 JOINT PAIRWISE-DISTINCTNESS contract on the outer-\
                 `Sexp` cache-key partition is broken; the INJECTIVITY \
                 axis of the joint permutation fails on the specific \
                 duplicated range byte",
            );
        }
        if b == HI {
            break;
        }
        b += 1;
    }
}

// Compile-time permutation-of-range witnesses — one `const _: () =
// assert_u8_array_permutes_inclusive_range::<N, LO, HI>(&…)` per
// family-wide `[u8; N]` hash-discriminator array on the substrate's
// closed-set outer algebras whose distinct-value set is an
// intentionally-closed contiguous inclusive range with the array
// acting as a permutation of it. Each invocation is const-evaluated
// at `cargo check` time; a regression that silently drifts the
// array's cardinality above the range's cardinality OR silently
// collides two entries OR silently drifts an entry outside the range
// fails the build rather than the test suite. Compression peer to
// the pre-existing `assert_u8_array_pairwise_distinct` +
// `assert_u8_array_covers_inclusive_range` weak-witness pair on the
// (axis-count) axis: those bind the SAME three arrays' invariants at
// TWO `const _` lines per array (six lines total across the three
// arrays); this compound helper binds the same theorem PLUS the
// arity-cardinality-equality contract at ONE `const _` line per
// array (three lines total across the three arrays) — a 2:1
// compression at strictly stronger contract strength.
// `StructuralKind::HASH_DISCRIMINATORS` stays on the weak-pair
// (pairwise-distinct + covers-finite-set) pattern because its
// distinct-value set `{0, 2}` is NON-contiguous (gap at `1u8` where
// the atomic-carve outer marker lives) — the non-contiguous corner
// binds through a future `assert_u8_array_permutes_finite_set`
// compound helper on the non-contiguous corner of the (contiguity)
// axis. `SexpShape::HASH_DISCRIMINATORS` stays on the range-
// coverage-only pattern because its intentionally-non-injective
// twelve-shape → seven-byte collapse means INJECTIVITY does not hold
// — it CANNOT bind a permutation contract on any range corner.
const _: () = assert_u8_array_permutes_inclusive_range::<6, 0, 5>(&AtomKind::HASH_DISCRIMINATORS);
const _: () = assert_u8_array_permutes_inclusive_range::<4, 3, 6>(&QuoteForm::HASH_DISCRIMINATORS);
const _: () = assert_u8_array_permutes_inclusive_range::<2, 5, 6>(
    &crate::error::UnquoteForm::HASH_DISCRIMINATORS,
);

// Compile-time FULL-ARRAY per-position ORDER pins — one `const _: () =
// assert_u8_array_slice_equals_u8_array::<N, N, 0>(&…, &[literal
// bytes; N])` per family-wide `[u8; N]` hash-discriminator
// SUB-CARVING array on the substrate's closed-set outer algebras.
// Each invocation exercises the [`assert_u8_array_slice_equals_u8_array`]
// helper at its FULL-ARRAY corner (`M == N`, `START == 0`) — the
// SLICE-EQUALS-ARRAY sweep collapses to an ALL-positions-equal-peer-
// array pointwise identity `arr == [b_0, b_1, …, b_{N-1}]`. The peer
// literal-byte sub-array on the RHS pins BOTH (a) the per-position
// ORDER of the outer array's declaration (the CANONICAL variant-
// declaration order that all `zip(ALL, HASH_DISCRIMINATORS)` consumers
// depend on) AND (b) each per-role `pub(crate) const *_HASH_DISCRIMINATOR`
// alias's canonical `u8` byte value the outer array's slots re-
// export. Strictly STRONGER on the (contract-strength) axis than the
// sibling permutation witnesses IMMEDIATELY ABOVE: those bind each
// array's IMAGE SET (`{0..=5}` for `AtomKind`, `{3..=6}` for
// `QuoteForm`, `{5..=6}` for `UnquoteForm`) via the JOINT
// (INJECTIVITY ∧ SURJECTIVITY ∧ ARITY) permutation-of-range contract
// but are SILENT on which SLOT of the array each byte lands at — a
// regression that swapped `SYMBOL_HASH_DISCRIMINATOR = 0` and
// `KEYWORD_HASH_DISCRIMINATOR = 1` (drifting `AtomKind::HASH_DISCRIMINATORS`
// from `[0, 1, 2, 3, 4, 5]` to `[1, 0, 2, 3, 4, 5]`) preserves the
// permutation witness's `{0..=5}` set-image AND the joint witness's
// scalar-plus-two-arrays `{0..=6}` set-image but silently misaligns
// the runtime pin `atom_kind_hash_discriminators_align_with_all_by_index`
// (which iterates `zip(AtomKind::ALL, AtomKind::HASH_DISCRIMINATORS)`
// and pins `HASH_DISCRIMINATORS[i] == ALL[i].hash_discriminator()` —
// after the swap `HASH_DISCRIMINATORS[0] == 1` but
// `ALL[0].hash_discriminator() == AtomKind::Symbol.hash_discriminator()
// == 0` fails the alignment at position 0). Post-lift the ARRAY-LEVEL
// per-position order binds at rustc time via ONE `const _` witness per
// array; a drift at either the per-role `pub(crate) const` byte OR
// the array declaration's ordering fails at `cargo check` BEFORE any
// test scheduler runs.
//
// The four `..._pin_legacy_cache_key_bytes` runtime pins the new
// witnesses supersede:
// * `atom_kind_hash_discriminators_pin_legacy_cache_key_bytes` (in
//   `ast.rs`) — six `assert_eq!` on `AtomKind::{SYMBOL, KEYWORD, STR,
//   INT, FLOAT, BOOL}_HASH_DISCRIMINATOR == {0, 1, 2, 3, 4, 5}`.
// * `quote_form_hash_discriminators_pin_legacy_cache_key_bytes` (in
//   `ast.rs`) — four `assert_eq!` on `QuoteForm::{QUOTE, QUASIQUOTE,
//   UNQUOTE, UNQUOTE_SPLICE}_HASH_DISCRIMINATOR == {3, 4, 5, 6}`.
// * `unquote_form_hash_discriminators_pin_legacy_cache_key_bytes` (in
//   `error.rs`) — two `assert_eq!` on `UnquoteForm::{UNQUOTE,
//   SPLICE}_HASH_DISCRIMINATOR == {5, 6}`.
// * `structural_kind_hash_discriminators_pin_legacy_cache_key_bytes`
//   (in `error.rs`) — two `assert_eq!` on `StructuralKind::{NIL,
//   LIST}_HASH_DISCRIMINATOR == {0, 2}`.
// Each runtime pin's fourteen total `assert_eq!` inline byte
// comparisons collapse to ONE `const _` witness per array (FOUR
// `const _` lines total) that bind the SAME per-role byte values
// AND the array's per-position ordering at rustc time. The runtime
// pins survive as sibling checks — they compose through the
// per-role `pub(crate) const` alias directly rather than the outer
// container array's declaration; a regression that drifted a
// per-role alias's declaration but LEFT the array's slot-i
// initializer with the correct literal byte inline (structurally
// distinct from the alias-source-of-truth path this family relies
// on) fails at the runtime pin as a distinct failure mode.
//
// Sibling posture to the four-witness EXHAUSTIVE per-position sweep
// on the OUTER `SexpShape::HASH_DISCRIMINATORS` container the trio
// of `assert_u8_array_slice_equals_u8_array::<12, {1, 4}, {0, 7, 8}>`
// witnesses + the `assert_u8_array_slice_is_scalar_replica::<12, 1, 7>`
// witness (all inside `ast.rs`, below the `Sexp` Hash impl area)
// close on the outer twelve-shape container. Those four witnesses
// pin the OUTER container against its FOUR sub-carvings; these four
// witnesses pin each SUB-CARVING array against its LITERAL bytes.
// Together the eight witnesses close the (outer container, sub-
// carving) × (per-position ORDER) 2×N face across the substrate's
// entire outer-`Sexp` cache-key hash-discriminator hierarchy at
// rustc time.
//
// `SexpShape::HASH_DISCRIMINATORS` is INTENTIONALLY OMITTED from
// this family sweep — the outer twelve-shape → seven-byte NON-
// INJECTIVE collapse means the outer container is NOT expressible
// as an equality with any literal `[u8; 12]` peer WITHOUT re-
// stating the six-way atomic-collapse block-constancy segment
// (which is ALREADY pinned via the sibling
// `assert_u8_array_slice_is_scalar_replica::<12, 1, 7>` witness
// below). The four SUB-CARVING arrays in this sweep ARE injective
// on their own carving; each one is expressible as `arr == [b_0,
// b_1, …, b_{N-1}]` with each `b_i` a DISTINCT byte, which is
// EXACTLY the shape `assert_u8_array_slice_equals_u8_array` at the
// FULL-ARRAY corner (`M == N`, `START == 0`) binds.
const _: () = assert_u8_array_slice_equals_u8_array::<6, 6, 0>(
    &AtomKind::HASH_DISCRIMINATORS,
    &[0u8, 1, 2, 3, 4, 5],
);
const _: () = assert_u8_array_slice_equals_u8_array::<4, 4, 0>(
    &QuoteForm::HASH_DISCRIMINATORS,
    &[3u8, 4, 5, 6],
);
const _: () = assert_u8_array_slice_equals_u8_array::<2, 2, 0>(
    &crate::error::UnquoteForm::HASH_DISCRIMINATORS,
    &[5u8, 6],
);
const _: () = assert_u8_array_slice_equals_u8_array::<2, 2, 0>(
    &crate::error::StructuralKind::HASH_DISCRIMINATORS,
    &[0u8, 2],
);

// Compile-time JOINT permutation-of-range witness — the ONE
// `(scalar, [u8; M], [u8; N])` triple across the substrate whose
// joint carving permutes the OUTER-`Sexp` cache-key discriminator
// range `{0..=6}` byte-for-byte. `AtomKind::OUTER_HASH_DISCRIMINATOR
// = 1u8` (the scalar arm on the atomic-carve marker byte for
// `Sexp::Atom(_)`) merges with `StructuralKind::HASH_DISCRIMINATORS
// = [0, 2]` (the structural-residual carving covering `Sexp::Nil`
// and `Sexp::List(_)` — NON-contiguous inside its own range because
// the `1u8` slot between `0` and `2` is reserved for the atomic-
// carve marker; this is EXACTLY the reason `StructuralKind::HASH_
// DISCRIMINATORS` stays on the weak-witness pair per the sibling
// comment above and does NOT bind through the single-array
// permutation helper) and `QuoteForm::HASH_DISCRIMINATORS = [3, 4,
// 5, 6]` (the quote-family carving covering `Sexp::Quote(_)` /
// `Sexp::Quasiquote(_)` / `Sexp::Unquote(_)` / `Sexp::UnquoteSplice
// (_)`, a permutation on its own range) to jointly cover the WHOLE
// outer-`Sexp` cache-key partition `{0..=6}`. Pre-lift this joint
// bijection was pinned ONLY at runtime via
// `structural_kind_hash_discriminator_disjoint_from_atom_outer_
// carve_byte_and_quote_form_hash_discriminator_partition` (in
// `error.rs`, sweeping the disjointness of the three carvings' byte
// spaces + full-range coverage via `BTreeSet`s) and
// `sexp_shape_hash_discriminator_partitions_by_three_way_carving_
// disjointly` (in `error.rs`, sweeping the shape-level `hash_
// discriminator` image partition via the three carvings'
// `as_atom_kind` / `as_quote_form` / `as_structural_kind`
// projections) — the theorem held only after `cargo test`
// scheduled the two tests. Post-lift the JOINT permutation binds at
// rustc time via ONE `const _` witness on the substrate CONSTANTS
// directly; a drift at ANY of the three carvings (renumbered atomic
// marker, an extra `StructuralKind` variant with a byte outside
// `{0, 2}`, a collision between `QuoteForm` and the atomic marker,
// an arity drift in either array) fails at `cargo check` BEFORE any
// test scheduler runs. The two runtime pins survive as sibling
// checks for the shape-level projection methods (a distinct failure
// mode from a drift in the constants themselves); together with
// this const witness the joint outer-`Sexp` partition theorem is
// enforced at BOTH stages of the toolchain — const-time on the
// CONSTANTS, test-time on the METHODS.
//
// The scalar-plus-two-arrays joint carving is the FIRST substrate
// primitive that binds a bijection across a NON-uniform tuple shape
// (a `u8` PLUS a `[u8; 2]` PLUS a `[u8; 4]`) — the pre-existing
// single-array `assert_u8_array_permutes_inclusive_range` witnesses
// above bind ONE-array permutations; a hypothetical decomposition
// through three single-array calls (one per carving) CANNOT bind
// the joint bijection without either concatenating the three
// carvings at rustc time (impossible without a runtime `Vec`) or
// threading joint-distinctness through a bespoke primitive
// separately (four+ `const _` lines total). The compound helper
// binds the joint theorem at ONE line.
const _: () = assert_scalar_plus_two_u8_arrays_permute_inclusive_range::<2, 4, 0, 6>(
    AtomKind::OUTER_HASH_DISCRIMINATOR,
    &crate::error::StructuralKind::HASH_DISCRIMINATORS,
    &QuoteForm::HASH_DISCRIMINATORS,
);

/// Compile-time contract verifier — panics at const evaluation time if
/// any entry of `arr` at positions `[START..END)` is NOT byte-equal to
/// the peer `scalar`.
///
/// Opens the SLICE-BLOCK-CONSTANCY column on the (`u8`) row of the
/// (element-type × contract-shape) matrix. Row-dual sibling posture to
/// the pre-existing (`&'static str`)-row helper
/// [`assert_str_array_is_concatenation_of_two_scalar_replicas`], but
/// specialised to the (u8) element type AND generalised from a
/// FIXED-PARTITION two-block-covering-the-full-array shape to an
/// ARBITRARY sub-slice `[START..END)` inside a possibly-longer array
/// `[0..N)`. Where the (str)-row helper binds a FULL-ARRAY partition
/// `arr == [head; K] ++ [tail; N - K]` (both blocks together cover
/// `[0..N)` exactly), this helper binds a SINGLE-BLOCK SUB-SLICE
/// `arr[START..END) == [scalar; END - START]` (the positions OUTSIDE
/// the slice are unconstrained by this witness — they can carry any
/// bytes, potentially bound by peer witnesses on other slices).
///
/// The load-bearing carrier on the substrate is
/// [`crate::error::SexpShape::HASH_DISCRIMINATORS`] (`[u8; 12]`), whose
/// positions `[1..7)` INTENTIONALLY collapse onto the SINGLE outer
/// cache-key byte [`AtomKind::OUTER_HASH_DISCRIMINATOR`] (`= 1u8`) —
/// the six atomic outer shapes (`Symbol` / `Keyword` / `String` /
/// `Int` / `Float` / `Bool`) all route through `Sexp::Atom(_)`'s
/// SINGLE outer marker byte on the outer-`Sexp` Hash algebra, so their
/// twelve-shape → seven-byte collapse condenses SIX shape slots into
/// ONE cache-key byte. The six per-role
/// [`SexpShape::SYMBOL_HASH_DISCRIMINATOR`] /
/// [`SexpShape::KEYWORD_HASH_DISCRIMINATOR`] /
/// [`SexpShape::STRING_HASH_DISCRIMINATOR`] /
/// [`SexpShape::INT_HASH_DISCRIMINATOR`] /
/// [`SexpShape::FLOAT_HASH_DISCRIMINATOR`] /
/// [`SexpShape::BOOL_HASH_DISCRIMINATOR`] `pub(crate) const` aliases
/// are ALL declared as `= crate::ast::AtomKind::OUTER_HASH_DISCRIMINATOR`
/// on the six atomic-outer arms, so the array-level slice-block-
/// constancy theorem `SexpShape::HASH_DISCRIMINATORS[1..7) == [OUTER; 6]`
/// is the ARRAY-LEVEL surface of the six per-role aliases' shared
/// upstream. A regression that silently reroutes ONE alias (e.g.
/// renames `SexpShape::SYMBOL_HASH_DISCRIMINATOR` to alias
/// `StructuralKind::LIST_HASH_DISCRIMINATOR` instead) OR that reorders
/// `SexpShape::ALL` so a NON-atomic shape lands in positions `[1..7)`
/// (e.g. moves `SexpShape::List` into slot `4`, drifting `LIST_BYTE
/// = 2` into the atomic-collapse slice) fails at `cargo check` BEFORE
/// any test scheduler runs, at ONE `const _` line rather than at the
/// pre-lift sextet of per-alias assertions inside
/// `sexp_shape_hash_discriminators_pin_legacy_outer_cache_key_bytes`.
///
/// Bounds preconditions and gate ordering: three CARDINALITY gates
/// fire at the TOP of the sweep BEFORE any per-position content check
/// begins, so a caller-side turbofish arity slip fails-loud on the
/// bounds axis rather than silently degenerating into a truncated or
/// vacuous sweep:
/// * `START > N` → `START-OUT-OF-BOUNDS` panic. The caller's slice
///   start index sits OUTSIDE the array's valid position range
///   `[0..N]` (inclusive upper bound: `START == N` is the empty-slice
///   corner and is legal). A silent slip past this gate would either
///   panic on `arr[i]` bounds-check at runtime (const-eval catches it
///   first) or, on an over-cautious future refactor that gated with a
///   raw `START >= N`, silently reject the legal `START == N` empty
///   corner.
/// * `END > N` → `END-OUT-OF-BOUNDS` panic. The caller's slice end
///   index sits OUTSIDE the array's valid position range `[0..N]`.
///   Analogous to the `START` gate; the two gates jointly enforce
///   `START, END ∈ [0..N]` before any content sweep.
/// * `START > END` → `INVERTED-RANGE` panic. The caller supplied a
///   right-open slice `[START..END)` whose left bound exceeds its
///   right bound — mathematically the empty slice, but semantically a
///   caller-side turbofish typo (e.g. `::<12, 7, 1>` instead of
///   `::<12, 1, 7>`). Routes to a distinct gate rather than silently
///   accepting the empty sweep so a coordinated typo across `START`
///   and `END` fails-loud on the ordering axis rather than passing
///   vacuously.
/// * `START == END` is a LEGAL empty-slice corner: the sweep never
///   enters the loop body and the helper accepts. The pre-check
///   sequence gates only STRICT violations (`>`) so both endpoints
///   (`START == 0` and `END == N`) remain in range and the `START ==
///   END` empty case degenerates cleanly.
///
/// Delegates to `u8`'s native `==` in const-fn context — no auxiliary
/// byte-equality helper needed (unlike the (str)-row peer's
/// [`str_bytes_equal`] delegation). The single-scalar SLICE-BLOCK-
/// CONSTANCY sweep is the simplest shape in the const-fn family: ONE
/// outer `while i < END` from `i = START`, ONE inner comparison, ONE
/// panic arm.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — pinned by
/// `assert_u8_array_slice_is_scalar_replica_panics_at_runtime_on_slice_content_drift`,
/// `assert_u8_array_slice_is_scalar_replica_panics_at_runtime_on_start_out_of_bounds`,
/// `assert_u8_array_slice_is_scalar_replica_panics_at_runtime_on_end_out_of_bounds`,
/// `assert_u8_array_slice_is_scalar_replica_panics_at_runtime_on_inverted_range`,
/// and
/// `assert_u8_array_slice_is_scalar_replica_panic_message_names_the_helper_and_slice_block_constancy_violation_axis`.
/// The panic-message axis-provenance strings
/// (`"SLICE-BLOCK-CONSTANCY-VIOLATION"`, `"START-OUT-OF-BOUNDS"`,
/// `"END-OUT-OF-BOUNDS"`, `"INVERTED-RANGE"`) are chosen DISTINCT
/// from every sibling helper's axis vocabulary so a diagnostic that
/// crosses helper boundaries stays unambiguous under `grep` on the
/// failed axis.
///
/// Theory grounding:
/// - THEORY.md §III — the typescape; the SLICE-BLOCK-CONSTANCY corner
///   on the (`u8`) row of the (element-type × contract-shape) matrix
///   becomes a TYPE-LEVEL theorem the substrate carries per (arr,
///   scalar, START, END) quadruple rather than a runtime iterator
///   sweep per quadruple. Complements the pre-existing (str)-row
///   FULL-ARRAY BLOCK-CONSTANCY sibling — the two together cover the
///   BLOCK-CONSTANCY column at BOTH the SUB-SLICE arity (this helper)
///   and the FULL-ARRAY-with-two-blocks arity (the sibling), on
///   COMPLEMENTARY element-type rows.
/// - THEORY.md §V.1 — knowable platform; the sub-slice constant-
///   block contract on the substrate's ONE MANY-TO-ONE-collapse
///   `[u8; N]` array binds at `cargo check` time via ONE `const _`
///   line, closing the drift-catch loop one invocation stage earlier
///   than the pre-lift sextet of per-alias assertions inside
///   `sexp_shape_hash_discriminators_pin_legacy_outer_cache_key_bytes`.
/// - THEORY.md §V.3 — three-pillar attestation; the outer-`Sexp`
///   cache-key partition is the `intent_hash` composition axis —
///   binding the six-way atomic-shape collapse at the ARRAY level
///   makes attestation-key drift on the atomic-collapse slice a
///   compile error rather than a silent BLAKE3 mis-hash across the
///   six atomic outer shapes.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   slice sweep IS the generative shape — every future MANY-TO-ONE
///   variant → canonical-projection substrate SUB-SLICE-CONSTANT
///   segment (a hypothetical `Signal::CLASSES` array whose middle
///   segment collapses several signal variants onto the SAME class
///   byte; a `ProcessPhase::CATEGORIES` array whose per-category
///   segments each collapse onto a shared category byte) picks up
///   the block-constant theorem at ONE new `const _` line rather
///   than at (END - START) inline byte comparisons per callsite.
pub const fn assert_u8_array_slice_is_scalar_replica<
    const N: usize,
    const START: usize,
    const END: usize,
>(
    arr: &[u8; N],
    scalar: u8,
) {
    if START > N {
        panic!(
            "assert_u8_array_slice_is_scalar_replica: START-OUT-OF-\
             BOUNDS — the const parameter `START` sits OUTSIDE the \
             array's valid position range `[0..N]` (inclusive upper \
             bound: `START == N` is the LEGAL empty-slice corner). \
             Fix at the `const _` witness's turbofish by reconciling \
             `START` against the array's declared arity `N`. The \
             START-OUT-OF-BOUNDS gate fires FIRST — a mistyped \
             `START` on the caller side fails HERE before any per-\
             position sweep begins, so a subtle bounds slip doesn't \
             silently degenerate into a vacuous sweep OR a panic \
             deeper in `arr[i]` bounds-checking."
        );
    }
    if END > N {
        panic!(
            "assert_u8_array_slice_is_scalar_replica: END-OUT-OF-\
             BOUNDS — the const parameter `END` sits OUTSIDE the \
             array's valid position range `[0..N]` (inclusive upper \
             bound: `END == N` is the LEGAL slice-to-end corner). \
             Fix at the `const _` witness's turbofish by reconciling \
             `END` against the array's declared arity `N`. Peer \
             gate to the START-OUT-OF-BOUNDS arm above — the two \
             gates jointly enforce `START, END ∈ [0..N]` before any \
             content sweep."
        );
    }
    if START > END {
        panic!(
            "assert_u8_array_slice_is_scalar_replica: INVERTED-RANGE \
             — the const parameters `START` and `END` satisfy `START \
             > END`, so the right-open slice `[START..END)` is \
             mathematically empty but semantically a caller-side \
             turbofish typo (e.g. `::<N, END, START>` instead of \
             `::<N, START, END>`). Routes to a distinct gate rather \
             than silently accepting the empty sweep so a coordinated \
             typo across the two const parameters fails-loud on the \
             ordering axis. The LEGAL empty-slice corner is `START \
             == END` (accepted without entering the sweep); the \
             STRICT `START > END` slip is what this gate rejects."
        );
    }
    let mut i = START;
    while i < END {
        if arr[i] != scalar {
            panic!(
                "assert_u8_array_slice_is_scalar_replica: SLICE-BLOCK-\
                 CONSTANCY-VIOLATION — the family-wide `[u8; N]` \
                 array `arr` carries a byte at some position in \
                 `[START..END)` (the SLICE segment) that does NOT \
                 byte-equal the peer `scalar`. The substrate's SLICE-\
                 BLOCK-CONSTANCY contract on the array-slice is \
                 broken; every consumer that reads `arr[START..END)` \
                 as a homogeneous constant block sharing ONE \
                 canonical byte with the peer `scalar` (the SIX \
                 atomic-outer-shape collapse onto `crate::ast::\
                 AtomKind::OUTER_HASH_DISCRIMINATOR` at positions \
                 `[1..7)` of `crate::error::SexpShape::HASH_\
                 DISCRIMINATORS` — the twelve-shape → seven-byte \
                 collapse condensing SIX atomic shape slots into ONE \
                 outer-`Sexp` cache-key byte; any future MANY-TO-ONE \
                 variant → canonical-projection substrate SUB-SLICE-\
                 CONSTANT segment) relies on this invariant. Fix at \
                 the ARRAY-DECLARATION site (the drifted `arr[i]` \
                 entry inside the slice segment) OR at the per-role \
                 scalar constant that `scalar` re-exports — the \
                 choice depends on whether the drift is an \
                 unintended slot reorder inside the slice OR a \
                 rename of the canonical projection byte upstream."
            );
        }
        i += 1;
    }
}

// Compile-time SLICE-BLOCK-CONSTANCY witness — the ONE `[u8; N]`
// array on the substrate whose ARRAY-LEVEL structure carries a MANY-
// TO-ONE-COLLAPSE SUB-SLICE segment. `SexpShape::HASH_DISCRIMINATORS`
// (`[u8; 12]`) has positions `[1..7)` INTENTIONALLY collapsing onto
// the SINGLE outer cache-key byte `AtomKind::OUTER_HASH_DISCRIMINATOR
// = 1u8` — the six atomic outer shapes (`Symbol` / `Keyword` /
// `String` / `Int` / `Float` / `Bool`) all route through `Sexp::Atom(_)
// `'s SINGLE outer marker byte on the outer-`Sexp` Hash algebra, so
// their twelve-shape → seven-byte collapse condenses SIX shape slots
// into ONE cache-key byte. Pre-lift this six-way collapse was pinned
// ONLY through the six per-alias runtime assertions inside
// `sexp_shape_hash_discriminators_pin_legacy_outer_cache_key_bytes`
// (`assert_eq!(SexpShape::SYMBOL_HASH_DISCRIMINATOR, 1)` × six roles);
// post-lift the ARRAY-LEVEL slice constancy `SexpShape::HASH_
// DISCRIMINATORS[1..7) == [OUTER; 6]` binds at rustc-time via ONE
// `const _` line, one invocation stage earlier than the runtime pin.
// A regression that reorders `SexpShape::ALL` so a non-atomic variant
// lands in the atomic-collapse slice (e.g. moves `SexpShape::List`
// into slot `4`, drifting `LIST_BYTE = 2` into positions `[1..7)`) OR
// that reroutes ONE atomic-shape alias to a different upstream byte
// fails-loudly HERE at const-eval on the ARRAY-LEVEL slice.
//
// The three OTHER load-bearing SexpShape::HASH_DISCRIMINATORS slices
// are intentionally OMITTED from this compile-time sweep because they
// are ALREADY compile-time-enforced through TIGHTER contracts: the
// singleton slices `[0..1) == [NIL_BYTE]` and `[7..8) == [LIST_BYTE]`
// (`StructuralKind::NIL_HASH_DISCRIMINATOR` and `StructuralKind::LIST_
// HASH_DISCRIMINATOR`) are pinned via the peer `assert_scalar_plus_
// two_u8_arrays_permute_inclusive_range` witness above (which binds
// the outer joint bijection `{0..=6} == {OUTER} ⊕ StructuralKind::
// HASH_DISCRIMINATORS ⊕ QuoteForm::HASH_DISCRIMINATORS`); the four-
// element tail slice `[8..12) == QuoteForm::HASH_DISCRIMINATORS`
// (`[3, 4, 5, 6]`) is pinned via the peer `assert_u8_array_permutes_
// inclusive_range::<4, 3, 6>` witness above (which binds the tail
// slice's PERMUTATION-of-`[3..=6]` shape). Only the middle atomic-
// collapse slice `[1..7)` requires a NEW helper — its shape is
// MANY-TO-ONE-BLOCK-CONSTANT rather than PERMUTATION (which is
// injective and would fail on this six-of-one collapse) or SUBSET
// (which is weaker and would accept the drifted `[1, 1, 2, 1, 1, 1]`
// slice that this witness rejects on position 2).
const _: () = assert_u8_array_slice_is_scalar_replica::<12, 1, 7>(
    &crate::error::SexpShape::HASH_DISCRIMINATORS,
    AtomKind::OUTER_HASH_DISCRIMINATOR,
);

/// Compile-time contract verifier — panics at const evaluation time if
/// any entry of `full` at positions `[START..START + M)` is NOT byte-
/// equal to the peer `sub` entry at the same offset `[i - START]`.
///
/// Opens the SLICE-EQUALS-ARRAY column on the (`u8`) row of the
/// (element-type × contract-shape) matrix. Row-sibling posture to the
/// pre-existing SLICE-BLOCK-CONSTANCY corner on the SAME (`u8`) row
/// ([`assert_u8_array_slice_is_scalar_replica`]) — where that helper
/// binds a sub-slice `full[START..END) == [scalar; END - START]` to a
/// SINGLE scalar (a MANY-TO-ONE-COLLAPSE shape whose per-position
/// image is a CONSTANT byte), this helper binds a sub-slice
/// `full[START..START + M) == sub[..]` to a SIBLING ARRAY of arity `M`
/// (a POSITIONWISE-COMPOSITION shape whose per-position image is
/// carried by an INDEPENDENT peer array). The two together cover the
/// SUB-SLICE column at BOTH the SINGLE-scalar-image arity (the sibling
/// above) AND the ARRAY-of-length-`M`-image arity (this helper).
///
/// The load-bearing carrier on the substrate is the pair
/// ([`crate::error::SexpShape::HASH_DISCRIMINATORS`] (`[u8; 12]`),
/// [`QuoteForm::HASH_DISCRIMINATORS`] (`[u8; 4]`)) at the SexpShape
/// sub-slice `[8..12)`. Both arrays share their four byte values
/// (`3`, `4`, `5`, `6`) via the four per-role
/// [`QuoteForm::QUOTE_HASH_DISCRIMINATOR`] /
/// [`QuoteForm::QUASIQUOTE_HASH_DISCRIMINATOR`] /
/// [`QuoteForm::UNQUOTE_HASH_DISCRIMINATOR`] /
/// [`QuoteForm::UNQUOTE_SPLICE_HASH_DISCRIMINATOR`] `pub(crate) const`
/// aliases, but the two per-array declaration LISTINGS are independent
/// — a regression that reordered ONE array's arm listing without
/// reordering the other's (e.g. swapped positions 10 and 11 of the
/// outer `SexpShape::HASH_DISCRIMINATORS` array so `UNQUOTE_SPLICE`'s
/// byte `6` slid ahead of `UNQUOTE`'s byte `5` while leaving
/// `QuoteForm::HASH_DISCRIMINATORS` in its canonical order) would
/// preserve BOTH arrays' PERMUTATION-of-`[3..=6]` contract — the
/// pre-existing weak witness
/// [`assert_u8_array_permutes_inclusive_range::<4, 3, 6>`] on
/// [`QuoteForm::HASH_DISCRIMINATORS`] above binds the tail SLICE'S
/// image SET (`{3, 4, 5, 6}`) but is SILENT on the tail slice's
/// per-position ORDER against the peer [`QuoteForm::HASH_DISCRIMINATORS`]
/// listing. Pre-lift the POSITIONWISE-tail-equality against the sub-
/// carving array was pinned ONLY at runtime through the per-position
/// sweep inside
/// `sexp_shape_hash_discriminators_align_with_sub_carvings_by_projection`
/// (in `error.rs`), which routes each `SexpShape::HASH_DISCRIMINATORS
/// [i]` through the shape's sub-carving projection method
/// (`as_quote_form().unwrap().hash_discriminator()`) at test-time.
/// Post-lift the ARRAY-LEVEL slice-equals-array contract binds at
/// rustc-time via ONE `const _` line on the substrate CONSTANTS
/// directly — a regression that reordered ONE array's arm listing
/// fails at `cargo check` BEFORE any test scheduler runs.
///
/// Bounds preconditions and gate ordering: two CARDINALITY gates fire
/// at the TOP of the sweep BEFORE any per-position content check
/// begins, so a caller-side turbofish arity slip fails-loud on the
/// bounds axis rather than silently degenerating into a truncated or
/// vacuous sweep:
/// * `START > N` → `START-OUT-OF-BOUNDS` panic. The caller's slice
///   start index sits OUTSIDE the outer array's valid position range
///   `[0..N]` (inclusive upper bound: `START == N` combined with
///   `M == 0` is the LEGAL empty-slice corner and is accepted). A
///   silent slip past this gate would either panic on `full[START +
///   i]` bounds-check at runtime (const-eval catches it first) or, on
///   an over-cautious future refactor that gated with a raw `START >=
///   N`, silently reject the legal `START == N, M == 0` empty corner.
/// * `M > N - START` → `SLICE-LENGTH-OUT-OF-BOUNDS` panic. The
///   caller's sub-array arity `M` overruns the outer array's tail
///   `[START..N)` — semantically equivalent to `START + M > N` but
///   phrased through subtraction to avoid `usize` arithmetic overflow
///   on the (unrealistic but pedantic) `START, M` pair with
///   `START + M > usize::MAX`; gate 1 guarantees `START ≤ N` so
///   `N - START` never underflows. The overrun would land the sweep
///   at `full[START + i]` for some `i ∈ [N - START..M)` and panic
///   deeper in bounds-checking with a helper-name-less message.
/// * `M == 0` is a LEGAL empty-sub-array corner (the sweep never
///   enters the loop body and the helper accepts, regardless of
///   `START`). `START == N` with `M == 0` collapses to the empty-slice
///   corner at the RIGHT endpoint. The pre-check sequence gates only
///   STRICT violations (`>`) so both degenerate corners
///   (`M == 0`, `M == N - START` at the exact-fit right endpoint)
///   remain in range.
///
/// Delegates to `u8`'s native `==` in const-fn context — no auxiliary
/// byte-equality helper needed. The two-array positionwise-composition
/// sweep is the natural arity extension of the single-scalar sibling
/// above: ONE outer `while i < M` from `i = 0`, ONE inner comparison
/// `full[START + i] != sub[i]`, ONE panic arm.
///
/// Runtime callability: the function is a normal `pub const fn`, so
/// callers CAN also invoke it at runtime — pinned by
/// `assert_u8_array_slice_equals_u8_array_panics_at_runtime_on_positionwise_drift`,
/// `assert_u8_array_slice_equals_u8_array_panics_at_runtime_on_start_out_of_bounds`,
/// `assert_u8_array_slice_equals_u8_array_panics_at_runtime_on_slice_length_out_of_bounds`,
/// and
/// `assert_u8_array_slice_equals_u8_array_panic_message_names_the_helper_and_slice_equals_array_violation_axis`.
/// The panic-message axis-provenance strings
/// (`"SLICE-EQUALS-ARRAY-VIOLATION"`, `"START-OUT-OF-BOUNDS"`,
/// `"SLICE-LENGTH-OUT-OF-BOUNDS"`) are chosen DISTINCT from every
/// sibling helper's axis vocabulary — the sibling
/// [`assert_u8_array_slice_is_scalar_replica`] carries
/// `"SLICE-BLOCK-CONSTANCY-VIOLATION"` / `"END-OUT-OF-BOUNDS"` /
/// `"INVERTED-RANGE"` on the SINGLE-scalar-image sweep, so a
/// diagnostic that crosses the two SUB-SLICE helpers routes back to
/// its authoring helper by axis string alone. The
/// `SLICE-LENGTH-OUT-OF-BOUNDS` axis renames what would be the
/// sibling's `END-OUT-OF-BOUNDS` gate to reflect the shift from
/// `(START, END)` const generics to `(START, M)` — the CARDINALITY
/// carrier is the peer array's arity `M`, not an END index.
///
/// Theory grounding:
/// - THEORY.md §III — the typescape; the SLICE-EQUALS-ARRAY corner on
///   the (`u8`) row of the (element-type × contract-shape) matrix
///   becomes a TYPE-LEVEL theorem the substrate carries per
///   `(full, sub, START)` triple rather than a runtime iterator sweep
///   through the sub-carving projection method per triple.
///   Complements the pre-existing SLICE-BLOCK-CONSTANCY sibling on
///   the SAME row — the two together open the SUB-SLICE column at
///   BOTH the SINGLE-scalar-image arity (constant block) AND the
///   ARRAY-of-length-`M`-image arity (positionwise composition).
/// - THEORY.md §V.1 — knowable platform; the positionwise
///   composition contract binding
///   `SexpShape::HASH_DISCRIMINATORS[8..12] ==
///   QuoteForm::HASH_DISCRIMINATORS` at rustc-time closes the drift-
///   catch loop one invocation stage earlier than the pre-lift
///   per-position runtime sweep inside
///   `sexp_shape_hash_discriminators_align_with_sub_carvings_by_projection`.
///   The runtime pin survives as a sibling check for the SHAPE-level
///   projection method chain (a distinct failure mode from a drift
///   in the constants themselves); together the two enforce the
///   theorem at BOTH stages of the toolchain.
/// - THEORY.md §V.3 — three-pillar attestation; the outer-`Sexp`
///   cache-key partition is the `intent_hash` composition axis —
///   binding the quote-family tail-slice's per-position ORDER at the
///   ARRAY level makes attestation-key drift on the four-slot quote-
///   family sub-carving a compile error rather than a silent BLAKE3
///   mis-hash across the four quote-family outer shapes.
/// - THEORY.md §VI.1 — generation over composition; the const-eval
///   slice sweep IS the generative shape — every future substrate
///   POSITIONWISE-COMPOSITION between a container array's sub-slice
///   and a sub-carving's canonical `[u8; M]` listing (a hypothetical
///   `Signal::CATEGORIES` outer array whose middle segment is
///   pointwise equal to a `CriticalSignal::CATEGORIES` sub-carving
///   array; a `ProcessPhase::ORDER` array whose leading segment is
///   pointwise equal to a `PreparationPhase::ORDER` sub-carving)
///   picks up the positionwise-equality theorem at ONE new `const _`
///   line rather than at `M` inline byte comparisons per callsite.
pub const fn assert_u8_array_slice_equals_u8_array<
    const N: usize,
    const M: usize,
    const START: usize,
>(
    full: &[u8; N],
    sub: &[u8; M],
) {
    if START > N {
        panic!(
            "assert_u8_array_slice_equals_u8_array: START-OUT-OF-\
             BOUNDS — the const parameter `START` sits OUTSIDE the \
             outer array's valid position range `[0..N]` (inclusive \
             upper bound: `START == N` combined with `M == 0` is the \
             LEGAL empty-slice-at-right-endpoint corner). Fix at the \
             `const _` witness's turbofish by reconciling `START` \
             against the outer array's declared arity `N`. The \
             START-OUT-OF-BOUNDS gate fires FIRST — a mistyped \
             `START` on the caller side fails HERE before the peer \
             `SLICE-LENGTH-OUT-OF-BOUNDS` gate reads `N - START` \
             (which would underflow `usize` had this gate not caught \
             the slip), so a subtle bounds slip doesn't silently \
             degenerate into a subtraction wrap-around OR a panic \
             deeper in `full[START + i]` bounds-checking."
        );
    }
    if M > N - START {
        panic!(
            "assert_u8_array_slice_equals_u8_array: SLICE-LENGTH-OUT-\
             OF-BOUNDS — the peer sub-array's arity `M` exceeds the \
             outer array's tail cardinality `N - START`, so the \
             positionwise sweep `full[START + i]` for `i ∈ [0..M)` \
             would overrun the outer array's valid position range \
             `[0..N)` at some `i ∈ [N - START..M)`. Fix at the \
             `const _` witness's turbofish by reconciling `M` against \
             the outer array's tail cardinality `N - START` OR by \
             narrowing `START` to leave a longer tail. The peer \
             `START-OUT-OF-BOUNDS` gate above guarantees `START ≤ N` \
             so `N - START` never underflows `usize` at this gate. \
             The LEGAL exact-fit corner `M == N - START` (the sub-\
             array reaches EXACTLY to the outer array's right \
             endpoint) is accepted; the STRICT `M > N - START` slip \
             is what this gate rejects."
        );
    }
    let mut i = 0;
    while i < M {
        if full[START + i] != sub[i] {
            panic!(
                "assert_u8_array_slice_equals_u8_array: SLICE-EQUALS-\
                 ARRAY-VIOLATION — the outer `[u8; N]` array `full` \
                 carries a byte at some position `START + i` (for \
                 `i ∈ [0..M)`) that does NOT byte-equal the peer \
                 `[u8; M]` sub-array `sub` at the offset-matched \
                 position `i`. The substrate's SLICE-EQUALS-ARRAY \
                 positionwise-composition contract on the sub-slice \
                 `full[START..START + M) == sub[..]` is broken; \
                 every consumer that reads `full[START..START + M)` \
                 as a positionwise-aligned copy of the peer sub-\
                 carving array (the four-slot QUOTE-family tail \
                 `crate::error::SexpShape::HASH_DISCRIMINATORS[8..12] \
                 == crate::ast::QuoteForm::HASH_DISCRIMINATORS`; any \
                 future container-array sub-slice byte-for-byte equal \
                 to a peer sub-carving's canonical `[u8; M]` listing) \
                 relies on this invariant. Fix at the ARRAY-\
                 DECLARATION site (the drifted `full[START + i]` \
                 entry inside the slice segment) OR at the peer sub-\
                 array's arm listing — the choice depends on whether \
                 the drift is an unintended slot reorder in the outer \
                 array's tail OR in the sub-carving's own listing."
            );
        }
        i += 1;
    }
}

// Compile-time SLICE-EQUALS-ARRAY witness — the ONE `(container,
// sub-carving)` pair on the substrate whose ARRAY-LEVEL structure
// composes a container-array sub-slice byte-for-byte identical to a
// peer sub-carving's canonical `[u8; M]` listing. `SexpShape::HASH_
// DISCRIMINATORS[8..12]` (the four-slot quote-family tail of the
// outer twelve-shape array, `[3, 4, 5, 6]`) is byte-for-byte equal
// to `QuoteForm::HASH_DISCRIMINATORS` (the four-slot quote-family
// carving's canonical listing, `[3, 4, 5, 6]`). Both arrays share
// their four byte values via the four per-role `QuoteForm::{QUOTE,
// QUASIQUOTE, UNQUOTE, UNQUOTE_SPLICE}_HASH_DISCRIMINATOR`
// `pub(crate) const` aliases (the outer SexpShape array's tail-arm
// initializers each spell `Self::<ROLE>_HASH_DISCRIMINATOR` where
// each `SexpShape::<ROLE>_HASH_DISCRIMINATOR` is declared as an
// alias for `QuoteForm::<ROLE>_HASH_DISCRIMINATOR`), so the array-
// level positionwise-equality theorem `SexpShape::HASH_DISCRIMINATORS
// [8..12] == QuoteForm::HASH_DISCRIMINATORS` is the ARRAY-LEVEL
// surface of the four per-role aliases' shared upstream. Pre-lift
// this per-position tail equality was pinned ONLY at runtime through
// the per-position sweep inside `sexp_shape_hash_discriminators_
// align_with_sub_carvings_by_projection` (in `error.rs`, routing
// each `SexpShape::HASH_DISCRIMINATORS[i]` through the shape's sub-
// carving projection `as_quote_form().unwrap().hash_discriminator()`
// on the four quote-family arms); post-lift the ARRAY-LEVEL slice-
// equals-array contract binds at rustc-time via ONE `const _` line,
// one invocation stage earlier than the runtime pin. A regression
// that reorders the outer `SexpShape::HASH_DISCRIMINATORS` array's
// quote-family tail (e.g. swaps positions 10 and 11 so `UNQUOTE_
// SPLICE_HASH_DISCRIMINATOR = 6` slides ahead of `UNQUOTE_HASH_
// DISCRIMINATOR = 5`) while leaving `QuoteForm::HASH_DISCRIMINATORS`
// in its canonical order fails at `cargo check` BEFORE any test
// scheduler runs. The pre-existing `assert_u8_array_permutes_
// inclusive_range::<4, 3, 6>(&QuoteForm::HASH_DISCRIMINATORS)`
// witness above is STRICTLY WEAKER — it binds the sub-carving
// array's image SET is `{3, 4, 5, 6}` but is SILENT on the outer
// container array's tail per-position ORDER against the sub-
// carving's listing.
//
// The atomic-collapse sub-slice `SexpShape::HASH_DISCRIMINATORS
// [1..7)` stays on the sibling `assert_u8_array_slice_is_scalar_
// replica::<12, 1, 7>` witness above because its shape is MANY-TO-
// ONE-COLLAPSE onto a single scalar `AtomKind::OUTER_HASH_
// DISCRIMINATOR`, not POSITIONWISE-COMPOSITION with a peer array —
// there is no natural `[u8; 6]` sub-carving array to compose it
// against (the six atomic outer shapes collapse to a SCALAR image,
// not an array image). The two singleton slices `[0..1)` and
// `[7..8)` on the outer container are pinned via the two sibling
// `assert_u8_array_slice_equals_u8_array::<12, 1, _>` witnesses
// IMMEDIATELY BELOW — see the prose comment there for the per-
// slot binding on `StructuralKind::NIL_HASH_DISCRIMINATOR` and
// `StructuralKind::LIST_HASH_DISCRIMINATOR`. Together the four
// SexpShape `HASH_DISCRIMINATORS` sub-slice witnesses (the
// singleton `[0..1)`, the atomic-collapse `[1..7)`, the singleton
// `[7..8)`, the quote-family tail `[8..12)`) EXHAUSTIVELY pin the
// twelve-slot outer container's per-position byte SHAPE at rustc-
// time, closing the corner the runtime sweep
// `sexp_shape_hash_discriminators_align_with_sub_carvings_by_projection`
// (in `error.rs`) previously covered alone.
const _: () = assert_u8_array_slice_equals_u8_array::<12, 4, 8>(
    &crate::error::SexpShape::HASH_DISCRIMINATORS,
    &QuoteForm::HASH_DISCRIMINATORS,
);

// Compile-time SLICE-EQUALS-ARRAY singleton witnesses — the two
// remaining unpinned-at-rustc-time slots on
// `crate::error::SexpShape::HASH_DISCRIMINATORS` (`[u8; 12]`). Both
// are covered by the LARGER sub-carving arrays' `[u8; 1]` slice
// projections against the container's singleton slice.
//
// * Position `[0..1)` — `SexpShape::HASH_DISCRIMINATORS[0] ==
//   StructuralKind::HASH_DISCRIMINATORS[0] ==
//   StructuralKind::NIL_HASH_DISCRIMINATOR == 0u8`. The outer
//   container's slot-0 initializer spells `Self::NIL_HASH_
//   DISCRIMINATOR` which is declared as an alias for
//   `StructuralKind::NIL_HASH_DISCRIMINATOR` (see
//   `SexpShape::NIL_HASH_DISCRIMINATOR = StructuralKind::NIL_HASH_
//   DISCRIMINATOR` in `error.rs`). Comparing against the singleton
//   `[StructuralKind::NIL_HASH_DISCRIMINATOR]` sub-array binds the
//   container's SLOT-0 POSITION to the structural-residual
//   carving's NIL role at rustc-time.
// * Position `[7..8)` — the mirror slot at the atomic-collapse
//   right endpoint, spelling `Self::LIST_HASH_DISCRIMINATOR` which
//   aliases `StructuralKind::LIST_HASH_DISCRIMINATOR = 2u8`.
//
// Pre-lift these two per-position bindings were pinned ONLY at
// runtime through the twelve-position sweep inside
// `sexp_shape_hash_discriminators_align_with_sub_carvings_by_projection`
// (routing each `SexpShape::HASH_DISCRIMINATORS[i]` through the
// shape's sub-carving projection `as_structural_kind().unwrap().
// hash_discriminator()` on the two structural-residual arms);
// post-lift the ARRAY-LEVEL slice-equals-array contract binds at
// rustc-time via TWO `const _` lines, one invocation stage earlier
// than the runtime pin. The peer joint witness
// `assert_scalar_plus_two_u8_arrays_permute_inclusive_range::<2, 4,
// 0, 6>(AtomKind::OUTER_HASH_DISCRIMINATOR,
// &StructuralKind::HASH_DISCRIMINATORS,
// &QuoteForm::HASH_DISCRIMINATORS)` above is STRICTLY WEAKER on
// these two slots — it binds the SUB-CARVING array
// `StructuralKind::HASH_DISCRIMINATORS = [0, 2]` per-position order
// but is SILENT on which SLOTS of the outer CONTAINER `SexpShape::
// HASH_DISCRIMINATORS` the sub-carving's two bytes land at (a
// regression that swapped `Self::NIL_HASH_DISCRIMINATOR` and
// `Self::LIST_HASH_DISCRIMINATOR` in the outer array initializer
// so slot 0 becomes `2u8` and slot 7 becomes `0u8` would preserve
// the sub-carving array's `[0, 2]` order the joint witness pins
// AND the outer array's global `{0..=6}` set-image the joint
// witness pins, but would silently corrupt the outer container's
// per-position slot-to-carving-role mapping the two new witnesses
// below reject).
//
// Sibling posture to the four-slot QUOTE-family tail
// `assert_u8_array_slice_equals_u8_array::<12, 4, 8>(&SexpShape::
// HASH_DISCRIMINATORS, &QuoteForm::HASH_DISCRIMINATORS)` witness
// IMMEDIATELY ABOVE — that witness carries the sub-carving
// projection at the LARGEST arity (4 positions in a single
// `const _` line); these two witnesses carry the sub-carving
// projection at the SMALLEST arity (1 position each, at the two
// disjoint singleton slots the structural-residual carving
// occupies on the outer container). Together the three SLICE-
// EQUALS-ARRAY witnesses cover the ENTIRE SexpShape ⊃
// {StructuralKind, QuoteForm} sub-carving composition at rustc-
// time — `SexpShape::HASH_DISCRIMINATORS[0..1] ∪ [7..8) ∪ [8..12)`
// exhausts the eight non-atomic slots on the outer container, so
// combined with the sibling `SLICE-BLOCK-CONSTANCY` witness on
// `[1..7)` the twelve-slot outer array is FULLY pinned per-
// position at rustc-time.
//
// The two witnesses use INLINE `[u8; 1]` singleton arrays rather
// than `&StructuralKind::HASH_DISCRIMINATORS[0..1]` slice syntax
// because the helper's signature takes `&[u8; M]` (a const-generic
// array reference, arity-known at rustc time) rather than `&[u8]`
// (a slice type with runtime-length). The inline arrays project
// the two per-role `pub(crate) const` 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 SLICE-EQUALS-ARRAY-VIOLATION panic.
const _: () = assert_u8_array_slice_equals_u8_array::<12, 1, 0>(
    &crate::error::SexpShape::HASH_DISCRIMINATORS,
    &[crate::error::StructuralKind::NIL_HASH_DISCRIMINATOR],
);
const _: () = assert_u8_array_slice_equals_u8_array::<12, 1, 7>(
    &crate::error::SexpShape::HASH_DISCRIMINATORS,
    &[crate::error::StructuralKind::LIST_HASH_DISCRIMINATOR],
);

// `Sexp` is `PartialEq` but not `Eq` (Float contains NaN). We implement Hash
// manually so cache keys can hash a borrowed `&[Sexp]` directly — avoids the
// serde_json serialization that would otherwise dominate cache overhead on
// cheap macro calls.
//
// The outer per-variant discriminator byte (`0` for Nil, `1` for Atom, `2`
// for List, `3..=6` for the four quote-family variants) binds at ONE site
// on the outer-`Sexp` algebra (`Sexp::hash_discriminator`) rather than at
// four per-arm byte projections here. The seven outer-variant arms
// partition `{0..=6}` injectively; the outer-`Sexp` method routes through
// the intermediate shape-level projection `SexpShape::hash_discriminator`
// (the 12 outer shapes → 7 outer bytes; the six atomic-shape arms
// collapse to the outer Atom marker byte `1`, symmetric with `Sexp::Atom(_)
// → 1u8` on the outer method), which in turn composes through the three
// sub-carvings' typed discriminator methods:
//   * `StructuralKind::hash_discriminator` for the two-arm structural-
//     residual partition `{0, 2}` (Nil, List);
//   * `AtomKind::hash_discriminator` for the nested atomic payload
//     `{0..=5}` inside the Atom outer byte `1` (surfaced INSIDE
//     `Hash for Atom`, NOT through this outer method OR the shape-level
//     method);
//   * `QuoteForm::hash_discriminator` for the quote-family arms `{3..=6}`.
// The outer-`Sexp` cache-key algebra now closes at FIVE typed layers
// (outer `Sexp` → `SexpShape` → three sub-carvings). A future eighth
// `Sexp` variant (e.g. `Vector` / `Map` / `Char`) picks a fresh cache-key
// byte outside `{0..=6}` and lands at ONE new arm on
// `Sexp::hash_discriminator` (or, one algebra level up, at ONE new arm on
// `SexpShape::hash_discriminator` — extending either `StructuralKind` if
// it is structural-residual or a fresh sub-algebra), with rustc binding
// the consistency through exhaustiveness over each closed enum.
//
// The per-arm body below only handles the inner-payload hash sequence
// after the outer discriminator byte is routed through
// `self.hash_discriminator().hash(h)` — the recursive `inner.hash(h)` on
// the quote-family arm is asserted-total via `expect_quote_form` (the
// outer pattern guarantees the projection lands `Some`).
impl Hash for Sexp {
    fn hash<H: Hasher>(&self, h: &mut H) {
        self.hash_discriminator().hash(h);
        match self {
            Self::Nil => {}
            Self::Atom(a) => a.hash(h),
            Self::List(items) => {
                items.len().hash(h);
                for i in items {
                    i.hash(h);
                }
            }
            Self::Quote(_) | Self::Quasiquote(_) | Self::Unquote(_) | Self::UnquoteSplice(_) => {
                let (_, inner) = self.expect_quote_form();
                inner.hash(h);
            }
        }
    }
}

// The six atomic variants share the (discriminator, inner) hash shape —
// the per-variant discriminator byte binds at ONE site on the outer-`Atom`
// algebra (`Atom::hash_discriminator`) rather than at six inline
// `<N>u8.hash(h)` arms here. The outer-value method composes through the
// pre-existing marker-level projection `AtomKind::hash_discriminator` (via
// `self.kind().hash_discriminator()`) so the (Atom variant, byte) pairing
// lives at ONE canonical site on the closed-set `AtomKind` algebra rather
// than at TWO (both a parallel six-arm match here AND `AtomKind::hash_
// discriminator`'s canonical site). The inner-payload arm stays a match
// because the payload type differs per variant (`String` for symbol /
// keyword / str, `i64` for int, `f64::to_bits()` for float, `bool` for
// bool); the or-pattern collapses the three string-carrying arms. Float:
// hash the bit pattern. NaN != NaN so PartialEq is broken, but cache
// lookups use PartialEq-by-hash which this satisfies modulo a NaN
// collision risk we accept for template args. The (Atom variant, byte)
// pairing is pinned bit-for-bit by `atom_kind_hash_discriminator_pins_
// legacy_atom_cache_key_bytes` against the pre-lift 0/1/2/3/4/5 sequence
// — same posture as `quote_form_hash_discriminator_pins_legacy_cache_
// key_bytes` for the four-of-thirteen `Sexp` wrapper variants. Post-lift
// the outer-`Atom` `Hash` body is structurally parallel to `Hash for
// Sexp` one algebra layer up — both spell `self.hash_discriminator().hash
// (h); <inner-payload-hash>` at the outer-value carrier, with the byte
// binding routed through the outer-value-level projection at each
// algebra. Routing identity pinned by
// `hash_for_atom_routes_atom_discriminator_through_atom_hash_discriminator`
// on the outer-`Atom` algebra, sibling of
// `hash_for_sexp_routes_outer_discriminator_through_sexp_hash_discriminator`
// on the outer-`Sexp` algebra.
impl Hash for Atom {
    fn hash<H: Hasher>(&self, h: &mut H) {
        self.hash_discriminator().hash(h);
        match self {
            Self::Symbol(s) | Self::Keyword(s) | Self::Str(s) => s.hash(h),
            Self::Int(n) => n.hash(h),
            Self::Float(f) => f.to_bits().hash(h),
            Self::Bool(b) => b.hash(h),
        }
    }
}

/// An S-expression — the homoiconic value + program representation.
/// Lowercase hex for a codepoint, without pulling in a formatter — the escaper
/// is on the Display path and must not recurse into it.
fn alloc_hex(mut n: u32) -> String {
    if n == 0 {
        return "0".to_string();
    }
    const DIGITS: &[u8; 16] = b"0123456789abcdef";
    let mut buf = Vec::with_capacity(6);
    while n > 0 {
        buf.push(DIGITS[(n % 16) as usize]);
        n /= 16;
    }
    buf.reverse();
    String::from_utf8(buf).expect("hex digits are ascii")
}

#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize)]
pub enum Sexp {
    Nil,
    Atom(Atom),
    List(Vec<Sexp>),
    /// `'x` — literal; does not participate in macro substitution.
    Quote(Box<Sexp>),
    /// `` `x `` — quasi-quotation; substitution happens inside.
    Quasiquote(Box<Sexp>),
    /// `,x` — substitute the binding named `x`. Only valid inside a quasi-quote.
    Unquote(Box<Sexp>),
    /// `,@x` — splice the list `x` into the containing list.
    UnquoteSplice(Box<Sexp>),
}

#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize)]
pub enum Atom {
    /// Plain symbol (`foo`, `defpoint`, `seph.1`).
    Symbol(String),
    /// Keyword (`:parent`, `:attr`) — a symbol bound to itself.
    Keyword(String),
    /// String literal.
    Str(String),
    /// Integer literal.
    Int(i64),
    /// Floating literal.
    Float(f64),
    /// Boolean literal (`#t`, `#f`).
    Bool(bool),
}

impl Atom {
    /// The canonical `:` marker prefix that a [`Self::Keyword`] payload
    /// projects THROUGH when rendered as / classified from its
    /// canonical-string surface across the substrate's four
    /// Keyword-round-trip sites — the reader-entry classifier
    /// ([`Self::from_lexeme`]), the Lisp-canonical-form projection
    /// ([`fmt::Display for Atom`]), the JSON-canonical-form projection
    /// ([`Self::to_json`]), and the iac-forge-canonical-form projection
    /// (`Atom::to_iac_forge_sexpr` (removed)).
    ///
    /// Pre-lift the same `":"` byte lived inline at four sites: `':'`
    /// (as a `char` pattern) at the [`Self::from_lexeme`] strip site
    /// and `":{s}"` (three byte-identical format-string literals) at the
    /// three canonical-form projection sites. Post-lift the marker
    /// byte lives at ONE canonical constant on the [`Atom`] algebra
    /// that all four sites bind to; a future refactor that swaps the
    /// marker (e.g. a Racket-compat port to `#:name`, a Clojure-compat
    /// port to `::name`) touches ONE line rather than four inline
    /// bytes that would silently drift out of round-trip agreement if
    /// one was updated without the others.
    ///
    /// Load-bearing round-trip contract:
    /// `Self::from_lexeme(&Self::keyword(name).to_string()) ==
    /// Self::keyword(name)` — the reader-entry classifier's
    /// `strip_prefix(Self::KEYWORD_MARKER)` gate and the Lisp-canonical
    /// [`Display`]'s `write!(f, "{}{name}", Self::KEYWORD_MARKER)`
    /// emission both bind to THIS constant so the pair cannot drift.
    /// Cross-surface round-trip: `Self::to_json` and
    /// `Atom::to_iac_forge_sexpr` (removed) emit the same prefix so any BLAKE3
    /// attestation over an iac-forge canonical form of a Keyword atom
    /// matches the JSON canonical form byte-for-byte on the prefix
    /// axis.
    ///
    /// Sibling-shape lift to the workspace's other prefix-marker
    /// constants: [`crate::error::UnquoteForm::ALL`] projects each
    /// template-marker variant to its punctuation prefix via
    /// [`crate::ast::QuoteForm::prefix`] (`"'"`, `"`"`, `","`, `",@"`)
    /// — a peer axis on the substrate's marker-byte algebra. This
    /// constant sits on the [`Atom`] algebra at the atomic-payload
    /// axis where the [`QuoteForm::prefix`] projection sits at the
    /// homoiconic-wrapper axis.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 2 — free middle; the
    /// (Keyword payload, canonical `:` prefix) pairing now binds at
    /// ONE constant on the closed-set [`Atom`] algebra regardless of
    /// which of the four reader-entry / rendering surfaces reaches in.
    /// THEORY.md §VI.1 — generation over composition; the four
    /// byte-identical `":"` / `":{s}"` inline literals collapse onto
    /// ONE named constant, matching the substrate's three-times rule
    /// (four occurrences, well past the ≥2 lift threshold).
    /// THEORY.md §V.1 — knowable platform; the canonical
    /// keyword-marker byte becomes a TYPE-level constant on the
    /// substrate algebra rather than four inline bytes at four
    /// consumer surfaces.
    pub const KEYWORD_MARKER: &'static str = ":";

    /// Canonical `:` LEAD `char` of the [`Self::KEYWORD_MARKER`] prefix
    /// (`":"`) — the ONE canonical `char` on the [`Atom`] algebra the
    /// substrate's Keyword-prefix lead-byte disjointness contract binds
    /// to.
    ///
    /// Sibling posture to the closed set of `pub const` reader-punctuation
    /// canonical `char` bytes on the substrate: [`Self::STR_DELIMITER`]
    /// (`'"'`), [`Self::STR_ESCAPE_LEAD`] (`'\\'`),
    /// [`Self::BOOL_LITERAL_LEAD`] (`'#'`), [`Sexp::LIST_OPEN`] (`'('`),
    /// [`Sexp::LIST_CLOSE`] (`')'`), [`Sexp::COMMENT_LEAD`] (`';'`),
    /// [`Sexp::COMMENT_TERM`] (`'\n'`), [`QuoteForm::SPLICE_DISCRIMINATOR`]
    /// (`'@'`) — every canonical per-role byte the reader's tokenizer
    /// specialises on is a `pub const` on its owning closed-set algebra.
    /// This constant closes the Keyword-prefix lead byte at the SAME
    /// algebra as its one-char [`Self::KEYWORD_MARKER`] `&'static str`
    /// projection — the ONE `char` that the `&'static str` projects to
    /// when the substrate's consumer needs a `char` (not a `&str`) for
    /// cross-axis marker-byte comparisons or for the reader's
    /// specific-arm outer-dispatch.
    ///
    /// Structural round-trip contract:
    /// `Self::KEYWORD_MARKER.starts_with(Self::KEYWORD_MARKER_LEAD)` —
    /// pinned by
    /// `atom_keyword_marker_lead_prefixes_keyword_marker`. A regression
    /// that drifts EITHER the constant OR the [`Self::KEYWORD_MARKER`]
    /// spelling surfaces at the pin rather than at a silent Keyword-
    /// prefix reader drift where `:foo` classifies as [`Self::Symbol`]
    /// instead of [`Self::Keyword`]. Sibling-shape peer of
    /// [`Self::BOOL_LITERAL_LEAD`]'s
    /// `Self::bool_literal(b).starts_with(Self::BOOL_LITERAL_LEAD)`
    /// round-trip law: where that pin binds the Bool-family two spellings
    /// to their shared lead byte, this pin binds the Keyword-marker
    /// one-char prefix to its projected lead byte.
    ///
    /// Disjointness contract: `KEYWORD_MARKER_LEAD`'s byte MUST differ
    /// from [`Self::STR_DELIMITER`] (`'"'`), [`Self::STR_ESCAPE_LEAD`]
    /// (`'\\'`), [`Self::BOOL_LITERAL_LEAD`] (`'#'`),
    /// [`Sexp::LIST_OPEN`] (`'('`), [`Sexp::LIST_CLOSE`] (`')'`),
    /// [`Sexp::COMMENT_LEAD`] (`';'`), [`Sexp::COMMENT_TERM`]
    /// (`'\n'`), every [`QuoteForm::lead_char`] projection AND
    /// [`QuoteForm::SPLICE_DISCRIMINATOR`] (`'@'`) — every other
    /// closed-set outer-marker byte the reader's tokenizer specialises
    /// on. A collision would silently break the reader's outer
    /// dispatch: a `:`-prefixed bare atom `:foo` would collide with
    /// whichever marker it aliased. Pinned by
    /// `atom_keyword_marker_lead_distinct_from_every_other_algebra_marker`.
    ///
    /// Consumer sites this constant closes: SEVEN test-surface sites
    /// that pre-lift each extracted the lead byte via
    /// `Atom::KEYWORD_MARKER.chars().next().expect(_)` (or `.unwrap()`) —
    /// the Keyword arm of the [`Sexp::is_bare_atom_boundary`] negative
    /// sweep AND the six cross-axis disjointness pins on the sibling
    /// marker-byte algebras
    /// ([`QuoteForm::SPLICE_DISCRIMINATOR`], [`Self::BOOL_LITERAL_LEAD`],
    /// [`Self::STR_DELIMITER`], [`Self::STR_ESCAPE_LEAD`],
    /// [`Sexp::LIST_OPEN`] / [`Sexp::LIST_CLOSE`],
    /// [`Sexp::COMMENT_LEAD`], [`Sexp::COMMENT_TERM`]) — collapse onto
    /// ONE named byte on the substrate algebra.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 2 — free middle; the
    /// (Keyword-prefix lead byte, canonical `':'`) pairing binds at ONE
    /// constant on the closed-set outer [`Atom`] algebra regardless of
    /// which reader-surface consumer reaches in. THEORY.md §II.1
    /// invariant 5 — composition preserves proofs; the
    /// `Self::KEYWORD_MARKER.starts_with(Self::KEYWORD_MARKER_LEAD)`
    /// round-trip law is a coherence proof BETWEEN the paired projection
    /// ([`Self::KEYWORD_MARKER`]) AND its projected lead byte (this
    /// constant) on ONE algebra — a regression that drifts either side
    /// surfaces at the pin rather than as a silent Keyword-prefix reader
    /// drift. THEORY.md §V.1 — knowable platform; the canonical
    /// Keyword-prefix lead byte becomes a TYPE-level constant on the
    /// substrate algebra rather than an inline
    /// `.chars().next().expect(_)` extraction at every test surface AND
    /// an inline `':'` mention across every docstring pinning the
    /// disjointness contract.
    ///
    /// Frontier inspiration: Racket's `read-syntax` colon-prefix reader
    /// hook (`#:name` for keyword args, `::name` for module-scoped bindings
    /// in some dialects) — where the `:` prefix dispatches keyword-family
    /// reader-macros keyed on ONE typed lead byte on the port's reader
    /// table. Translated to tatara-lisp: `Atom::KEYWORD_MARKER_LEAD`
    /// becomes the ONE typed lead byte on the closed-set outer [`Atom`]
    /// algebra that a future keyword-family peer method (e.g. a
    /// Clojure-compat port to `::foo` namespaced keywords) can extend
    /// through — the paired-prefix discipline that Racket's read-syntax
    /// table carries lands here as a `pub const` on the algebra rather
    /// than as an inline char literal at every consumer site.
    pub const KEYWORD_MARKER_LEAD: char = ':';

    /// Project a bare keyword `name` to its canonical qualified rendering
    /// — `format!("{}{name}", Self::KEYWORD_MARKER)`, i.e. the ONE
    /// canonical [`String`] on the [`Atom`] algebra that composes
    /// [`Self::KEYWORD_MARKER`] with a bare keyword name to produce the
    /// substrate-canonical `":name"` spelling.
    ///
    /// Sibling projection to [`Self::bool_literal`] on the atomic-payload
    /// canonical-rendering axis: where `bool_literal(b)` projects the
    /// closed-set `bool` domain to its canonical Scheme spelling
    /// `"#t"` / `"#f"` (`&'static str` because the set is finite), THIS
    /// method projects the open-set bare-name domain to its canonical
    /// qualified spelling `":name"` ([`String`] because the set is
    /// unbounded). The [`Atom`] algebra's atomic-payload canonical-
    /// rendering axis now carries a typed projection for BOTH the
    /// prefix-marked variable-payload variant (Keyword) and the self-
    /// marked closed-set-payload variant (Bool).
    ///
    /// Pre-lift the same `format!("{}{s}", Self::KEYWORD_MARKER)`
    /// composition lived inline at THREE Keyword-arm sites on the
    /// atomic-payload rendering axis:
    ///
    /// 1. [`Self::to_json`]'s [`Self::Keyword`] arm —
    ///    `serde_json::Value::String(format!(...))` for the JSON-
    ///    canonical projection.
    /// 2. `Atom::to_iac_forge_sexpr` (removed)'s [`Self::Keyword`] arm —
    ///    `SExpr::Symbol(format!(...))` for the iac-forge canonical-
    ///    attestation projection.
    /// 3. [`fmt::Display for Atom`]'s [`Self::Keyword`] arm —
    ///    `write!(f, "{}{s}", Self::KEYWORD_MARKER)` for the Lisp-
    ///    canonical-form Display projection.
    ///
    /// Post-lift the two allocating sites (1) + (2) bind at ONE typed
    /// projection on the algebra; the [`fmt::Display for Atom`] site
    /// (3) keeps its allocation-free `write!` path but its byte output
    /// is pinned bit-identical to this projection by
    /// `atom_display_keyword_arm_agrees_with_keyword_qualified_bytes`
    /// so the three canonical-rendering surfaces cannot drift out of
    /// agreement. Adding a fourth Keyword-rendering site (e.g. a future
    /// YAML canonical projection, an LSP hover renderer) binds through
    /// THIS projection rather than composing [`Self::KEYWORD_MARKER`]
    /// inline — the (Keyword payload, canonical qualified rendering)
    /// pairing lives at ONE algebra layer.
    ///
    /// Round-trip contract (with [`Self::from_lexeme`]):
    /// `Self::from_lexeme(&Self::keyword_qualified(name)) ==
    /// Self::Keyword(name.to_owned())` for every `name: &str` that
    /// does NOT itself parse as a Bool spelling, integer, or float
    /// (the four typed-entry classification arms preceding the
    /// [`Self::KEYWORD_MARKER`]-prefix arm). The classifier's
    /// `s.strip_prefix(Self::KEYWORD_MARKER)` gate is the LEFT-inverse
    /// of THIS projection on the Keyword-payload subset — pinned by
    /// `atom_from_lexeme_inverts_keyword_qualified_on_bare_name`.
    /// Composition preserves proofs across the (typed-EXIT rendering,
    /// typed-ENTRY classification) round-trip at ONE algebra site.
    ///
    /// Sibling posture to [`QuoteForm::prefix`]'s composition with
    /// homoiconic inner forms in [`fmt::Display for Sexp`]'s quote-
    /// family arm: where `QuoteForm::prefix` is the [`&'static str`]
    /// prefix a quote-family variant composes with an inner rendering
    /// via `write!(f, "{}{inner}", qf.prefix())`, THIS method is the
    /// composed [`String`] a Keyword atom composes with a bare name.
    /// Both projections close a (marker, payload) pair on their owning
    /// closed-set algebra.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 2 — free middle; the
    /// (Keyword payload, canonical qualified rendering) pairing binds
    /// at ONE projection on the closed-set [`Atom`] algebra regardless
    /// of which of the three canonical-rendering surfaces reaches in.
    /// THEORY.md §II.1 invariant 5 — composition preserves proofs; the
    /// round-trip law
    /// `Self::from_lexeme(&Self::keyword_qualified(n)) ==
    /// Self::Keyword(n.into())` is a coherence proof BETWEEN the
    /// paired typed-EXIT rendering (this method) AND the typed-ENTRY
    /// classification ([`Self::from_lexeme`]) on ONE algebra — a
    /// regression that drifts either side surfaces at the pin rather
    /// than as a silent Keyword-round-trip drift. THEORY.md §V.1 —
    /// knowable platform; the (Keyword payload → canonical qualified
    /// rendering) composition becomes a TYPE-level projection on the
    /// substrate algebra rather than an inline
    /// `format!("{}{s}", Self::KEYWORD_MARKER)` at every consumer
    /// site. THEORY.md §VI.1 — generation over composition; three
    /// byte-identical inline compositions collapse onto ONE named
    /// projection (two routed sites + one Display byte-identity pin),
    /// matching the substrate's three-times rule.
    ///
    /// Frontier inspiration: Racket's `syntax/parse` keyword-form
    /// canonical-rendering hook — where `#:name` keyword args have
    /// ONE canonical printer that composes the port's `KEYWORD_PREFIX`
    /// with the bare name rather than N per-consumer `printf`
    /// compositions. Translated to tatara-lisp:
    /// `Atom::keyword_qualified` becomes the ONE canonical-rendering
    /// projection on the closed-set outer [`Atom`] algebra so a
    /// future prefix migration (a Racket-compat port to `#:name`, a
    /// Clojure-compat port to `::name`) touches ONE
    /// [`Self::KEYWORD_MARKER`] constant + zero rendering sites,
    /// rather than the pre-lift three inline `format!` compositions
    /// that would silently drift.
    #[must_use]
    pub fn keyword_qualified(name: &str) -> String {
        let mut out = String::with_capacity(Self::KEYWORD_MARKER.len() + name.len());
        out.push_str(Self::KEYWORD_MARKER);
        out.push_str(name);
        out
    }

    /// Project the closed-set `bool` domain to its canonical Scheme-
    /// spelling `&'static str` — `"#t"` for `true`, `"#f"` for `false`.
    /// ONE projection on the [`Atom`] algebra that the substrate's
    /// FOUR `Self::Bool`-round-trip inline byte-literals across TWO
    /// consumer sites (the two-arm `Bool(true|false)` fork inside
    /// [`fmt::Display for Atom`] and the two-line `if s == "#t"` /
    /// `if s == "#f"` cascade inside [`Self::from_lexeme`]) collapse
    /// onto — parallel to how [`Self::KEYWORD_MARKER`] is the ONE
    /// canonical prefix the four Keyword-round-trip sites bind to.
    ///
    /// Pre-lift the same `"#t"` / `"#f"` bytes lived inline at four
    /// sites: two `f.write_str("#t"|"#f")` arms at the Display impl and
    /// two `if s == "#t"|"#f"` gates at [`Self::from_lexeme`]. Post-
    /// lift the (typed `bool`, canonical Scheme spelling) pairing binds
    /// at ONE projection on the [`Atom`] algebra that every consumer
    /// routes through; a refactor that swaps the spelling (e.g. a
    /// Common-Lisp-compat port to `T` / `NIL`, a JSON-compat port to
    /// `true` / `false`) touches ONE method rather than four inline
    /// bytes that would silently drift out of round-trip agreement if
    /// one was updated without the others. The Display arm also
    /// collapses from TWO variant-branches (`Bool(true) => "#t"`,
    /// `Bool(false) => "#f"`) to ONE variant-branch
    /// (`Bool(b) => Self::bool_literal(*b)`) — the fork on `bool`
    /// happens at the projection, not at every consumer's match body.
    ///
    /// Load-bearing round-trip contract:
    /// `Self::from_lexeme(&Self::boolean(b).to_string()) ==
    /// Self::boolean(b)` for every `b: bool` — the reader-entry
    /// classifier's `s == Self::bool_literal(true|false)` gates and the
    /// Lisp-canonical [`Display`]'s
    /// `f.write_str(Self::bool_literal(*b))` emission both bind to THIS
    /// projection so the pair cannot drift. Guards against the
    /// CLAUDE.md pin ("bare `true`/`false` are symbols → strings, not
    /// bools") — the closed-set `bool` domain projects only through
    /// this typed method, so a reader extension that later accepts
    /// bare `true`/`false` extends the projection (or its reverse) at
    /// ONE algebra site rather than at every callsite in lockstep.
    ///
    /// Sibling-shape peer of [`Self::KEYWORD_MARKER`]: where
    /// `KEYWORD_MARKER` is the ONE `&'static str` prefix a Keyword
    /// payload composes with at four round-trip sites, this method is
    /// the ONE projection a Bool payload composes THROUGH at its two
    /// round-trip sites. The [`Atom`] algebra's atomic-payload axis
    /// now carries a canonical-marker/spelling for BOTH prefix-marked
    /// (Keyword) and self-marked (Bool) variants.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 2 — free middle; the
    /// (Bool payload, canonical Scheme spelling) pairing now binds at
    /// ONE projection on the closed-set [`Atom`] algebra regardless of
    /// which of the two reader-entry / rendering surfaces reaches in.
    /// THEORY.md §VI.1 — generation over composition; the four byte-
    /// identical `"#t"` / `"#f"` inline literals collapse onto ONE
    /// named projection, matching the substrate's three-times rule.
    /// THEORY.md §V.1 — knowable platform; the canonical Scheme-bool
    /// spellings become a TYPE-level projection on the substrate
    /// algebra rather than four inline bytes at two consumer surfaces.
    #[must_use]
    pub fn bool_literal(b: bool) -> &'static str {
        if b {
            Self::TRUE_LITERAL
        } else {
            Self::FALSE_LITERAL
        }
    }

    /// Canonical `&'static str` Scheme-bool spelling for the `true`
    /// element of the closed `bool` domain — the `"#t"` bytes
    /// [`Self::bool_literal`] projects `true` to, AND the
    /// [`Self::from_lexeme`] reader classifier gates on. Sibling
    /// posture to [`Self::FALSE_LITERAL`] (`"#f"`) on the same
    /// bool-spelling algebra layer.
    ///
    /// Pre-lift the same `"#t"` bytes lived inline at [`Self::bool_literal`]'s
    /// `true`-arm plus at five test-surface sites that pin the
    /// canonical spelling — the ≥2 PRIME-DIRECTIVE trigger. Post-lift
    /// the (`true`, canonical Scheme spelling) pairing binds at ONE
    /// `pub const` on the closed-set [`Atom`] algebra: the
    /// [`Self::bool_literal`] `true`-arm AND every consumer that pins
    /// the exact bytes route through this constant, so a spelling
    /// migration (e.g. a Common-Lisp-compat port to `"T"`, a JSON-compat
    /// port to `"true"`, a Racket-compat port to `"#true"`) is ONE
    /// edit HERE with the [`Self::bool_literal`] projection AND every
    /// downstream reader/Display consumer 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: [`Self::STR_DELIMITER`] (`'"'`),
    /// [`Self::KEYWORD_MARKER`] (`":"`),
    /// [`Sexp::LIST_OPEN`] (`'('`),
    /// [`crate::error::MacroDefHead::DEFMACRO_KEYWORD`] (`"defmacro"`),
    /// [`crate::macro_expand::MacroParams::REST_MARKER`] (`"&rest"`),
    /// [`crate::macro_expand::MacroParams::OPTIONAL_MARKER`] (`"&optional"`).
    ///
    /// Structural round-trip contract (composed with the algebra's
    /// [`Self::BOOL_LITERAL_LEAD`] axis peer):
    /// `Self::TRUE_LITERAL.starts_with(Self::BOOL_LITERAL_LEAD)` — the
    /// lead-byte-prefixes-spelling law from
    /// `atom_bool_literal_lead_prefixes_every_bool_literal_spelling`
    /// specialises byte-for-byte to this constant, pinning the
    /// (`BOOL_LITERAL_LEAD`, `TRUE_LITERAL`) pairing on ONE typed
    /// algebra.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 2 — free middle; the
    /// (`true`, canonical Scheme spelling) pairing binds at ONE
    /// `pub const` on the closed-set outer [`Atom`] algebra regardless
    /// of which of the reader/Display surface consumers reaches in.
    /// THEORY.md §VI.1 — generation over composition; the multi-site
    /// inline `"#t"` literal collapses onto ONE named `pub const`,
    /// matching the substrate's three-times rule. THEORY.md §V.1 —
    /// knowable platform; the canonical `true`-spelling becomes a
    /// TYPE-level constant on the substrate algebra rather than an
    /// inline byte literal at every consumer surface.
    pub const TRUE_LITERAL: &'static str = "#t";

    /// Canonical `&'static str` Scheme-bool spelling for the `false`
    /// element of the closed `bool` domain — the `"#f"` bytes
    /// [`Self::bool_literal`] projects `false` to, AND the
    /// [`Self::from_lexeme`] reader classifier gates on. Sibling
    /// posture to [`Self::TRUE_LITERAL`] (`"#t"`) on the same
    /// bool-spelling algebra layer.
    ///
    /// Pre-lift the same `"#f"` bytes lived inline at [`Self::bool_literal`]'s
    /// `false`-arm plus at five test-surface sites that pin the
    /// canonical spelling — the ≥2 PRIME-DIRECTIVE trigger. Post-lift
    /// the (`false`, canonical Scheme spelling) pairing binds at ONE
    /// `pub const` on the closed-set [`Atom`] algebra: the
    /// [`Self::bool_literal`] `false`-arm AND every consumer that pins
    /// the exact bytes route through this constant.
    ///
    /// Structural round-trip contract (composed with the algebra's
    /// [`Self::BOOL_LITERAL_LEAD`] axis peer):
    /// `Self::FALSE_LITERAL.starts_with(Self::BOOL_LITERAL_LEAD)`.
    pub const FALSE_LITERAL: &'static str = "#f";

    /// The closed set of two canonical `&'static str` Scheme-bool
    /// spellings — the [`Self::TRUE_LITERAL`] (`"#t"`) canonical `true`
    /// spelling followed by the [`Self::FALSE_LITERAL`] (`"#f"`)
    /// canonical `false` spelling. Canonical declaration order matches
    /// the `[true, false]` sweep order every existing sibling test in
    /// the crate uses (see e.g. the `for b in [true, false]` sweeps at
    /// `atom_bool_literal_lead_prefixes_every_bool_literal_spelling`)
    /// so `Self::BOOL_LITERALS[i] == Self::bool_literal([true, false][i])`
    /// element-wise — pinned by
    /// `atom_bool_literals_align_with_bool_literal_by_index`.
    ///
    /// Sibling posture to
    /// [`crate::error::MacroDefHead::KEYWORDS`] (`[&'static str; 3]`),
    /// [`crate::macro_expand::MacroParams::LAMBDA_LIST_KEYWORDS`]
    /// (`[&'static str; 2]`) — every closed-set spelling algebra now
    /// pins its projection ALL array at the declaration site via a
    /// forced-arity `[&'static str; N]` array whose length fails
    /// compilation if a new spelling lands without being added to the
    /// set. The closed `bool` domain admits exactly two spellings by
    /// construction (a hypothetical third would require extending the
    /// underlying `bool` type itself), so this array's `N == 2` is
    /// pinned by the mathematics — the forced-arity `[_; 2]` here
    /// records that invariant on the substrate algebra so a future
    /// tri-valued-logic extension surfaces at the array-arity check
    /// rather than as a silent drift.
    ///
    /// Future consumers that compose against [`Self::BOOL_LITERALS`]:
    /// an LSP / REPL completion provider surfacing every `#…` partial
    /// input against the closed set (`Self::BOOL_LITERALS.iter()` is
    /// the ONE typed sweep over every legal bool spelling), a
    /// `tatara-check` coverage assertion (every workspace `.lisp` file's
    /// bare-`#`-prefixed lexeme must classify to some entry of
    /// `Self::BOOL_LITERALS` OR be routed through the broader
    /// hash-prefix reader-macro family), any future audit-trail metric
    /// jointly labeled by the canonical Scheme spelling (e.g.
    /// `tatara_lisp_bool_lexeme_total{literal="#t"}`) — the metric
    /// label set IS [`Self::BOOL_LITERALS`].
    pub const BOOL_LITERALS: [&'static str; 2] = [Self::TRUE_LITERAL, Self::FALSE_LITERAL];

    /// Canonical `#` LEAD byte shared across both [`Self::bool_literal`]
    /// spellings (`"#t"` for [`true`], `"#f"` for [`false`]) — the ONE
    /// canonical `char` on the [`Atom`] algebra the substrate's Bool-
    /// prefix disjointness contract binds to.
    ///
    /// Sibling posture to the closed set of `pub const` reader-punctuation
    /// canonical bytes on the substrate: [`Self::STR_DELIMITER`] (`'"'`),
    /// [`Self::STR_ESCAPE_LEAD`] (`'\\'`), [`Sexp::LIST_OPEN`] (`'('`),
    /// [`Sexp::LIST_CLOSE`] (`')'`), [`Sexp::COMMENT_LEAD`] (`';'`),
    /// [`Sexp::COMMENT_TERM`] (`'\n'`), [`QuoteForm::SPLICE_DISCRIMINATOR`]
    /// (`'@'`) — every canonical per-role byte the reader's tokenizer
    /// specialises on is now a `pub const` on its owning closed-set
    /// algebra. This constant closes the Bool-family lead byte at the
    /// SAME algebra as its two-char [`Self::bool_literal`] projections
    /// so a delimiter swap (e.g. a Common-Lisp-compat port from
    /// Scheme `#t`/`#f` to CL `T`/`NIL`, a JSON-compat port to
    /// `true`/`false`, or an extension for the broader Scheme
    /// hash-prefix reader-macro family `#\char` / `#(vector)` /
    /// `#|block-comment|#` / `#;datum-comment`) lands at ONE constant
    /// on the algebra rather than at inline `'#'` char literals
    /// scattered across the test surface AND the docstrings pinning
    /// the disjointness contract.
    ///
    /// Structural round-trip contract:
    /// `Self::bool_literal(b).starts_with(Self::BOOL_LITERAL_LEAD)`
    /// for every `b: bool` — pinned by
    /// `atom_bool_literal_lead_prefixes_every_bool_literal_spelling`.
    /// A regression that drifts EITHER the constant OR the two
    /// [`Self::bool_literal`] arms surfaces at the pin rather than at
    /// a silent bool-family reader drift where `#t` / `#f` classify as
    /// [`Self::Symbol`] instead of [`Self::Bool`].
    ///
    /// Disjointness contract: `BOOL_LITERAL_LEAD`'s byte MUST differ
    /// from [`Self::STR_DELIMITER`] (`'"'`), [`Self::STR_ESCAPE_LEAD`]
    /// (`'\\'`), [`Self::KEYWORD_MARKER`]'s lead byte (`':'`),
    /// [`Sexp::LIST_OPEN`] (`'('`), [`Sexp::LIST_CLOSE`] (`')'`),
    /// [`Sexp::COMMENT_LEAD`] (`';'`), [`Sexp::COMMENT_TERM`]
    /// (`'\n'`), every [`QuoteForm::lead_char`] projection AND
    /// [`QuoteForm::SPLICE_DISCRIMINATOR`] (`'@'`) — every other
    /// closed-set outer-marker byte the reader's tokenizer specialises
    /// on. A collision would silently break the reader's outer
    /// dispatch: a `#`-prefixed bare atom `#t` would collide with
    /// whichever marker it aliased. Pinned by
    /// `atom_bool_literal_lead_distinct_from_every_other_algebra_marker`.
    ///
    /// Consumer sites this constant closes: the three test-surface
    /// sites that pre-lift each extracted the lead byte via
    /// `Self::bool_literal(b).chars().next().unwrap()` (or `.expect(_)`)
    /// — the `Bool`-arm of [`Sexp::is_bare_atom_boundary`]'s negative
    /// sweep AND the two [`QuoteForm::SPLICE_DISCRIMINATOR`]
    /// disjointness assertions — collapse onto ONE named byte on the
    /// substrate algebra. The two SPLICE_DISCRIMINATOR assertions
    /// (one per `bool_literal` spelling) further collapse to ONE
    /// assertion since the lead byte is by construction the SAME
    /// across both spellings.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 2 — free middle; the
    /// (Bool-family lead byte, canonical `'#'`) pairing binds at ONE
    /// constant on the closed-set outer [`Atom`] algebra regardless of
    /// which reader-surface consumer reaches in. THEORY.md §II.1
    /// invariant 5 — composition preserves proofs; the
    /// [`Self::bool_literal(b).starts_with(Self::BOOL_LITERAL_LEAD)`]
    /// round-trip law is a coherence proof BETWEEN the paired
    /// projection ([`Self::bool_literal`]) AND the shared lead byte
    /// (this constant) on ONE algebra — a regression that drifts
    /// either side surfaces at the pin rather than as a silent
    /// hash-prefix reader-family drift. THEORY.md §V.1 — knowable
    /// platform; the canonical Bool-family lead byte becomes a
    /// TYPE-level constant on the substrate algebra rather than an
    /// inline `.chars().next().unwrap()` extraction at every test
    /// surface AND an inline `'#'` mention across every docstring
    /// pinning the disjointness contract.
    pub const BOOL_LITERAL_LEAD: char = '#';

    /// Canonical `"` delimiter that opens AND closes a [`Self::Str`]
    /// atom in the reader's tokenizer AND self-escapes inside a
    /// backslash-escape sequence — ONE canonical `char` on the
    /// [`Atom`] algebra the substrate's FOUR `"`-round-trip inline
    /// `char` literals at [`crate::reader::tokenize`] bind to.
    ///
    /// Sibling constant of [`Self::KEYWORD_MARKER`] on the atomic-
    /// payload marker/delimiter axis of the closed-set [`Atom`]
    /// algebra: where `KEYWORD_MARKER` is the ONE `&'static str`
    /// prefix a [`Self::Keyword`] payload composes WITH at four
    /// canonical-form round-trip sites (reader-entry classifier,
    /// Lisp-canonical Display, JSON canonical form, iac-forge
    /// canonical form) and [`Self::bool_literal`] is the ONE
    /// projection a [`Self::Bool`] payload composes THROUGH at its
    /// two Bool-round-trip sites, this constant is the ONE canonical
    /// delimiter a [`Self::Str`] payload pairs with at the reader's
    /// four `"`-round-trip sites inside [`crate::reader::tokenize`]:
    ///   1. The outer-match string-opening arm — the `"` byte that
    ///      begins a [`crate::reader::Token::Str`] tokenization run.
    ///   2. The escape-handler mapping — `\"` unescapes to a bare `"`
    ///      character inside the accumulated string payload (the
    ///      only self-escape arm on the reader's five-arm escape
    ///      table: `\n → \n`, `\t → \t`, `\r → \r`, `\" → "`,
    ///      `\\ → \\`).
    ///   3. The string-closing arm — the `"` byte that terminates the
    ///      current [`crate::reader::Token::Str`] tokenization run
    ///      and emits the accumulated payload.
    ///   4. The bare-atom tokenizer's break-disjunct — `"` is one of
    ///      the seven characters that terminates a
    ///      [`crate::reader::Token::Atom`] run so a bare atom
    ///      followed by a string (e.g. `foo"body"`) tokenizes as two
    ///      distinct tokens rather than one Symbol payload.
    ///
    /// Pre-lift the same `"` byte lived inline at four `char`
    /// literals scattered across `crate::reader::tokenize`: two outer-
    /// match arm patterns (opening + escape-handler), one inner-loop
    /// termination pattern (closing), one bare-atom termination
    /// disjunct. Post-lift the (Str payload, canonical `"` delimiter)
    /// pairing binds at ONE `char` constant on the [`Atom`] algebra
    /// that every reader consumer routes through; a refactor that
    /// swaps the delimiter (e.g. a Racket-compat port to `#"…"#`
    /// heredoc mode, a Python-compat port that also accepts `'`,
    /// a triple-quoted heredoc mode) touches ONE constant + one
    /// reader table rather than four inline byte literals that would
    /// silently drift out of round-trip agreement if one was updated
    /// without the others (e.g. an opening `#` without a matching
    /// closing `#` would round-trip a broken string with a
    /// silently-truncated payload).
    ///
    /// Load-bearing round-trip contract:
    /// `read(&format!("{}{s}{}", Atom::STR_DELIMITER,
    /// Atom::STR_DELIMITER))[0] == Sexp::Atom(Atom::string(s))` for
    /// every escape-free `s: &str`. The reader's opening + closing
    /// arms both bind to THIS constant so the delimiter cannot drift
    /// silently between opener and closer; a regression that swaps
    /// ONE arm's pattern to a different byte fails the round-trip
    /// even when the byte-value at the other arm still agrees at
    /// the surface. Guards the CLAUDE.md-implicit convention that
    /// operator-visible strings use ONE canonical delimiter across
    /// the reader entry surface — the delimiter is a first-class
    /// algebra fact rather than a per-callsite reader convention.
    ///
    /// Sibling-shape peer of [`Self::KEYWORD_MARKER`] on the closed-
    /// set [`Atom`] algebra: where `KEYWORD_MARKER` (`":"`) partitions
    /// bare-atom lexemes at reader-entry classifier `strip_prefix`
    /// gate into `Keyword` vs default `Symbol`, this constant (`'"'`)
    /// partitions the reader's outer tokenizer arm into
    /// `Token::Str` vs `Token::Atom` — both are the ONE canonical
    /// marker byte the reader binds to when discriminating an
    /// [`Atom`] variant's typed-entry classification path. A `Str`
    /// payload takes the `Token::Str` reader branch (with THIS
    /// delimiter) NOT the `Token::Atom` reader branch (routed
    /// through [`Self::from_lexeme`]) — the two paths remain
    /// structurally disjoint through the reader's delimiter
    /// dispatch.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 2 — free middle; the
    /// (Str payload, canonical `"` delimiter) pairing now binds at
    /// ONE constant on the closed-set [`Atom`] algebra regardless of
    /// which of the four reader tokenizer sites reaches in.
    /// THEORY.md §VI.1 — generation over composition; four byte-
    /// identical inline `'"'` char literals in `crate::reader::tokenize`
    /// collapse onto ONE named constant. Four occurrences, well past
    /// the ≥2 lift threshold — the substrate's three-times rule at
    /// the Str-delimiter axis. THEORY.md §V.1 — knowable platform;
    /// the canonical string-delimiter byte becomes a TYPE-level
    /// constant on the substrate algebra rather than four inline
    /// bytes at four consumer sites inside one reader file.
    pub const STR_DELIMITER: char = '"';

    /// Canonical `\` escape-lead byte that OPENS a backslash-escape
    /// sequence inside a [`Self::Str`] payload AND self-escapes to the
    /// same byte inside that sequence — ONE canonical `char` on the
    /// [`Atom`] algebra the substrate's TWO `\`-round-trip inline
    /// `char` literals at [`crate::reader::tokenize`] bind to.
    ///
    /// Sibling constant of [`Self::STR_DELIMITER`] on the same
    /// Str-payload delimiter axis of the closed-set [`Atom`] algebra:
    /// where `STR_DELIMITER` is the ONE canonical delimiter that
    /// BOUNDS a Str payload from the outside (opener, closer, self-
    /// escape, bare-atom terminator), this constant is the ONE
    /// canonical escape lead that ESCAPES-IN a following byte from
    /// the INSIDE of the same payload. The two constants together
    /// span the Str-tokenization boundary — every `char` the reader's
    /// `Token::Str` accumulation loop specialises on binds to one of
    /// them.
    ///
    /// The reader's TWO `\`-round-trip sites inside
    /// [`crate::reader::tokenize`]:
    ///   1. The escape-lead outer arm — the `\` byte that triggers the
    ///      inner escape-handler branch that consumes the following
    ///      byte as an escape sequence.
    ///   2. The escape-handler's self-escape arm — inside the reader's
    ///      six-arm escape table (`\n → \n`, `\t → \t`, `\r → \r`,
    ///      `\" → "`, `\\ → \`, passthrough), the self-escape arm on
    ///      the escape-lead axis: pattern AND mapped value both bind
    ///      to THIS constant so `\\` unescapes to a single `\` byte
    ///      in the accumulated payload. Sibling posture to the
    ///      analogous self-escape arm on [`Self::STR_DELIMITER`] axis
    ///      (`\"` unescapes to `"`) — the two self-escape arms are
    ///      the escape table's ONLY pattern-equals-value arms; every
    ///      other arm is pattern-distinct-from-value.
    ///
    /// Pre-lift the same `\` byte lived inline at two `char` literals
    /// scattered across `crate::reader::tokenize`: one outer-arm
    /// pattern (escape-lead detection), one inner-loop escape-handler
    /// arm's pattern + value pair (the self-escape mapping). Post-
    /// lift the (Str-payload escape lead, canonical `\` byte) pairing
    /// binds at ONE `char` constant on the [`Atom`] algebra that every
    /// reader consumer routes through; a refactor that swaps the
    /// escape lead (e.g. a Rust-compat port to `\\` byte-strings, a
    /// hypothetical Racket-compat port that adopts `#\` prefix syntax
    /// as the escape lead, or a heredoc mode that suspends escaping
    /// altogether) touches ONE constant + one reader table rather
    /// than two inline byte literals that would silently drift out of
    /// round-trip agreement if one was updated without the other
    /// (e.g. the outer arm's pattern updated without the inner self-
    /// escape's pattern + value would leak a stale escape lead through
    /// the wrong branch).
    ///
    /// Load-bearing round-trip contract:
    /// `read(&format!("{}{}{}{}", Atom::STR_DELIMITER,
    /// Atom::STR_ESCAPE_LEAD, Atom::STR_ESCAPE_LEAD,
    /// Atom::STR_DELIMITER))[0] ==
    /// Sexp::Atom(Atom::string(Atom::STR_ESCAPE_LEAD.to_string()))`.
    /// The `\\` inside a STR_DELIMITER-wrapped payload unescapes to
    /// ONE `\` byte on the accumulated payload — pinning the (self-
    /// escape pattern, self-escape mapped value) pair against
    /// re-inlining. A regression that swaps ONE side of the self-
    /// escape arm to a different byte fails this round-trip even when
    /// the pattern OR value at the other side still agrees at the
    /// surface, because both sides bind to THIS constant.
    ///
    /// Sibling-shape peer of [`Self::STR_DELIMITER`] on the closed-set
    /// [`Atom`] algebra: where `STR_DELIMITER` partitions the outer-
    /// tokenizer arm into `Token::Str` vs `Token::Atom`, this constant
    /// partitions the inner-tokenizer arm (inside `Token::Str`
    /// accumulation) into the escape-handler branch vs the passthrough
    /// `Some((_, ch))` branch — both are the ONE canonical marker
    /// byte the reader binds to when discriminating the Str-payload
    /// accumulation loop's branch dispatch.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 2 — free middle; the
    /// (Str-payload escape lead, canonical `\` byte) pairing now binds
    /// at ONE constant on the closed-set [`Atom`] algebra regardless
    /// of which of the two reader tokenizer sites reaches in.
    /// THEORY.md §VI.1 — generation over composition; two byte-
    /// identical inline `'\\'` char literals in `crate::reader::tokenize`
    /// collapse onto ONE named constant. Two occurrences at the ≥2
    /// lift threshold — the substrate's three-times rule at the
    /// Str-escape-lead axis. THEORY.md §V.1 — knowable platform; the
    /// canonical string-escape-lead byte becomes a TYPE-level constant
    /// on the substrate algebra rather than two inline bytes at two
    /// consumer sites inside one reader file.
    pub const STR_ESCAPE_LEAD: char = '\\';

    /// Canonical Str-payload escape-table projection — total closed-set
    /// decode from the ONE post-escape-lead source byte the reader's
    /// escape-handler branch consumes to the ONE decoded byte pushed
    /// onto the accumulated Str payload. ONE typed projection on the
    /// closed-set [`Atom`] algebra that the substrate's Str-escape
    /// decode boundary binds to; every consumer that reaches inside a
    /// [`Self::Str`] payload for a backslash-escape sequence routes
    /// through THIS method rather than a per-site inline
    /// `match esc { … }` table.
    ///
    /// Closes the Str-payload tokenization boundary that
    /// [`Self::STR_DELIMITER`] + [`Self::STR_ESCAPE_LEAD`] began: where
    /// those two constants pin the ONE canonical delimiter byte AND
    /// the ONE canonical escape-lead byte the reader's outer + inner
    /// branch dispatch specialises on, this method pins the ONE
    /// canonical decode table the escape-handler's inner branch
    /// consumes AFTER the escape-lead byte fires. The three constants
    /// together span the Str-payload tokenization axis — every byte
    /// the reader's `Token::Str` accumulation loop reads either
    /// terminates the payload (`STR_DELIMITER`), triggers the escape
    /// handler (`STR_ESCAPE_LEAD`), pushes through unchanged
    /// (passthrough), OR is fed into THIS method as the escape source
    /// byte AND its result pushed onto the payload.
    ///
    /// Total function: EVERY `char` maps to exactly one decoded
    /// `char`. The five typed arms bind the substrate's canonical
    /// escape shorthand:
    ///
    /// | esc source                | decoded byte              |
    /// | ------------------------- | ------------------------- |
    /// | `'n'`                     | `'\n'`                    |
    /// | `'t'`                     | `'\t'`                    |
    /// | `'r'`                     | `'\r'`                    |
    /// | `Self::STR_DELIMITER`     | `Self::STR_DELIMITER`     |
    /// | `Self::STR_ESCAPE_LEAD`   | `Self::STR_ESCAPE_LEAD`   |
    /// | any other `char`          | itself (passthrough)      |
    ///
    /// The two self-escape arms (`STR_DELIMITER → STR_DELIMITER`,
    /// `STR_ESCAPE_LEAD → STR_ESCAPE_LEAD`) are the ONLY
    /// pattern-equals-value arms in the table; both bind through the
    /// closed-set [`Atom`] algebra constants so a delimiter-swap or
    /// escape-lead-swap on the algebra propagates through pattern AND
    /// value at ONE site rather than as scattered inline byte literals
    /// that would silently drift out of round-trip agreement if one
    /// was updated without the other.
    ///
    /// The three named-escape arms (`'n'` / `'t'` / `'r'`) are the
    /// substrate's canonical whitespace shorthand — pattern-distinct-
    /// from-value on every arm (each maps a printable ASCII letter to
    /// its corresponding C0 control byte). Pre-lift the whole table
    /// lived inline at ONE site inside [`crate::reader::tokenize`]'s
    /// escape-handler branch; post-lift the table lives at ONE typed
    /// projection on the [`Atom`] algebra that the reader consumes
    /// through a single `Self::decode_str_escape(esc)` call. Adding a
    /// sixth named-escape arm (e.g. `'0' → '\0'` for the NUL byte, or
    /// an `'x'` hex-byte-prefix arm) extends THIS method's match
    /// rather than mutating the reader's inline block.
    ///
    /// Load-bearing round-trip contract: for every `esc: char`,
    /// `read(&format!("{}{}{}{}", Atom::STR_DELIMITER,
    /// Atom::STR_ESCAPE_LEAD, esc, Atom::STR_DELIMITER))[0] ==
    /// Sexp::Atom(Atom::string(Atom::decode_str_escape(esc)
    /// .to_string()))`. Every escape-source byte inside a
    /// STR_DELIMITER-wrapped payload decodes through THIS projection
    /// end-to-end — pinning the (reader escape-handler branch, this
    /// method) pairing against a silent drift at either side. A
    /// regression that re-inlines the reader's table would break the
    /// pin the moment a new arm lands here but NOT there (or vice
    /// versa).
    ///
    /// Sibling-shape peer of [`QuoteForm::from_lead_char`] on the
    /// closed-set [`QuoteForm`] algebra: where `from_lead_char` is
    /// the ONE typed dispatch on the outer-tokenizer quote-family
    /// axis (four homoiconic prefix chars decode to `Option<Self>`),
    /// this method is the ONE typed dispatch on the inner-tokenizer
    /// Str-escape axis (every escape-source char decodes to a
    /// resolved `char`). Both are the substrate's canonical
    /// closed-set projections the reader consumes through ONE call
    /// site each; both close the reader's per-char specialization
    /// point onto the algebra.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 2 — free middle; the
    /// (Str-escape source byte, decoded byte) pairing now binds at
    /// ONE typed projection on the closed-set [`Atom`] algebra
    /// regardless of which consumer reaches in. THEORY.md §VI.1 —
    /// generation over composition; the reader's five-arm inline
    /// table plus one passthrough arm at [`crate::reader::tokenize`]
    /// collapses onto ONE named projection. THEORY.md §V.1 — knowable
    /// platform; the canonical Str-escape decode table becomes a
    /// TYPE-level method on the substrate algebra rather than an
    /// inline block inside one reader file — a future decoder
    /// (e.g. a Racket-compat port, a heredoc mode, a raw-string
    /// mode) plugs a peer projection onto the same algebra rather
    /// than forking the reader.
    ///
    /// Canonical newline-escape SOURCE char — the ONE `'n'` byte
    /// [`Self::decode_str_escape`]'s newline arm pattern-matches on.
    /// Sibling constant of [`Self::NEWLINE_ESCAPE_DECODED`] on the
    /// same (source, decoded) escape-arm axis: the (`'n'`, `'\n'`)
    /// pairing is the first of the substrate's three named-escape
    /// arms; each pairing binds at ONE `pub const` per role rather
    /// than at an inline `char` literal at the match-arm pattern +
    /// value. Sibling posture to [`Self::STR_DELIMITER`] /
    /// [`Self::STR_ESCAPE_LEAD`] one axis over on the same
    /// Str-payload tokenization boundary — those two constants pin
    /// the ONE canonical delimiter byte AND the ONE canonical
    /// escape-lead byte the reader's outer + inner branch dispatch
    /// specialises on; this constant + its five per-role peers
    /// close the (named-escape, self-escape) decode-arm surface at
    /// the same closed-set [`Atom`] algebra.
    pub const NEWLINE_ESCAPE_SOURCE: char = 'n';

    /// Canonical newline-escape DECODED byte — the ONE `'\n'` C0
    /// control byte [`Self::decode_str_escape`]'s newline arm
    /// value-emits when the source char is [`Self::NEWLINE_ESCAPE_SOURCE`].
    /// Peer of the SOURCE constant on the SAME (source, decoded)
    /// escape-arm axis; the pairing (`NEWLINE_ESCAPE_SOURCE`,
    /// `NEWLINE_ESCAPE_DECODED`) IS the first row of the
    /// [`Self::NAMED_ESCAPE_TABLE`] two-column algebra.
    pub const NEWLINE_ESCAPE_DECODED: char = '\n';

    /// Canonical tab-escape SOURCE char — the ONE `'t'` byte
    /// [`Self::decode_str_escape`]'s tab arm pattern-matches on.
    /// Second of the three named-escape SOURCE `pub const` peers.
    pub const TAB_ESCAPE_SOURCE: char = 't';

    /// Canonical tab-escape DECODED byte — the ONE `'\t'` C0
    /// control byte [`Self::decode_str_escape`]'s tab arm
    /// value-emits when the source char is [`Self::TAB_ESCAPE_SOURCE`].
    /// Peer of the SOURCE constant on the SAME (source, decoded)
    /// escape-arm axis; the pairing (`TAB_ESCAPE_SOURCE`,
    /// `TAB_ESCAPE_DECODED`) IS the second row of the
    /// [`Self::NAMED_ESCAPE_TABLE`] two-column algebra.
    pub const TAB_ESCAPE_DECODED: char = '\t';

    /// Canonical carriage-return-escape SOURCE char — the ONE `'r'`
    /// byte [`Self::decode_str_escape`]'s carriage-return arm
    /// pattern-matches on. Third of the three named-escape SOURCE
    /// `pub const` peers.
    pub const CARRIAGE_RETURN_ESCAPE_SOURCE: char = 'r';

    /// Canonical carriage-return-escape DECODED byte — the ONE
    /// `'\r'` C0 control byte [`Self::decode_str_escape`]'s
    /// carriage-return arm value-emits when the source char is
    /// [`Self::CARRIAGE_RETURN_ESCAPE_SOURCE`]. Peer of the SOURCE
    /// constant on the SAME (source, decoded) escape-arm axis; the
    /// pairing (`CARRIAGE_RETURN_ESCAPE_SOURCE`,
    /// `CARRIAGE_RETURN_ESCAPE_DECODED`) IS the third row of the
    /// [`Self::NAMED_ESCAPE_TABLE`] two-column algebra.
    pub const CARRIAGE_RETURN_ESCAPE_DECODED: char = '\r';

    /// Canonical NAMED-escape table — the closed-set ALL array over
    /// the substrate's three (SOURCE, DECODED) pairings the
    /// pattern-distinct-from-value named-escape arms of
    /// [`Self::decode_str_escape`] emit, in canonical declaration
    /// order (newline / tab / carriage-return). Forced-arity
    /// `[(char, char); 3]` composition — a hypothetical fourth
    /// named-escape arm (e.g. `'0' → '\0'` for the NUL byte, `'e'
    /// → '\x1b'` for ESC, or a Racket-compat `'a' → '\x07'` for
    /// BEL) extends [`Self::decode_str_escape`]'s match ONCE +
    /// this array ONCE + TWO new per-role `pub const`s (one on
    /// each axis) in lockstep; rustc's forced-arity check on
    /// `[(char, char); N]` binds the extension through the array
    /// declaration site. Sibling posture to
    /// [`QuoteForm::PREFIXES`] / [`QuoteForm::IAC_FORGE_TAGS`] on
    /// the outer-tokenizer quote-family axis — where those ALL
    /// arrays close the reader-prefix + canonical-form byte
    /// vocabularies on the [`QuoteForm`] closed set, this array
    /// closes the named-escape (source, decoded) pairing vocabulary
    /// on the inner-tokenizer Str-escape axis of the [`Atom`]
    /// closed set.
    ///
    /// The `[(char, char); 3]` shape (rather than a `[char; 3]`
    /// singleton) is load-bearing: the escape-arm is a projection
    /// from a source byte to a decoded byte, both bytes are typed
    /// data, and pinning them as a PAIR at the array declaration
    /// site closes the drift channel between pattern (source) and
    /// value (decoded) that a scalar array would leave open.
    ///
    /// Excludes the two pattern-equals-value self-escape arms
    /// (`Self::STR_DELIMITER → Self::STR_DELIMITER`,
    /// `Self::STR_ESCAPE_LEAD → Self::STR_ESCAPE_LEAD`) because
    /// those bind through [`Self::STR_DELIMITER`] +
    /// [`Self::STR_ESCAPE_LEAD`] one axis over on the Str-payload
    /// delimiter axis — the (source, decoded) pairing there is
    /// definitionally the identity by algebra design (a delimiter-
    /// swap propagates through pattern AND value at ONE constant
    /// per axis). This array closes the OTHER three arms — the
    /// pattern-DISTINCT-from-value named-escape rows.
    pub const NAMED_ESCAPE_TABLE: [(char, char); 3] = [
        (Self::NEWLINE_ESCAPE_SOURCE, Self::NEWLINE_ESCAPE_DECODED),
        (Self::TAB_ESCAPE_SOURCE, Self::TAB_ESCAPE_DECODED),
        (
            Self::CARRIAGE_RETURN_ESCAPE_SOURCE,
            Self::CARRIAGE_RETURN_ESCAPE_DECODED,
        ),
    ];

    /// Canonical SELF-escape table — the closed-set ALL array over the
    /// substrate's TWO pattern-EQUALS-value arms of
    /// [`Self::decode_str_escape`], in canonical declaration order
    /// ([`Self::STR_DELIMITER`], [`Self::STR_ESCAPE_LEAD`]) matching
    /// the projection's match-arm order. Forced-arity `[char; 2]`
    /// composition — a hypothetical third self-escape byte (e.g. a
    /// raw-string mode adopting `'#'` as an additional self-escaping
    /// delimiter, or a Racket-compat `'|'` verbatim-symbol boundary)
    /// extends [`Self::decode_str_escape`]'s match ONCE + this array
    /// ONCE + ONE new `pub const` on the closed-set [`Atom`] algebra
    /// in lockstep; rustc's forced-arity check on `[char; N]` binds
    /// the extension through the array declaration site.
    ///
    /// Peer to [`Self::NAMED_ESCAPE_TABLE`] on the SAME Str-payload
    /// tokenization boundary: where `NAMED_ESCAPE_TABLE` closes the
    /// THREE pattern-DISTINCT-from-value named-escape rows (`'n' →
    /// '\n'`, `'t' → '\t'`, `'r' → '\r'`), this array closes the TWO
    /// pattern-EQUALS-value self-escape rows (`STR_DELIMITER →
    /// STR_DELIMITER`, `STR_ESCAPE_LEAD → STR_ESCAPE_LEAD`). The two
    /// arrays together span the FIVE non-passthrough arms of
    /// [`Self::decode_str_escape`] — every byte the reader's
    /// `Token::Str` escape-handler branch specialises on lives in
    /// exactly ONE of the two closed-set arrays OR falls through the
    /// `other => other` passthrough at the algebra's projection.
    ///
    /// The `[char; 2]` shape (rather than a `[(char, char); 2]`
    /// pairing peer to `NAMED_ESCAPE_TABLE`) is load-bearing: the
    /// self-escape arm is definitionally the identity by algebra
    /// design (a delimiter-swap propagates through pattern AND value
    /// at ONE constant per axis), so the PAIRING collapses to a
    /// SCALAR on this sub-vocabulary. The SHAPE ASYMMETRY between the
    /// two peer arrays ([(char, char); N] vs [char; N]) IS the
    /// structural axis distinguishing the pattern-DISTINCT-from-value
    /// vocabulary from the pattern-EQUALS-value vocabulary — a
    /// consumer that reaches for the array shape encodes its
    /// vocabulary's identity relation in the SHAPE it iterates.
    ///
    /// Sibling posture to [`QuoteForm::PREFIXES`] +
    /// [`QuoteForm::IAC_FORGE_TAGS`] on the outer-tokenizer
    /// quote-family axis — where those ALL arrays close the TWO
    /// byte-vocabulary axes (reader prefix + iac-forge tag) of the
    /// outer-tokenizer `QuoteForm` closed set with parallel shapes,
    /// `NAMED_ESCAPE_TABLE` + `SELF_ESCAPE_TABLE` close the TWO
    /// sub-vocabularies (pattern-distinct + pattern-equals) of the
    /// inner-tokenizer `Atom` Str-escape closed set with asymmetric
    /// shapes reflecting the identity-relation asymmetry.
    pub const SELF_ESCAPE_TABLE: [char; 2] = [Self::STR_DELIMITER, Self::STR_ESCAPE_LEAD];

    /// Canonical closed-set ALL array over every escape-SOURCE byte
    /// [`Self::decode_str_escape`] has a non-passthrough arm for — the
    /// SPAN of the two peer sub-vocabulary source columns
    /// ([`Self::NAMED_ESCAPE_TABLE`]'s three (SOURCE, DECODED) pairs'
    /// SOURCE column + [`Self::SELF_ESCAPE_TABLE`]'s two rows) in
    /// canonical declaration order matching `decode_str_escape`'s
    /// match-arm order. Forced-arity `[char; 5]` composition — a
    /// hypothetical sixth non-passthrough arm (e.g. a `'0' → '\0'`
    /// NUL-byte extension, a Racket-compat `'a' → '\x07'` BEL, a raw-
    /// string mode adopting `'#'` as an additional self-escaping
    /// delimiter) extends [`Self::decode_str_escape`]'s match ONCE +
    /// EITHER `NAMED_ESCAPE_TABLE` or `SELF_ESCAPE_TABLE` ONCE + this
    /// ALL array ONCE + one new per-role `pub const` (or pair) in
    /// lockstep; rustc's forced-arity check on `[char; N]` binds the
    /// extension through the array declaration site.
    ///
    /// Cross-sub-vocabulary SPAN peer to [`Self::NAMED_ESCAPE_TABLE`] +
    /// [`Self::SELF_ESCAPE_TABLE`] at the ALL-array level: where those
    /// two arrays partition the FIVE non-passthrough arms of
    /// [`Self::decode_str_escape`] into the pattern-DISTINCT-from-value
    /// sub-vocabulary (3 rows, `[(char, char); 3]`) AND the pattern-
    /// EQUALS-value sub-vocabulary (2 rows, `[char; 2]`), this array
    /// closes the UNION of the SOURCE columns at ONE typed
    /// `[char; 5]` on the SAME closed-set [`Atom`] algebra. Pre-lift
    /// the SPAN identity lived at TWO sites: the runtime iterator
    /// chain
    /// `Atom::NAMED_ESCAPE_TABLE.iter().map(|&(src, _)| src)
    /// .chain(Atom::SELF_ESCAPE_TABLE.iter().copied()).collect()` at
    /// `atom_decode_str_escape_composes_end_to_end_through_reader_for_every_named_arm`
    /// AND the prose docstring for [`Self::SELF_ESCAPE_TABLE`] naming
    /// "the FIVE non-passthrough arms" as a cardinality identity. Post-
    /// lift the SPAN binds at ONE forced-arity `[char; 5]` on the
    /// [`Atom`] algebra so consumers that want "every char for which
    /// decode_str_escape is not the identity passthrough" iterate the
    /// typed array rather than reassembling the two peer arrays at
    /// each callsite.
    ///
    /// Also sibling-shape to [`Sexp::LIST_DELIMITERS`] (`[char; 2]` on
    /// the outer-structural paired-delimiter axis of the closed-set
    /// [`Sexp`] algebra), [`Sexp::COMMENT_DELIMITERS`] (`[char; 2]` on
    /// the reader-discard paired-delimiter axis of the SAME [`Sexp`]
    /// algebra), [`Atom::BOOL_LITERALS`] (`[&'static str; 2]` on the
    /// Scheme-bool spelling axis of this same [`Atom`] algebra), and
    /// [`QuoteForm::LEADS`] (`[char; 3]` on the DISTINCT-lead-byte
    /// sub-vocabulary axis of the closed-set [`QuoteForm`] algebra) —
    /// every closed-set outer projection on the substrate that carries
    /// a scalar `[char; N]` sub-vocabulary now pins its canonical
    /// bytes at ONE `pub const` per role plus a forced-arity ALL array
    /// for family-wide consumers.
    ///
    /// Composition law (SPAN): `ESCAPE_SOURCES ==
    /// [NAMED_ESCAPE_TABLE[0].0, NAMED_ESCAPE_TABLE[1].0,
    /// NAMED_ESCAPE_TABLE[2].0, SELF_ESCAPE_TABLE[0],
    /// SELF_ESCAPE_TABLE[1]]` AND `ESCAPE_SOURCES.len() ==
    /// NAMED_ESCAPE_TABLE.len() + SELF_ESCAPE_TABLE.len()` — the
    /// forced-arity + canonical declaration order together pin every
    /// downstream index-sweep consumer to the (named-source-column
    /// prefix, self-source-column suffix) partition at rustc time; a
    /// reorder that broke the partition (e.g. interleaving the two
    /// sub-vocabularies' rows) fails at the composition pin below.
    ///
    /// Path-uniformity contract carried at the row level: for every
    /// `esc` in `ESCAPE_SOURCES`, `Self::decode_str_escape(esc) != esc`
    /// iff `esc` is a NAMED_ESCAPE_TABLE SOURCE row (the three
    /// pattern-DISTINCT-from-value arms), and `Self::decode_str_escape
    /// (esc) == esc` iff `esc` is a SELF_ESCAPE_TABLE row (the two
    /// pattern-EQUALS-value arms). The union is exhaustive over the
    /// FIVE non-passthrough arms so no `ESCAPE_SOURCES` row projects
    /// through the `other => other` passthrough branch — the arm-set
    /// closure is pinned structurally at
    /// `atom_escape_sources_every_row_projects_through_a_non_passthrough_arm_of_decode_str_escape`.
    ///
    /// Pairwise disjointness: every row is distinct from every other
    /// row — the closed-set SPAN inherits pairwise disjointness from
    /// the two peer sub-vocabularies (each already pairwise distinct
    /// via `atom_named_escape_table_sources_pairwise_distinct` +
    /// `atom_self_escape_table_pairwise_distinct`) PLUS the cross-
    /// sub-vocabulary disjointness pinned by
    /// `atom_self_escape_table_disjoint_from_named_escape_table`. This
    /// ALL array's own `atom_escape_sources_pairwise_distinct` test
    /// closes the disjointness contract at the SPAN-level so a future
    /// refactor that added a sixth arm whose SOURCE aliased an
    /// existing arm surfaces HERE rather than at a distant reader
    /// round-trip.
    ///
    /// Future consumers that compose against [`Self::ESCAPE_SOURCES`]:
    /// - LSP / REPL completion for the escape-source vocabulary — the
    ///   completion set IS `Self::ESCAPE_SOURCES` rather than a
    ///   per-consumer chain over the two peer arrays.
    /// - `tatara-check` coverage assertions that a `.lisp` corpus
    ///   exercises every non-passthrough escape arm — the sweep IS
    ///   `Self::ESCAPE_SOURCES.iter()` rather than a runtime chain
    ///   over `NAMED_ESCAPE_TABLE.iter().map(|&(src, _)| src)
    ///   .chain(SELF_ESCAPE_TABLE.iter().copied())`.
    /// - Any future syntax-highlighter that colors escape sequences —
    ///   the classifier binds through `Self::ESCAPE_SOURCES` rather
    ///   than through two parallel per-sub-vocabulary lookups.
    /// - Any future fuzz-input generator that biases toward escape
    ///   sequences — the source-byte pool IS `Self::ESCAPE_SOURCES`
    ///   rather than reassembled from the two peer arrays.
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the FIVE non-
    /// passthrough source bytes now bind at ONE typed `[char; 5]` on
    /// the closed-set [`Atom`] algebra rather than at a runtime chain
    /// over the two peer sub-vocabulary arrays reassembled per
    /// consumer. THEORY.md §V.1 — knowable platform; the non-
    /// passthrough source-byte SPAN becomes load-bearing typed data at
    /// the algebra level. THEORY.md §VI.1 — generation over
    /// composition; the "FIVE non-passthrough arms" identity that
    /// lived as prose in the [`Self::SELF_ESCAPE_TABLE`] docstring AND
    /// as a runtime iterator chain at one test site regenerates
    /// identically through this ONE typed forced-arity array.
    pub const ESCAPE_SOURCES: [char; 5] = [
        Self::NEWLINE_ESCAPE_SOURCE,
        Self::TAB_ESCAPE_SOURCE,
        Self::CARRIAGE_RETURN_ESCAPE_SOURCE,
        Self::STR_DELIMITER,
        Self::STR_ESCAPE_LEAD,
    ];

    /// Canonical closed-set ALL array over every DECODED byte
    /// [`Self::decode_str_escape`] can emit from a non-passthrough arm
    /// — the SPAN of the two peer sub-vocabulary DECODED columns
    /// ([`Self::NAMED_ESCAPE_TABLE`]'s three (SOURCE, DECODED) pairs'
    /// DECODED column + [`Self::SELF_ESCAPE_TABLE`]'s two rows, which
    /// are pattern-EQUALS-value so their DECODED column is definitionally
    /// the row byte itself) in canonical declaration order matching
    /// `decode_str_escape`'s match-arm order. Forced-arity `[char; 5]`
    /// composition — a hypothetical sixth non-passthrough arm (e.g. a
    /// `'0' → '\0'` NUL-byte extension, a Racket-compat `'a' → '\x07'`
    /// BEL, a raw-string mode adopting `'#'` as an additional
    /// self-escaping delimiter) extends [`Self::decode_str_escape`]'s
    /// match ONCE + EITHER `NAMED_ESCAPE_TABLE` or `SELF_ESCAPE_TABLE`
    /// ONCE + this ALL array ONCE + [`Self::ESCAPE_SOURCES`] ONCE + one
    /// new per-role `pub const` (or pair) in lockstep; rustc's forced-
    /// arity check on `[char; N]` binds the extension through the array
    /// declaration site.
    ///
    /// Column-dual peer to [`Self::ESCAPE_SOURCES`] on the SAME closed-set
    /// [`Atom`] algebra: where `ESCAPE_SOURCES` closes the SOURCE column
    /// of the FIVE non-passthrough arms at ONE typed `[char; 5]`, this
    /// array closes the DECODED column at the SAME shape. Together the
    /// two arrays close the (SOURCE, DECODED) cross-product of
    /// `decode_str_escape`'s non-passthrough arm-set at two byte-
    /// identical `[char; 5]` shapes on the SAME closed-set [`Atom`]
    /// algebra — the shape symmetry across the two columns of the SAME
    /// arm-set is itself a typed load-bearing invariant carrying the
    /// column-dual identity relation on the algebra.
    ///
    /// Cross-sub-vocabulary SPAN peer to [`Self::NAMED_ESCAPE_TABLE`] +
    /// [`Self::SELF_ESCAPE_TABLE`] at the ALL-array level: where those
    /// two arrays partition the FIVE non-passthrough arms of
    /// [`Self::decode_str_escape`] into the pattern-DISTINCT-from-value
    /// sub-vocabulary (3 rows, `[(char, char); 3]`) AND the pattern-
    /// EQUALS-value sub-vocabulary (2 rows, `[char; 2]`), this array
    /// closes the UNION of the DECODED columns at ONE typed
    /// `[char; 5]` on the SAME closed-set [`Atom`] algebra. Pre-lift
    /// the DECODED SPAN identity lived at ZERO callsites — the substrate
    /// had a typed SOURCE-column SPAN ([`Self::ESCAPE_SOURCES`]) but the
    /// DECODED-column SPAN was only reachable by iterating the two peer
    /// sub-vocabulary arrays' DECODED columns per consumer OR by mapping
    /// `ESCAPE_SOURCES` through [`Self::decode_str_escape`] at runtime;
    /// post-lift the DECODED SPAN binds at ONE forced-arity `[char; 5]`
    /// on the [`Atom`] algebra so consumers that want "every byte
    /// decode_str_escape can emit from a typed non-passthrough arm"
    /// iterate the typed array rather than reassembling it per callsite.
    ///
    /// Also sibling-shape to [`Sexp::LIST_DELIMITERS`] (`[char; 2]` on
    /// the outer-structural paired-delimiter axis of the closed-set
    /// [`Sexp`] algebra), [`Sexp::COMMENT_DELIMITERS`] (`[char; 2]` on
    /// the reader-discard paired-delimiter axis of the SAME [`Sexp`]
    /// algebra), [`Atom::BOOL_LITERALS`] (`[&'static str; 2]` on the
    /// Scheme-bool spelling axis of this same [`Atom`] algebra), and
    /// [`QuoteForm::LEADS`] (`[char; 3]` on the DISTINCT-lead-byte
    /// sub-vocabulary axis of the closed-set [`QuoteForm`] algebra) —
    /// every closed-set outer projection on the substrate that carries
    /// a scalar `[char; N]` sub-vocabulary now pins its canonical bytes
    /// at ONE `pub const` per role plus a forced-arity ALL array for
    /// family-wide consumers.
    ///
    /// Composition law (SPAN): `ESCAPE_DECODED ==
    /// [NAMED_ESCAPE_TABLE[0].1, NAMED_ESCAPE_TABLE[1].1,
    /// NAMED_ESCAPE_TABLE[2].1, SELF_ESCAPE_TABLE[0],
    /// SELF_ESCAPE_TABLE[1]]` AND `ESCAPE_DECODED.len() ==
    /// NAMED_ESCAPE_TABLE.len() + SELF_ESCAPE_TABLE.len()` — the
    /// forced-arity + canonical declaration order together pin every
    /// downstream index-sweep consumer to the (named-decoded-column
    /// prefix, self-decoded-column suffix) partition at rustc time; a
    /// reorder that broke the partition (e.g. interleaving the two
    /// sub-vocabularies' rows) fails at the composition pin below.
    ///
    /// Column-dual pointwise projection law: for every index `i` in
    /// `0..5`, `ESCAPE_DECODED[i] == Self::decode_str_escape(
    /// ESCAPE_SOURCES[i])`. The two forced-arity `[char; 5]` arrays are
    /// the SOURCE column and DECODED column of `decode_str_escape`'s
    /// non-passthrough arm-set — the pointwise projection identity is
    /// pinned structurally at
    /// `atom_escape_decoded_projects_pointwise_from_escape_sources_through_decode_str_escape`.
    ///
    /// Pairwise disjointness: every row is distinct from every other
    /// row — `'\n'`, `'\t'`, `'\r'`, `'"'`, `'\\'` are five distinct
    /// C0-and-ASCII bytes. Distinctness on the DECODED column follows
    /// from (a) the NAMED sub-vocabulary's DECODED-column pairwise
    /// distinctness at `atom_named_escape_table_decoded_pairwise_distinct`,
    /// (b) the SELF sub-vocabulary's pairwise distinctness at
    /// `atom_self_escape_table_pairwise_distinct`, and (c) the fact
    /// that no NAMED-DECODED byte (`'\n'`, `'\t'`, `'\r'` — all C0
    /// control bytes) can alias a SELF byte (`'"'`, `'\\'` — printable
    /// ASCII bytes). The pairwise-distinctness pin below closes the
    /// contract at the SPAN level so a future refactor that added a
    /// sixth arm whose DECODED aliased an existing row surfaces HERE
    /// rather than at a distant reader round-trip.
    ///
    /// Future consumers that compose against [`Self::ESCAPE_DECODED`]:
    /// - A Str-render / encoder consumer that needs to escape a DECODED
    ///   byte back into its SOURCE form — the classifier IS "is this
    ///   byte in `Self::ESCAPE_DECODED`?" rather than a per-consumer
    ///   chain over the two peer sub-vocabularies' DECODED columns.
    /// - LSP / REPL diagnostic rendering that needs to name every byte
    ///   the substrate's escape-handler can emit — the completion set
    ///   IS `Self::ESCAPE_DECODED` rather than a runtime map through
    ///   `decode_str_escape` from `ESCAPE_SOURCES`.
    /// - A syntax-highlighter that colors decoded-escape byte payloads —
    ///   the classifier binds through `Self::ESCAPE_DECODED` rather
    ///   than through two parallel per-sub-vocabulary lookups.
    /// - A fuzz-input generator that biases toward decoded-escape byte
    ///   payloads (probing the reader's error-recovery path when a
    ///   raw C0 byte appears inside a Str payload) — the target-byte
    ///   pool IS `Self::ESCAPE_DECODED` rather than reassembled from
    ///   the two peer arrays.
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the FIVE
    /// DECODED bytes of the non-passthrough arm-set now bind at ONE
    /// typed `[char; 5]` on the closed-set [`Atom`] algebra rather than
    /// at a runtime map through `decode_str_escape` from
    /// `ESCAPE_SOURCES`. THEORY.md §V.1 — knowable platform; the
    /// non-passthrough DECODED-byte SPAN becomes load-bearing typed
    /// data at the algebra level. THEORY.md §VI.1 — generation over
    /// composition; the column-dual identity that lived only as a
    /// runtime `decode_str_escape` projection of the peer SOURCE-column
    /// SPAN regenerates identically through this ONE typed forced-arity
    /// array.
    pub const ESCAPE_DECODED: [char; 5] = [
        Self::NEWLINE_ESCAPE_DECODED,
        Self::TAB_ESCAPE_DECODED,
        Self::CARRIAGE_RETURN_ESCAPE_DECODED,
        Self::STR_DELIMITER,
        Self::STR_ESCAPE_LEAD,
    ];

    /// Canonical closed-set ALL array over every `(SOURCE, DECODED)`
    /// pair [`Self::decode_str_escape`] projects at a non-passthrough
    /// arm — the paired-column SPAN closing BOTH columns of the FIVE
    /// non-passthrough arms at ONE typed forced-arity
    /// `[(char, char); 5]` on the closed-set [`Atom`] algebra.
    /// Composes as `NAMED_ESCAPE_TABLE`'s three pattern-DISTINCT-from-
    /// value rows (which are already `(char, char)` shape) followed by
    /// `SELF_ESCAPE_TABLE`'s two pattern-EQUALS-value rows re-shaped as
    /// `(row, row)` pairs (the definitional-identity closure of the
    /// self-escape sub-vocabulary at the paired shape), in canonical
    /// declaration order matching `decode_str_escape`'s match-arm order.
    ///
    /// Cross-column peer-collapse of [`Self::ESCAPE_SOURCES`] +
    /// [`Self::ESCAPE_DECODED`] — the two byte-identical `[char; 5]`
    /// column-dual arrays close the SOURCE column and DECODED column
    /// SEPARATELY at ONE forced-arity `[char; 5]` each; this array
    /// closes BOTH columns TOGETHER at ONE typed forced-arity
    /// `[(char, char); 5]` on the SAME closed-set [`Atom`] algebra.
    /// Together the three arrays close the FIVE non-passthrough arms
    /// at THREE typed forced-arity shapes: `[char; 5]` on the SOURCE
    /// column, `[char; 5]` on the DECODED column, and `[(char, char);
    /// 5]` on the paired-column composition. The shape symmetry
    /// `(SOURCE, DECODED)` pair at row `i` IS
    /// `(ESCAPE_SOURCES[i], ESCAPE_DECODED[i])` is a load-bearing
    /// pointwise identity carrying the two-column composition relation
    /// on the algebra.
    ///
    /// Paired-column SPAN peer to [`Self::NAMED_ESCAPE_TABLE`] +
    /// [`Self::SELF_ESCAPE_TABLE`] at the paired-shape level: where
    /// those two arrays partition the FIVE arms into the pattern-
    /// DISTINCT-from-value sub-vocabulary (3 rows already at
    /// `[(char, char); 3]` shape by algebra design) AND the pattern-
    /// EQUALS-value sub-vocabulary (2 rows at `[char; 2]` shape by
    /// definitional-identity collapse), this array closes the UNION of
    /// the two sub-vocabularies at ONE typed `[(char, char); 5]` — the
    /// self-escape rows re-shaped from `char` to `(char, char)` at the
    /// SPAN level via the definitional-identity `(row, row)`
    /// composition. Pre-lift the paired-column SPAN identity lived at
    /// ZERO callsites at the paired shape — consumers wanting "every
    /// `(SOURCE, DECODED)` pair `decode_str_escape` projects at a non-
    /// passthrough arm on the closed-set [`Atom`] algebra" had to zip
    /// the two column-dual `[char; 5]` peer arrays at their sites OR
    /// iterate `NAMED_ESCAPE_TABLE` and re-shape `SELF_ESCAPE_TABLE`'s
    /// rows to `(row, row)` per callsite. Post-lift the paired-column
    /// SPAN binds at ONE forced-arity `[(char, char); 5]` on the
    /// [`Atom`] algebra.
    ///
    /// Also sibling-shape to [`Self::NAMED_ESCAPE_TABLE`]
    /// (`[(char, char); 3]` on the same paired-column axis, one sub-
    /// vocabulary over on the pattern-DISTINCT-from-value axis of the
    /// SAME closed-set [`Atom`] algebra) — the paired-column shape is
    /// the substrate-canonical shape for closing a `(SOURCE, DECODED)`
    /// cross-product at ONE typed array on the algebra; extending it
    /// from the NAMED sub-vocabulary's 3-row shape to the SPAN's 5-row
    /// shape is a mechanical arity extension. A hypothetical sixth
    /// non-passthrough arm (e.g. a `'0' → '\0'` NUL-byte extension,
    /// a Racket-compat `'a' → '\x07'` BEL, a raw-string mode adopting
    /// `'#'` as an additional self-escaping delimiter) extends
    /// [`Self::decode_str_escape`]'s match ONCE plus EITHER
    /// `NAMED_ESCAPE_TABLE` or `SELF_ESCAPE_TABLE` ONCE plus this ALL
    /// array ONCE plus both column-dual `[char; 5]` peer arrays
    /// ([`Self::ESCAPE_SOURCES`] and [`Self::ESCAPE_DECODED`]) ONCE
    /// each plus one new per-role `pub const` (or pair) in lockstep;
    /// rustc's forced-arity check on `[(char, char); N]` binds the
    /// extension through the array declaration site.
    ///
    /// Composition law (paired SPAN): for every index `i` in `0..5`,
    /// `ESCAPE_TABLE[i] == (ESCAPE_SOURCES[i], ESCAPE_DECODED[i])`.
    /// The forced-arity `[(char, char); 5]` + canonical declaration
    /// order pin every downstream index-sweep consumer to the (named
    /// prefix, self suffix) partition at rustc time. The paired-SPAN
    /// row identity is pinned structurally at
    /// `atom_escape_table_composes_pointwise_from_escape_sources_and_escape_decoded_column_duals`.
    ///
    /// Sub-vocabulary partition law: `ESCAPE_TABLE[0..3] ==
    /// NAMED_ESCAPE_TABLE` (the pattern-DISTINCT-from-value sub-
    /// vocabulary at its native paired shape passes through
    /// identically), AND for i in 3..5, `ESCAPE_TABLE[i] ==
    /// (SELF_ESCAPE_TABLE[i-3], SELF_ESCAPE_TABLE[i-3])` (the pattern-
    /// EQUALS-value sub-vocabulary re-shapes from `char` to
    /// `(row, row)` at the SPAN level via the definitional-identity
    /// collapse). Pinned structurally at
    /// `atom_escape_table_partitions_into_named_paired_prefix_and_self_reshape_suffix`.
    ///
    /// Pattern-classification partition law: for every index `i` in
    /// `0..3`, `ESCAPE_TABLE[i].0 != ESCAPE_TABLE[i].1` (the NAMED
    /// pattern-DISTINCT-from-value prefix); for every index `i` in
    /// `3..5`, `ESCAPE_TABLE[i].0 == ESCAPE_TABLE[i].1` (the SELF
    /// pattern-EQUALS-value suffix). The classification carried in the
    /// row's per-column identity relation IS the sub-vocabulary
    /// identity — a consumer classifying an escape arm reads the sub-
    /// vocabulary off `row.0 == row.1` rather than off an index range
    /// or a separate tag. Pinned structurally at
    /// `atom_escape_table_named_prefix_is_pattern_distinct_and_self_suffix_is_pattern_equals`.
    ///
    /// Pointwise projection law: for every `(src, decoded)` in
    /// `ESCAPE_TABLE`, `Self::decode_str_escape(src) == decoded`. The
    /// paired-column SPAN closes the (input, output) cross-product of
    /// `decode_str_escape`'s non-passthrough arm-set at ONE typed
    /// array so a refactor that drifted the arm-set (swapped rows,
    /// added a row without extending the array, or removed a row
    /// without extending the array) surfaces HERE at the first drifted
    /// pair rather than at a distant sweep site.
    ///
    /// Future consumers that compose against [`Self::ESCAPE_TABLE`]:
    /// - A round-trip reader/renderer that pairs SOURCE bytes with
    ///   their DECODED payloads — the paired vocabulary IS
    ///   `Self::ESCAPE_TABLE` rather than a zip of the two column-dual
    ///   peer arrays.
    /// - LSP / REPL diagnostic rendering that names both columns of
    ///   every non-passthrough arm — the completion set IS
    ///   `Self::ESCAPE_TABLE` rather than reassembled from the two
    ///   sub-vocabulary arrays via a `char → (char, char)` re-shape on
    ///   the SELF rows.
    /// - A syntax-highlighter that colors both the SOURCE byte and the
    ///   DECODED payload of every escape arm — the classifier binds
    ///   through `Self::ESCAPE_TABLE` rather than through two parallel
    ///   per-column lookups.
    /// - A fuzz-input generator that exercises `decode_str_escape`'s
    ///   projection round-trip — the input-output pool IS
    ///   `Self::ESCAPE_TABLE` rather than a runtime zip of the peer
    ///   arrays.
    /// - A hypothetical `EscapeArm` typed sum enumerating the FIVE
    ///   non-passthrough arms at ONE closed-set enum on the algebra
    ///   (with `ESCAPE_TABLE` becoming its `.pair()` projection).
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the FIVE
    /// `(SOURCE, DECODED)` pairs of the non-passthrough arm-set now
    /// bind at ONE typed `[(char, char); 5]` on the closed-set
    /// [`Atom`] algebra rather than at a runtime zip of the two peer
    /// column-dual arrays. THEORY.md §V.1 — knowable platform; the
    /// non-passthrough paired-column SPAN becomes load-bearing typed
    /// data at the algebra level. THEORY.md §VI.1 — generation over
    /// composition; the paired-column identity that lived only as a
    /// runtime zip of the peer column-dual `[char; 5]` SPANs
    /// regenerates identically through this ONE typed forced-arity
    /// pair-array. THEORY.md §II.1 invariant 5 — composition preserves
    /// proofs; the pointwise composition law `ESCAPE_TABLE[i] ==
    /// (ESCAPE_SOURCES[i], ESCAPE_DECODED[i])` is a load-bearing
    /// structural invariant carrying the two-column composition
    /// relation between the paired SPAN and its two column-dual peer
    /// SPANs. A refactor that drifted any of the three arrays'
    /// declaration orders (paired SPAN, SOURCE-column SPAN, DECODED-
    /// column SPAN) OR drifted `decode_str_escape`'s match-arm
    /// ordering surfaces at the first drifted index across the three
    /// pointwise composition pins.
    pub const ESCAPE_TABLE: [(char, char); 5] = [
        Self::NAMED_ESCAPE_TABLE[0],
        Self::NAMED_ESCAPE_TABLE[1],
        Self::NAMED_ESCAPE_TABLE[2],
        (Self::SELF_ESCAPE_TABLE[0], Self::SELF_ESCAPE_TABLE[0]),
        (Self::SELF_ESCAPE_TABLE[1], Self::SELF_ESCAPE_TABLE[1]),
    ];

    /// A string payload as source text, quoted and escaped so that
    /// [`Self::decode_str_escape`] (plus the reader's `\u{…}` arm) reads back
    /// exactly these bytes.
    ///
    /// The inverse of the reader, deliberately written as one: anything the
    /// reader cannot decode is emitted as `\u{…}` rather than as a shorter
    /// escape that would mean something different.
    #[must_use]
    pub fn escape_str_payload(s: &str) -> String {
        let mut out = String::with_capacity(s.len() + 2);
        out.push(Self::STR_DELIMITER);
        for c in s.chars() {
            match c {
                Self::STR_DELIMITER | Self::STR_ESCAPE_LEAD => {
                    out.push(Self::STR_ESCAPE_LEAD);
                    out.push(c);
                }
                Self::NEWLINE_ESCAPE_DECODED => {
                    out.push(Self::STR_ESCAPE_LEAD);
                    out.push(Self::NEWLINE_ESCAPE_SOURCE);
                }
                Self::TAB_ESCAPE_DECODED => {
                    out.push(Self::STR_ESCAPE_LEAD);
                    out.push(Self::TAB_ESCAPE_SOURCE);
                }
                Self::CARRIAGE_RETURN_ESCAPE_DECODED => {
                    out.push(Self::STR_ESCAPE_LEAD);
                    out.push(Self::CARRIAGE_RETURN_ESCAPE_SOURCE);
                }
                // Everything else the reader cannot round-trip literally goes
                // out as `\u{…}`, which it CAN. Printable characters — including
                // every non-ASCII one — are emitted raw, so ordinary text stays
                // readable.
                c if c.is_control() => {
                    out.push_str("\\u{");
                    out.push_str(&alloc_hex(c as u32));
                    out.push('}');
                }
                c => out.push(c),
            }
        }
        out.push(Self::STR_DELIMITER);
        out
    }

    pub const fn decode_str_escape(esc: char) -> char {
        match esc {
            Self::NEWLINE_ESCAPE_SOURCE => Self::NEWLINE_ESCAPE_DECODED,
            Self::TAB_ESCAPE_SOURCE => Self::TAB_ESCAPE_DECODED,
            Self::CARRIAGE_RETURN_ESCAPE_SOURCE => Self::CARRIAGE_RETURN_ESCAPE_DECODED,
            Self::STR_DELIMITER => Self::STR_DELIMITER,
            Self::STR_ESCAPE_LEAD => Self::STR_ESCAPE_LEAD,
            other => other,
        }
    }

    /// Canonical [`Self::Symbol`] constructor — first of the six per-
    /// variant typed-construct methods on the closed-set [`Atom`]
    /// algebra. Takes `impl Into<String>` so the consumer composes any
    /// `&str` / `String` / `Cow<'_, str>` into the typed payload without
    /// pre-coercing at its site — the `.into()` boundary lives at this
    /// method on the algebra, parallel to how the [`Sexp`] outer
    /// constructors ([`Sexp::symbol`], [`Sexp::keyword`],
    /// [`Sexp::string`]) accept the same `impl Into<String>` shape at
    /// the outer algebra layer.
    ///
    /// Sibling typed-construct family on the closed-set [`Atom`]
    /// algebra — paired section-for-retraction with the soft-projection
    /// family ([`Self::as_symbol`], [`Self::as_keyword`],
    /// [`Self::as_string`], [`Self::as_int`], [`Self::as_float`],
    /// [`Self::as_bool`]). Pre-lift the typed-construct family was
    /// missing from the algebra: consumers reached for the bare
    /// `Self::Symbol(s.into())` tuple-variant constructor + `.into()`
    /// coercion at every site (with no `impl Into` ergonomy on the
    /// algebra), AND the soft-projection family had no constructor
    /// peer — section-for-retraction was uneven. Post-lift every
    /// consumer that builds an [`Atom`] from a typed payload at one
    /// site AND projects an [`Atom`] back to its typed payload at
    /// another binds to ONE method per direction on the algebra. The
    /// six [`Sexp`] outer constructors ([`Sexp::symbol`] through
    /// [`Sexp::boolean`]) route through `Self::Atom(Atom::X(_))` —
    /// `.into()` ergonomy on the inner algebra is reused at the outer
    /// algebra without re-derivation.
    ///
    /// Round-trip law binding it to the soft-projection sibling: for
    /// every `s: &str`, `Atom::symbol(s).as_symbol() == Some(s)` —
    /// every other arm projects to `None`. Same posture across the
    /// five sibling pairs (`Atom::keyword(s).as_keyword() == Some(s)`,
    /// …). The `kind()` projection ([`Self::kind`]) similarly
    /// round-trips through the construct face: `Atom::symbol(_).kind()
    /// == AtomKind::Symbol`.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 2 — free middle;
    /// every consumer that constructs an [`Atom`] of a typed kind binds
    /// to ONE typed method on the algebra rather than to the bare
    /// tuple-variant constructor + per-site `.into()` coercion.
    /// THEORY.md §V.1 — knowable platform; the `(AtomKind variant,
    /// typed construct method)` pair becomes a TYPE projection on the
    /// substrate's [`Atom`] algebra. THEORY.md §VI.1 — generation over
    /// composition; the `[Sexp; 6]` outer constructors at
    /// [`Sexp::symbol`]–[`Sexp::boolean`] regenerate identically
    /// through `Self::Atom(Atom::X(_))` composition rather than
    /// re-deriving the `.into()` + tuple-variant pair per outer
    /// constructor.
    ///
    /// Frontier inspiration: Racket's `(symbol 'x)` / `(string s)` —
    /// the typed-construct face the consumer reaches for a typed
    /// atomic value paired one-for-one with `(symbol? v)` /
    /// `(symbol->string v)` predicate/projection siblings; the
    /// substrate's [`Self::symbol`] / [`Self::as_symbol`] pair is the
    /// Rust-typed peer on the closed-set [`Atom`] algebra, with
    /// `impl Into<String>` standing in for Racket's typed-pair coerce
    /// face. MLIR's `mlir::SymbolAttr::get(ctx, name)` — typed-IR
    /// attribute construction routes through ONE typed factory paired
    /// with `mlir::dyn_cast<SymbolAttr>(attr)` on the projection face;
    /// `Atom::symbol` is the substrate's unstructured-Rust peer.
    #[must_use]
    pub fn symbol(s: impl Into<String>) -> Self {
        Self::Symbol(s.into())
    }

    /// Canonical [`Self::Keyword`] constructor — second of the six
    /// per-variant typed-construct methods on the closed-set [`Atom`]
    /// algebra. See [`Self::symbol`] for the algebra-level docstring.
    #[must_use]
    pub fn keyword(s: impl Into<String>) -> Self {
        Self::Keyword(s.into())
    }

    /// Canonical [`Self::Str`] constructor — third of the six per-variant
    /// typed-construct methods. The method name is `string` for
    /// consumer-vocabulary continuity with [`Self::as_string`] /
    /// [`Sexp::string`] / [`crate::error::SexpShape::String`] (the typed
    /// payload variant is `Str` for `String` shortening; the consumer-
    /// facing method keeps `string` for symmetry).
    #[must_use]
    pub fn string(s: impl Into<String>) -> Self {
        Self::Str(s.into())
    }

    /// Canonical [`Self::Int`] constructor — fourth of the six per-variant
    /// typed-construct methods. The `i64` is taken by value (no
    /// `impl Into<…>` widening) — strict typed identity at the algebra
    /// boundary, the same posture [`Self::as_int`] preserves on the
    /// soft-projection face (`Atom::Int(n)` projects to `Some(n)` only;
    /// the `Sexp::as_float` consumer is where Int→Float widening lives).
    #[must_use]
    pub fn int(n: i64) -> Self {
        Self::Int(n)
    }

    /// Canonical [`Self::Float`] constructor — fifth of the six
    /// per-variant typed-construct methods. The `f64` is taken by value
    /// (no `impl Into<…>` widening), matching [`Self::int`]'s strict
    /// typed-identity posture at the algebra boundary.
    #[must_use]
    pub fn float(n: f64) -> Self {
        Self::Float(n)
    }

    /// Canonical [`Self::Bool`] constructor — sixth and last of the six
    /// per-variant typed-construct methods on the closed-set [`Atom`]
    /// algebra. Together with the five siblings ([`Self::symbol`],
    /// [`Self::keyword`], [`Self::string`], [`Self::int`],
    /// [`Self::float`]) the per-`Atom`-variant typed-construct family is
    /// complete across all six closed-set arms, and pairs section-for-
    /// retraction with the soft-projection family ([`Self::as_symbol`],
    /// [`Self::as_keyword`], [`Self::as_string`], [`Self::as_int`],
    /// [`Self::as_float`], [`Self::as_bool`]) — every consumer that
    /// constructs an [`Atom`] from a typed payload at one site AND
    /// projects an [`Atom`] back to its typed payload at another binds
    /// to ONE method per direction on the algebra rather than to the
    /// bare tuple-variant constructor + the soft-projection method
    /// asymmetrically.
    ///
    /// The closed-set `bool` payload's Scheme-canonical `#t` / `#f`
    /// reader lexemes are dispatched at [`Self::from_lexeme`] (the
    /// typed-ENTRY classifier) — this method is the construction face
    /// the consumer composes the typed `bool` value into when building
    /// an [`Atom`] from already-typed Rust, parallel to how
    /// [`Self::int`] and [`Self::float`] take their typed payload by
    /// value.
    #[must_use]
    pub fn boolean(b: bool) -> Self {
        Self::Bool(b)
    }

    /// Project the atomic value into its closed-set [`AtomKind`] marker —
    /// `Symbol(_) → AtomKind::Symbol`, `Keyword(_) → AtomKind::Keyword`,
    /// `Str(_) → AtomKind::Str`, `Int(_) → AtomKind::Int`,
    /// `Float(_) → AtomKind::Float`, `Bool(_) → AtomKind::Bool`. The
    /// projection discards the payload and surfaces the typed
    /// discriminator that every per-atom-kind dispatch site (Hash cache-
    /// key bytes via [`AtomKind::hash_discriminator`], outer-shape
    /// projection via [`AtomKind::sexp_shape`], diagnostic label via
    /// [`AtomKind::label`]) keys on.
    ///
    /// Soft-projection peer of [`Sexp::as_quote_form`]: where
    /// `as_quote_form` decomposes the four homoiconic prefix wrappers
    /// into `(QuoteForm, &Sexp)`, `kind` decomposes the six atomic
    /// payloads into `AtomKind` alone — there is no inner-sexp body to
    /// surface, so the projection's return type is just the marker.
    /// Sibling-arm sweep with the quote-family `as_quote_form` /
    /// `QuoteForm` algebra lifts the (Atom variant, byte-discriminator,
    /// canonical-label, SexpShape variant) quadruple from per-callsite
    /// discipline (`Hash for Atom`'s six byte literals AND
    /// `domain::sexp_shape`'s six SexpShape literals) onto ONE typed
    /// algebra the substrate's diagnostic + cache-key surfaces both
    /// route through.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 2 — free middle; the
    /// (Atom variant, downstream-consumer-payload) pairing now binds at
    /// ONE typed projection site (this method composed with
    /// [`AtomKind`]'s arms) regardless of which consumer surface
    /// (cache-key Hash, diagnostic SexpShape, future LSP completion
    /// label) needs it. A regression that drifts ONE consumer's pairing
    /// from the others cannot reach the substrate's runtime.
    #[must_use]
    pub fn kind(&self) -> AtomKind {
        match self {
            Self::Symbol(_) => AtomKind::Symbol,
            Self::Keyword(_) => AtomKind::Keyword,
            Self::Str(_) => AtomKind::Str,
            Self::Int(_) => AtomKind::Int,
            Self::Float(_) => AtomKind::Float,
            Self::Bool(_) => AtomKind::Bool,
        }
    }

    /// Project the atomic payload to its canonical `&'static str`
    /// diagnostic label — `"symbol"` for [`Self::Symbol`], `"keyword"`
    /// for [`Self::Keyword`], `"string"` for [`Self::Str`], `"int"` for
    /// [`Self::Int`], `"float"` for [`Self::Float`], `"bool"` for
    /// [`Self::Bool`]. The outer-`Atom` peer on the [`Atom`] algebra of
    /// [`AtomKind::label`] (the marker-level label projection on the
    /// closed-set atomic-kind algebra) and [`crate::ast::Sexp::type_name`]
    /// (the outer-value label projection on the [`crate::ast::Sexp`]
    /// algebra composed through [`crate::ast::Sexp::shape`] +
    /// [`crate::error::SexpShape::label`]). Every label is byte-for-byte
    /// identical to the corresponding [`crate::error::SexpShape`] variant's
    /// label — the AtomKind ⊂ SexpShape label-vocabulary containment
    /// established by [`AtomKind::label`]'s composition through
    /// [`AtomKind::sexp_shape`] surfaces at the outer-`Atom` layer through
    /// this projection.
    ///
    /// Composition law: `atom.label() == atom.kind().label() ==
    /// atom.kind().sexp_shape().label()` for every `atom: &Atom`. The
    /// body composes [`Self::kind`] (the typed projection lifting each
    /// [`Atom`] variant into its peer [`AtomKind`] marker) with
    /// [`AtomKind::label`] (the canonical `&'static str` projection on the
    /// closed-set atomic-payload algebra), so the six atomic-arm labels
    /// live at ONE canonical site ([`crate::error::SexpShape::label`]'s
    /// atomic arms, via [`AtomKind::label`]'s composition through
    /// [`AtomKind::sexp_shape`]) rather than at TWO
    /// ([`crate::error::SexpShape::label`] AND a parallel six-arm match
    /// on the outer [`Atom`] algebra, pre-lift). Cross-algebra agreement
    /// law: `Sexp::Atom(atom.clone()).type_name() == atom.label()` for
    /// every `atom: Atom` — the outer-[`crate::ast::Sexp`] label
    /// projection at the atomic-payload arms routes through
    /// [`crate::ast::Sexp::shape`]'s
    /// `Self::Atom(a) => a.kind().sexp_shape()` arm which composes with
    /// [`crate::error::SexpShape::label`] byte-for-byte with this
    /// projection's `self.kind().label()` composition, so the (outer
    /// `Sexp` label, outer `Atom` label) agreement is a TYPED CONSEQUENCE
    /// of the two typed compositions rather than literal discipline at
    /// two sites.
    ///
    /// Sibling-shape lift to [`Self::kind`] (the closed-set atomic-kind
    /// projection): where `kind()` carries the typed [`AtomKind`] marker
    /// on the [`Atom`] algebra, `label()` carries the `&'static str`
    /// literal the rendered diagnostic surface wants (still derived from
    /// the typed marker, but flattened through [`AtomKind::label`] for
    /// substring-grep callers, future
    /// [`crate::error::LispError::TypeMismatch`] `got` slots keyed on an
    /// atomic witness before the outer [`crate::ast::Sexp`] wrap, and
    /// future LSP hover / REPL completion / audit-trail metric surfaces
    /// that hold an [`Atom`] value directly rather than a wrapped
    /// [`crate::ast::Sexp::Atom`]). The `&'static str` lifetime is
    /// load-bearing: the composition allocates nothing at runtime
    /// ([`Self::kind`] returns a `Copy` value and [`AtomKind::label`]
    /// yields `&'static str`).
    ///
    /// Pre-lift the (Atom variant, `&'static str` diagnostic label)
    /// pairing had no typed projection on the outer-[`Atom`] algebra —
    /// a consumer with a typed [`Atom`] in hand (a hand-authored
    /// [`Atom`] value at a test-harness diagnostic, a future
    /// [`crate::domain`] typed-kwarg gate that rejects on an atomic
    /// witness before the outer [`crate::ast::Sexp`] wrap, a future LSP
    /// hover surface that emits an atomic-payload identity without an
    /// enclosing [`crate::ast::Sexp::Atom`] wrap, a future audit-trail
    /// metric keyed on the observed atomic kind) wanting the canonical
    /// diagnostic label had to spell the two-step composition
    /// `atom.kind().label()` at every callsite, OR go through
    /// [`crate::ast::Sexp::Atom(atom.clone()).type_name()`] which wraps
    /// and unwraps for no runtime purpose. Post-lift the composition
    /// binds at ONE typed-algebra method on the outer [`Atom`] value-
    /// carrier — the SIXTH consumer of the outer-[`Atom`] projection
    /// surface (sibling of [`Self::kind`], [`Self::to_json`],
    /// `Atom::to_iac_forge_sexpr` (removed), [`Self::from_lexeme`], and the six
    /// per-variant soft-projection methods [`Self::as_symbol`] /
    /// [`Self::as_keyword`] / [`Self::as_string`] / [`Self::as_int`] /
    /// [`Self::as_float`] / [`Self::as_bool`] + the composite
    /// [`Self::as_symbol_or_string`]).
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the (Atom
    /// variant, `&'static str` diagnostic label) pairing becomes a TYPE
    /// projection on the outer-[`Atom`] algebra rather than a per-
    /// callsite `.kind().label()` two-step OR a wrap-through-Sexp
    /// [`crate::ast::Sexp::Atom(atom.clone()).type_name()`] round-trip.
    /// A typo or swap at the outer-`Atom` label site is no longer a
    /// runtime label drift but a compile error against the typed
    /// composition — the [`Atom`] ↔ [`AtomKind`] ↔ label chain is
    /// rustc-enforced end-to-end. THEORY.md §II.1 invariant 2 — free
    /// middle; the outer-[`Atom`] diagnostic-label projection now binds
    /// at ONE site on the outer-`Atom` algebra, composing through the
    /// pre-existing marker-level label projection ([`AtomKind::label`])
    /// rather than duplicating the six-arm match. THEORY.md §VI.1 —
    /// generation over composition; the outer-`Atom` label projection is
    /// the missing algebra layer between the outer [`Atom`] value-carrier
    /// and the pre-existing [`AtomKind`] marker-level label projection —
    /// the three pre-existing typed layers ([`Atom`] → [`AtomKind`] →
    /// [`crate::error::SexpShape`] → `&'static str`) become a full
    /// four-layer typed composition through ONE new named projection on
    /// the outer value-carrier.
    ///
    /// Frontier inspiration: MLIR's `mlir::Attribute::getAbstractAttribute()
    /// .getName()` typed projection composed with the attribute-kind's
    /// typed string identity — narrowing an attribute-carrier value
    /// through its typed kind identity yields the canonical diagnostic
    /// string identity in ONE typed composition on the outer attribute
    /// algebra. Translated through the substrate's outer-[`Atom`]
    /// value-carrier algebra, `atom.kind().label()` closes the (outer
    /// value, canonical diagnostic label) pairing at ONE typed projection
    /// on the value-carrier algebra composed through the marker-level
    /// diagnostic-label face. Racket's `(syntax-kind stx)` composed with
    /// `(kind-label kind)` on the datum-kind taxonomy — the typed
    /// diagnostic label emerges from a two-hop composition on the outer
    /// datum-carrier through the typed kind identity. `Atom::label` is
    /// the Rust-typed peer on the closed-set outer-[`Atom`] algebra with
    /// [`AtomKind`] standing in for Racket's datum-kind taxonomy.
    #[must_use]
    pub fn label(&self) -> &'static str {
        self.kind().label()
    }

    /// Project the atomic value into its outer-shape [`SexpShape`]
    /// variant — `Symbol(_) → SexpShape::Symbol`,
    /// `Keyword(_) → SexpShape::Keyword`, `Str(_) → SexpShape::String`,
    /// `Int(_) → SexpShape::Int`, `Float(_) → SexpShape::Float`,
    /// `Bool(_) → SexpShape::Bool`. The outer-value peer of
    /// [`AtomKind::sexp_shape`] one algebra layer down and of
    /// [`Sexp::shape`] one algebra layer up. Body composes through
    /// `self.kind().sexp_shape()` — routing through [`Self::kind`]
    /// (the typed 6-arm outer-value → marker projection) then
    /// [`AtomKind::sexp_shape`] (the canonical 6-of-12 atomic-payload
    /// carving of [`SexpShape`]) so the (Atom variant, SexpShape
    /// variant) pairing lives at ONE canonical site
    /// ([`AtomKind::sexp_shape`]'s six match arms in `ast.rs`) rather
    /// than at six byte-identical inline arms across consumers.
    ///
    /// Same composition-through-carving-marker posture as [`Self::label`]
    /// (`self.kind().label()`) one vocabulary axis over on the
    /// outer-`Atom` algebra: [`Self::label`] closes the diagnostic-label
    /// axis, this method closes the outer-shape-projection axis, and
    /// both compose through the SAME typed marker layer
    /// ([`Self::kind`] into [`AtomKind`]) into the outer-shape's
    /// per-axis canonical site. The two methods now paint the
    /// outer-`Atom` value with typed projections onto BOTH the
    /// diagnostic-label vocabulary AND the outer-shape closed-set —
    /// the pair mirrors how [`Sexp::type_name`] and [`Sexp::shape`]
    /// paint the outer-`Sexp` value one algebra layer up.
    ///
    /// Composition law: `atom.sexp_shape() == atom.kind().sexp_shape()`
    /// for every `atom: &Atom`. Pinned by
    /// `atom_sexp_shape_composes_through_kind_sexp_shape_for_every_variant`
    /// across a representative payload sweep (including NaN via
    /// `f64::to_bits` round-trip on the Float arm, matching
    /// [`Hash for Atom`]'s posture; both empty and non-empty
    /// String/Symbol/Keyword arms; `i64::{MIN, MAX}` on the Int arm;
    /// both Bool arms). Sibling of
    /// `atom_label_composes_through_kind_label_for_every_variant` one
    /// vocabulary axis over.
    ///
    /// Cross-algebra agreement law: for every `atom: &Atom`,
    /// `atom.sexp_shape() == Sexp::Atom(atom.clone()).shape()`. The
    /// outer-`Atom` shape projection routes into the SAME canonical
    /// site the outer-`Sexp` [`Sexp::shape`] projection lands on for
    /// every atomic-payload arm — pinned by
    /// `atom_sexp_shape_agrees_with_sexp_shape_at_every_atom_arm` via
    /// byte-equality on the `SexpShape` variant across all six atomic
    /// arms. Sibling of
    /// `atom_label_agrees_with_sexp_type_name_at_every_atom_arm` one
    /// vocabulary axis over.
    ///
    /// Round-trip through the outer-shape's soft-projection sibling:
    /// `atom.sexp_shape().as_atom_kind() == Some(atom.kind())` for
    /// every `atom: &Atom` — the typed embed `Atom → AtomKind →
    /// SexpShape` inverts through the soft-projection retraction
    /// `SexpShape → AtomKind` exactly on the 6-of-12 atomic-payload
    /// image. Pinned by
    /// `atom_sexp_shape_round_trips_through_sexp_shape_as_atom_kind`.
    ///
    /// The `SexpShape` return type (owned; [`SexpShape`] is not `Copy`
    /// because its `Unknown(String)` arm carries a `String`) is the
    /// outer-shape closed set; consumers that want the diagnostic
    /// label render string compose `atom.sexp_shape().label()`, and
    /// that composition IS `atom.label()` byte-for-byte by the
    /// composition-through-carving-marker posture the two methods
    /// share.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the (outer
    /// `Atom` variant, `SexpShape` variant) pairing becomes a TYPE
    /// projection on the outermost atomic value-carrier algebra
    /// composed through the pre-existing marker-level projection,
    /// rather than at parallel inline match arms each future consumer
    /// of the outer-shape from an outer-`Atom` value has to re-derive.
    /// THEORY.md §II.1 invariant 2 — free middle; the outer-`Atom`
    /// outer-shape algebra now closes over THREE typed layers (outer
    /// `Atom` → [`AtomKind`] → [`SexpShape`]) with rustc-enforced
    /// consistency across each — a regression that drifts ONE layer's
    /// shape mapping from the others cannot reach the substrate's
    /// runtime typed-witness surface, `LispError::TypeMismatch.got`
    /// slot, or [`SexpWitness::shape`] projection. THEORY.md §VI.1 —
    /// generation over composition; the outer-value projection is the
    /// missing algebra layer between the outer `Atom` and the
    /// pre-existing marker-level shape projection — the two
    /// pre-existing typed layers become a full THREE-layer typed
    /// composition through ONE new named projection.
    ///
    /// Frontier inspiration: MLIR's `mlir::Attribute::getType()`
    /// typed projection composed with the attribute-kind's typed
    /// outer-type identity — narrowing an attribute-carrier value
    /// through its typed kind identity yields the outer-type identity
    /// in ONE typed composition on the outer attribute algebra.
    /// Translated through the substrate's outer-`Atom` value-carrier
    /// algebra, `atom.kind().sexp_shape()` closes the (outer value,
    /// outer-shape) pairing at ONE typed projection on the value-
    /// carrier algebra composed through the marker-level
    /// outer-shape face.
    #[must_use]
    pub fn sexp_shape(&self) -> SexpShape {
        self.kind().sexp_shape()
    }

    /// Stable, per-variant byte discriminator that paired with the
    /// recursive payload hash builds the substrate's [`Hash for Atom`]
    /// projection — `0u8` for [`Self::Symbol`], `1u8` for
    /// [`Self::Keyword`], `2u8` for [`Self::Str`], `3u8` for
    /// [`Self::Int`], `4u8` for [`Self::Float`], `5u8` for
    /// [`Self::Bool`]. The outer-value peer on the [`Atom`] algebra of
    /// [`AtomKind::hash_discriminator`] (the marker-level cache-key byte
    /// projection on the closed-set atomic-kind algebra), sibling of
    /// [`Self::label`] and [`Self::sexp_shape`] one vocabulary axis over
    /// on the outer-`Atom` algebra. Body composes through
    /// `self.kind().hash_discriminator()` — routing through [`Self::kind`]
    /// (the typed 6-arm outer-value → marker projection) then
    /// [`AtomKind::hash_discriminator`] (the canonical 6-arm cache-key
    /// byte projection) so the (Atom variant, byte) pairing lives at
    /// ONE canonical site ([`AtomKind::hash_discriminator`]'s six match
    /// arms) rather than at six inline `<N>u8.hash(h)` arms at
    /// [`Hash for Atom`]'s callsite.
    ///
    /// Composition law: `atom.hash_discriminator() ==
    /// atom.kind().hash_discriminator()` for every `atom: &Atom`. Pinned
    /// by `atom_hash_discriminator_composes_through_kind_hash_discriminator_for_every_variant`
    /// across a representative payload sweep (including NaN via
    /// `f64::to_bits` round-trip on the Float arm, matching
    /// [`Hash for Atom`]'s posture; both empty and non-empty
    /// String/Symbol/Keyword arms; `i64::{MIN, MAX}` on the Int arm;
    /// both Bool arms). Sibling of
    /// `atom_label_composes_through_kind_label_for_every_variant` and
    /// `atom_sexp_shape_composes_through_kind_sexp_shape_for_every_variant`
    /// one vocabulary axis over.
    ///
    /// Routing-identity law binding it to [`Hash for Atom`]'s post-lift
    /// body: for every `atom: &Atom`, hashing via the impl produces
    /// byte-identical output to a hand-driven
    /// `atom.hash_discriminator().hash(h); <inner-payload-hash>`
    /// sequence. Pinned by
    /// `hash_for_atom_routes_atom_discriminator_through_atom_hash_discriminator`.
    /// Sibling posture to
    /// `hash_for_sexp_routes_outer_discriminator_through_sexp_hash_discriminator`
    /// one algebra layer up — the two routing pins jointly enforce the
    /// outer-value Hash bodies at BOTH algebras stay structurally
    /// parallel (`self.hash_discriminator().hash(h); <inner>`).
    ///
    /// `pub(crate)` because the byte-discriminator surface is an
    /// implementation detail of the substrate's [`Hash for Atom`]
    /// cache-key contract; exposing it publicly would leak the cache-key
    /// shape through the API without enabling any external consumer the
    /// public projections ([`Self::kind`], [`Self::label`],
    /// [`Self::sexp_shape`]) don't already serve. Same posture as
    /// [`AtomKind::hash_discriminator`] one algebra layer down and
    /// [`crate::ast::Sexp::hash_discriminator`] one algebra layer up.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the (outer
    /// `Atom` variant, cache-key byte) pairing becomes a TYPE projection
    /// on the outermost atomic value-carrier algebra composed through the
    /// pre-existing marker-level projection, rather than a two-hop
    /// composition at the [`Hash for Atom`] callsite. THEORY.md §II.1
    /// invariant 2 — free middle; the outer-`Atom` cache-key algebra now
    /// closes over THREE typed layers (outer `Atom` → [`AtomKind`] → byte)
    /// with rustc-enforced consistency across each — a regression that
    /// drifts the [`Hash for Atom`] callsite's byte routing from the
    /// canonical [`AtomKind::hash_discriminator`] site cannot reach the
    /// substrate's expansion-cache runtime. THEORY.md §VI.1 — generation
    /// over composition; the outer-value byte projection is the missing
    /// algebra layer between the outer `Atom` and the pre-existing
    /// marker-level byte projection — the two pre-existing typed layers
    /// become a full THREE-layer typed composition through ONE new named
    /// projection on the outer value-carrier, closing the (label,
    /// sexp_shape, hash_discriminator) trio on the outer-`Atom` algebra.
    ///
    /// Frontier inspiration: MLIR's
    /// `mlir::Attribute::getAsOpaquePointer()` typed projection composed
    /// with the attribute-kind's stable identifier — narrowing an
    /// attribute-carrier value through its typed kind identity yields the
    /// canonical cache-key identity in ONE typed composition on the outer
    /// attribute algebra. Translated through the substrate's
    /// outer-[`Atom`] value-carrier algebra,
    /// `atom.kind().hash_discriminator()` closes the (outer value, byte
    /// cache-key discriminator) pairing at ONE typed projection on the
    /// value-carrier algebra composed through the marker-level cache-key
    /// face. Racket's `(datum-hash-key datum)` composed with
    /// `(kind-hash-tag kind)` on the datum-kind taxonomy — the byte
    /// cache-key identity emerges from a two-hop composition on the
    /// outer datum-carrier through the typed kind identity;
    /// `Atom::hash_discriminator` is the Rust-typed peer on the
    /// closed-set outer-[`Atom`] algebra with [`AtomKind`] standing in
    /// for Racket's datum-kind taxonomy.
    #[must_use]
    pub(crate) fn hash_discriminator(&self) -> u8 {
        self.kind().hash_discriminator()
    }

    /// Project the atomic payload to its canonical [`serde_json::Value`]
    /// rendering — the typed-algebra peer of [`fmt::Display for Atom`] at
    /// the JSON-projection boundary. Lifts six inline atom arms inside
    /// [`crate::domain::sexp_to_json`]'s outer match (one
    /// `Sexp::Atom(Atom::<variant>(payload)) => JValue::<…>(…)` arm
    /// per [`AtomKind`] variant) onto ONE typed-algebra method that
    /// every consumer routes through. Sibling-shape lift to the prior
    /// `Display for Atom` (the canonical-string rendering surface),
    /// `Hash for Atom` (the cache-key bytes surface via
    /// [`AtomKind::hash_discriminator`]), and the upcoming
    /// `Atom::to_iac_forge_sexpr` (the canonical-SExpr rendering
    /// surface, feature-gated `iac-forge`) — every per-`Atom`-variant
    /// projection now binds at ONE method on the closed-set algebra
    /// rather than at six inline arms inside its consumer.
    ///
    /// Mapping (preserves the byte-identical pre-lift behavior at the
    /// `sexp_to_json` callsite):
    ///   * [`Self::Symbol`] payload `s` → [`serde_json::Value::String`] of
    ///     `s` cloned (Symbols are enum discriminants — the JSON
    ///     deserializer reads them as the string-form variant tag).
    ///   * [`Self::Keyword`] payload `s` → [`serde_json::Value::String`]
    ///     of `":{s}"` (Keywords prefix with `:` in their canonical
    ///     wire-form; `json_to_sexp`'s inverse strips the prefix).
    ///   * [`Self::Str`] payload `s` → [`serde_json::Value::String`] of
    ///     `s` cloned.
    ///   * [`Self::Int`] payload `n` → [`serde_json::Value::Number`] of
    ///     `n` (lossless via `serde_json::Number::from(i64)`).
    ///   * [`Self::Float`] payload `n` → [`serde_json::Value::Number`] of
    ///     `n` IFF `n` is finite (NaN / ±∞ collapse to
    ///     [`serde_json::Value::Null`]; this is JSON's structural
    ///     inexpressibility of those f64 values, NOT a substrate
    ///     choice). The NaN/∞→Null branch is pinned at one test below
    ///     (`atom_to_json_float_nan_and_infinity_collapse_to_null`).
    ///   * [`Self::Bool`] payload `b` → [`serde_json::Value::Bool`] of
    ///     `b`.
    ///
    /// Bidirectional contract anchored by tests in this module:
    ///   * `atom_to_json_projects_each_variant_to_canonical_json_value`
    ///     — sweeps a representative atom of each [`AtomKind`] variant
    ///     and pins each variant's canonical JValue mapping
    ///     byte-for-byte against the pre-lift inline rule, so a future
    ///     regression that drifts ONE arm (e.g. swaps `Symbol`'s
    ///     mapping to a Number, or drops `Keyword`'s `:` prefix) fails
    ///     loudly.
    ///   * `atom_to_json_float_nan_and_infinity_collapse_to_null`
    ///     — pins the JSON-structural inexpressibility branch at the
    ///     atom layer directly, so a future Atom-Display-style refactor
    ///     that bypasses [`serde_json::Number::from_f64`] (e.g. tries
    ///     to emit `NaN` as the string `"NaN"`) surfaces at the
    ///     typed-algebra boundary without requiring a Sexp wrap.
    ///   * `sexp_to_json_atom_arms_route_through_atom_to_json` (in
    ///     [`crate::domain::tests`]) — pins the lifted boundary:
    ///     `sexp_to_json(&Sexp::Atom(a.clone())) == Ok(a.to_json())`
    ///     for every atomic payload variant. Catches a future drift
    ///     where one surface's per-variant body changes without the
    ///     other.
    ///
    /// Theory anchor: THEORY.md §VI.1 — generation over composition;
    /// the (Atom variant, canonical JValue rendering) pair lived inline
    /// at the `sexp_to_json` site as six byte-identical arms. The lift
    /// retires the per-site fan-out onto ONE method on the `Atom`
    /// algebra. THEORY.md §II.1 invariant 2 — free middle; the typed-
    /// exit JSON projection, the Display-surface rendering, the
    /// diagnostic surface, and any future canonical-form surface
    /// (e.g. `Atom::to_iac_forge_sexpr`) all route through ONE
    /// per-variant projection family rather than per-callsite
    /// re-derivation. THEORY.md §V.1 — knowable platform; a future
    /// seventh atomic kind (e.g. `Char` for `#\x` reader syntax) lands
    /// at one [`AtomKind::ALL`] entry plus one arm here plus one arm
    /// per sibling projection — exhaustively checked by the compiler,
    /// not by per-consumer convention.
    ///
    /// Frontier inspiration: MLIR's `mlir::AsmPrinter::printAttribute`
    /// — the typed-IR attribute printer dispatches on the closed-set
    /// `AttributeKind` so every printer body for a kind lives at ONE
    /// implementation site; `Atom::to_json` is the unstructured-Rust
    /// peer on the `Atom` algebra for the JSON canonical-form surface
    /// (where `Display for Atom` is the Lisp-canonical-form peer and
    /// `From<&Sexp> for iac_forge::SExpr` is the canonical-attestation-
    /// form peer). Racket's `(syntax->datum stx)` then a serializer
    /// over the datum prim — `to_json` is the substrate's serializer
    /// at the atomic-payload layer, with the closed-set `AtomKind`
    /// standing in for Racket's datum-prim taxonomy.
    #[must_use]
    pub fn to_json(&self) -> serde_json::Value {
        match self {
            Self::Symbol(s) => serde_json::Value::String(s.clone()),
            // Keyword arm routes through the typed
            // [`Self::keyword_qualified`] projection on the atomic-
            // payload canonical-rendering axis — the ONE composition
            // of [`Self::KEYWORD_MARKER`] with a bare keyword name on
            // the [`Atom`] algebra, shared with
            // `Atom::to_iac_forge_sexpr` (removed)'s Keyword arm and pinned
            // byte-identical to [`fmt::Display for Atom`]'s Keyword
            // arm. Pre-lift each of the three sites carried its own
            // inline `format!("{}{s}", Self::KEYWORD_MARKER)`
            // composition; post-lift the composition lives at ONE
            // typed algebra projection.
            Self::Keyword(s) => serde_json::Value::String(Self::keyword_qualified(s)),
            Self::Str(s) => serde_json::Value::String(s.clone()),
            Self::Int(n) => serde_json::Value::Number((*n).into()),
            Self::Float(n) => serde_json::Number::from_f64(*n)
                .map(serde_json::Value::Number)
                .unwrap_or(serde_json::Value::Null),
            Self::Bool(b) => serde_json::Value::Bool(*b),
        }
    }

    /// Inverse of [`Self::to_json`] restricted to the JSON `Number`
    /// discriminator — the ONE typed inverse projection on the closed-set
    /// [`Atom`] algebra that names the (`serde_json::Number` →
    /// [`Self::Int`] / [`Self::Float`]) bifurcation. Lifts the pre-lift
    /// inline three-arm cascade inside [`crate::ast::Sexp::from_json`]'s
    /// `serde_json::Value::Number(n)` outer-match arm — first
    /// `n.as_i64()?` sink to [`Self::Int`] then `n.as_f64()?` sink to
    /// [`Self::Float`] then a `Self::Int(0)` typed floor for the
    /// structural-impossibility residual — onto ONE typed projection on
    /// the [`Atom`] algebra so the paired FORWARD ([`Self::to_json`]'s
    /// [`Self::Int`] / [`Self::Float`] arms) and INVERSE (this method)
    /// numeric-axis projections live at ONE algebra layer.
    ///
    /// Mapping (byte-identical to the pre-lift cascade in
    /// [`crate::ast::Sexp::from_json`]):
    ///
    /// | `serde_json::Number` shape         | result             |
    /// | ---------------------------------- | ------------------ |
    /// | `n.as_i64() == Some(i)`            | [`Self::Int`]`(i)` |
    /// | `n.as_i64() == None`, `.as_f64() == Some(f)` | [`Self::Float`]`(f)` |
    /// | `n.as_i64() == None`, `.as_f64() == None`    | [`Self::Int`]`(0)` — typed floor |
    ///
    /// Every `serde_json::Number` today is either i64-fitting,
    /// u64-fitting (projected through f64), or f64-fitting — the
    /// `Int(0)` residual arm is a static-invariant statement that
    /// `serde_json::Number`'s closed-set discriminator excludes the
    /// "neither i64 nor f64" case in practice; the typed floor stays
    /// explicit so a future `serde_json` extension does NOT silently
    /// misroute through an unreachable-panic. The `Self::int(0)`
    /// composition in the pre-lift code equalled `Self::Atom(Atom::Int(0))`
    /// via the `Sexp::int` sugar; post-lift the [`Atom`] algebra owns
    /// the typed floor at the atomic layer directly.
    ///
    /// Round-trip laws (paired with [`Self::to_json`]'s numeric arms):
    ///
    /// * For every `i: i64`, `Atom::from_json_number(&i.into()) ==
    ///   Atom::Int(i)` — the [`Self::Int`] → `JValue::Number` →
    ///   [`Self::Int`] round-trip is byte-identical.
    /// * For every finite non-integer-valued `f: f64`,
    ///   `Atom::from_json_number(&serde_json::Number::from_f64(f)
    ///   .unwrap()) == Atom::Float(f)` — the [`Self::Float`] →
    ///   `JValue::Number` → [`Self::Float`] round-trip is byte-identical
    ///   for `f64` values that don't overlap the i64-fitting subset of
    ///   [`serde_json::Number`]'s discriminator (i.e. non-integer-valued
    ///   finite floats; integer-valued floats round-trip through the
    ///   [`Self::Int`] arm by `as_i64`'s eager check).
    /// * Non-finite floats ([`f64::NAN`], [`f64::INFINITY`],
    ///   [`f64::NEG_INFINITY`]) collapse to [`serde_json::Value::Null`]
    ///   in [`Self::to_json`] — they NEVER produce a [`serde_json::Number`]
    ///   value, so the round-trip law does not apply to them. This
    ///   asymmetry is JSON's structural inexpressibility of non-finite
    ///   floats (pinned at
    ///   `atom_to_json_float_nan_and_infinity_collapse_to_null`), not a
    ///   substrate choice.
    ///
    /// ONE consumer entrypoint the substrate binds against: the outer
    /// [`crate::ast::Sexp::from_json`]'s `serde_json::Value::Number(n)`
    /// arm was pre-lift a hand-rolled three-branch cascade
    /// (`if let Some(i) = n.as_i64() { Self::int(i) } else if let
    /// Some(f) = n.as_f64() { Self::float(f) } else { Self::int(0) }`);
    /// post-lift the outer arm collapses to
    /// `Self::Atom(Atom::from_json_number(n))` — the ONE typed inverse
    /// on the [`Atom`] algebra owns the numeric-axis bifurcation, the
    /// outer arm delegates. A regression that drifts the outer arm
    /// (e.g. re-inlines the bifurcation and swaps the `as_i64`/`as_f64`
    /// order so `42.0` sinks to [`Self::Float`] instead of
    /// [`Self::Int`]) becomes structurally unreachable — there is
    /// exactly ONE numeric decode both directions of the round-trip
    /// consume.
    ///
    /// Sibling-lift posture: this method mirrors [`Self::from_lexeme`]
    /// on the typed-entry classification axis — that method decodes a
    /// bare-atom lexeme (`&str`) into the six-way [`Atom`] taxonomy;
    /// THIS method decodes a JSON `Number` into the two-way (
    /// [`Self::Int`] / [`Self::Float`]) numeric subtaxonomy on the SAME
    /// algebra. Together with the seven typed-EXIT projections on
    /// [`Atom`] ([`fmt::Display for Atom`], [`Self::to_json`],
    /// `Atom::to_iac_forge_sexpr` (removed), [`Self::label`],
    /// [`Self::sexp_shape`], [`Self::hash_discriminator`],
    /// [`Self::bool_literal`]) and the two typed-ENTRY projections on
    /// [`Atom`] ([`Self::from_lexeme`], THIS method) the algebra's
    /// canonical-form bidirectional sweep is complete across every
    /// production-site rendering + parsing surface — every consumer's
    /// (`Atom` variant, canonical rendering) OR (canonical source,
    /// `Atom` variant) pairing binds at ONE method per direction per
    /// surface on the closed-set algebra rather than at inline arms
    /// scattered across per-consumer sites.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 1 — typed entry; the
    /// (JSON `Number` → typed [`Atom`] numeric variant) projection IS
    /// the typed-entry gate on the JSON numeric axis. Placing the
    /// paired forward (`Atom::to_json`'s [`Self::Int`] / [`Self::Float`]
    /// arms) AND inverse (THIS method) on the [`Atom`] algebra closes
    /// the round-trip closure at ONE algebra layer — future numeric
    /// taxonomy extensions (e.g. `u64`-fitting arm for the
    /// `serde-preserve-order` feature's `arbitrary_precision` mode, a
    /// [`Self::Bigint`] variant for arbitrary-precision integers, a
    /// [`Self::Rational`] variant for [`num_rational::Rational64`])
    /// extend the algebra ONCE at [`Self::to_json`]'s match AND ONCE at
    /// this method's cascade — both edits land on the SAME algebra
    /// rather than across the `Atom` module AND the `Sexp` module
    /// boundary. THEORY.md §V.1 — knowable platform; the numeric
    /// inverse projection becomes a NAMED primitive on the substrate's
    /// [`Atom`] algebra rather than an inline three-arm cascade at the
    /// `Sexp::from_json` consumer. THEORY.md §II.1 invariant 5 —
    /// composition preserves proofs; the round-trip law
    /// `Atom::from_json_number(&Atom::Int(n).to_json_as_number()) ==
    /// Atom::Int(n)` (pinned at
    /// `atom_from_json_number_round_trips_atom_to_json_int_arm`) is a
    /// coherence proof BETWEEN the paired projections on ONE algebra —
    /// a regression that drifts either side surfaces at the pin
    /// rather than as a silent Sexp ↔ JSON round-trip drift.
    ///
    /// Frontier inspiration: MLIR's `mlir::parseAttribute(str, ctx)` —
    /// the typed-IR parser inverse of `printAttribute` lives on the
    /// SAME `Attribute` algebra as its printer dual; the substrate's
    /// [`Self::from_json_number`] is the unstructured-Rust peer on the
    /// [`Atom`] algebra for the JSON-numeric canonical-form inverse,
    /// paired with [`Self::to_json`]'s numeric arms as the closed
    /// numeric-axis round-trip. Racket's
    /// `(json->racket (racket->json v))` numeric identity — the
    /// round-trip law that a JSON-projected numeric datum recovers to
    /// its source Racket numeric primitive; THIS method's round-trip
    /// pins are the Rust-typed peer on the [`Atom`] algebra with the
    /// closed-set numeric taxonomy ([`Self::Int`] / [`Self::Float`])
    /// standing in for Racket's numeric tower.
    #[must_use]
    pub fn from_json_number(n: &serde_json::Number) -> Self {
        if let Some(i) = n.as_i64() {
            Self::Int(i)
        } else if let Some(f) = n.as_f64() {
            Self::Float(f)
        } else {
            Self::Int(0)
        }
    }

    // REMOVED (consolidation phase 2 step 8): `Atom::to_iac_forge_sexpr`
    // and the `crate::interop` module it mirrored. Both were gated on a
    // `iac-forge` Cargo feature this crate never declared, against an
    // `iac_forge` dependency it never had — unconditionally dead, and
    // uncompilable had the gate ever opened. Re-introducing the bridge
    // needs a crates.io-published `iac-forge` first; see
    // TATARA-LISP-CONSOLIDATION.md open question 7.
    //
    // NOT part of this deletion: the `iac_forge_tag` / `IAC_FORGE_TAGS`
    // / `from_iac_forge_tag` family on `QuoteForm`, `SexpShape`,
    // `UnquoteForm` and `Sexp`. Those are pure `&'static str` closed-set
    // projections with no dependency on the `iac-forge` crate; they stay
    // live and tested.

    /// Classify a bare reader-token lexeme into its typed [`Atom`]
    /// variant — the typed-ENTRY mirror of the three typed-EXIT
    /// projections on the [`Atom`] algebra ([`fmt::Display for Atom`],
    /// [`Self::to_json`], `Atom::to_iac_forge_sexpr` (removed)). Lifts the
    /// five-statement classification cascade that lived inline at the
    /// reader's private `atom_from_str` helper onto ONE typed-algebra
    /// method on the closed-set [`Atom`] algebra; the reader's
    /// `Token::Atom(s)` arm collapses to `Sexp::Atom(Atom::from_lexeme(&s))`.
    /// Completes the bidirectional sweep across the four production-site
    /// per-`Atom`-variant projection shapes (typed-exit Display, JSON,
    /// iac-forge canonical attestation, AND now typed-entry
    /// classification) onto the algebra.
    ///
    /// Classification rule (byte-identical to the pre-lift reader
    /// `atom_from_str` cascade):
    ///   1. `"#t"`/`"#f"` → [`Self::Bool`] — the Scheme bool spellings;
    ///      bare `true`/`false` re-read as [`Self::Symbol`] (the
    ///      CLAUDE.md "Lisp bools" warning — every `:values-overlay`
    ///      payload depends on this for `Value::Bool` round-trip).
    ///   2. `:foo` (leading `:`) → [`Self::Keyword`] — strips the `:`
    ///      so the inverse [`fmt::Display`] rule (`Keyword(s) →
    ///      ":{s}"`) round-trips.
    ///   3. `i64::from_str` succeeds → [`Self::Int`] — load-bearing
    ///      ORDERING: tried BEFORE `f64` so `"1"` classifies as
    ///      [`Self::Int`]`(1)`, NOT [`Self::Float`]`(1.0)`. Typed-int-
    ///      vs-typed-float distinction at the Display→read boundary
    ///      is the dual of `fmt_float`'s `.0`-suffix discipline.
    ///   4. `f64::from_str` succeeds → [`Self::Float`].
    ///   5. Default → [`Self::Symbol`].
    ///
    /// Composition laws (pinned by tests below):
    ///   * `Atom::from_lexeme(&a.to_string()) == a` for every variant
    ///     EXCEPT [`Self::Str`] (Display renders Str with quote marks
    ///     — strings take the reader's `"`-quoted tokenizer branch,
    ///     NOT the bare-atom branch).
    ///   * `read(s)` for every canonical bare-atom source lexeme
    ///     equals `vec![Sexp::Atom(Atom::from_lexeme(s))]` (pinned by
    ///     `reader_atom_token_arm_routes_through_atom_from_lexeme_for_
    ///     every_kind` in [`crate::reader::tests`]).
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 1 — typed entry;
    /// `atom_from_str` was the typed-entry gate as a free function in
    /// `reader.rs`, outside the typed `Atom` algebra. Naming it on the
    /// algebra brings the typed-entry side INTO the same closed-set
    /// match family the typed-exit projections live on, so a future
    /// seventh atomic kind (e.g. `Char` for `#\x` reader syntax) lands
    /// at ONE [`AtomKind::ALL`] entry plus ONE arm here plus ONE arm
    /// per typed-exit projection — exhaustively checked by rustc
    /// across all FOUR per-variant projection families. THEORY.md
    /// §II.1 invariant 2 — free middle; FOUR consumers (typed-entry
    /// classification, Display rendering, JSON projection, canonical-
    /// attestation-form projection) now route through ONE
    /// per-`Atom`-variant projection family on the closed-set algebra.
    /// THEORY.md §VI.1 — generation over composition; this lift
    /// completes the bidirectional sweep across the four production
    /// surfaces the prior runs in this series named.
    ///
    /// Frontier inspiration: Racket's `(read-syntax …)` dispatches a
    /// bare-atom lexeme through a closed-set classifier keyed on
    /// prefix + parse-as-numeric cascade; `Atom::from_lexeme` is the
    /// substrate's typed-Rust peer, with [`AtomKind`] standing in for
    /// Racket's datum-prim taxonomy. MLIR's
    /// `mlir::AsmParser::parseAttribute` dispatches on the closed-set
    /// `AttributeKind` so every parser body for a kind lives at ONE
    /// implementation site; `Atom::from_lexeme` is the
    /// unstructured-Rust peer on the [`Atom`] algebra for the
    /// typed-entry classification surface.
    #[must_use]
    pub fn from_lexeme(s: &str) -> Self {
        if s == Self::bool_literal(true) {
            return Self::Bool(true);
        }
        if s == Self::bool_literal(false) {
            return Self::Bool(false);
        }
        if let Some(rest) = s.strip_prefix(Self::KEYWORD_MARKER) {
            return Self::Keyword(rest.to_owned());
        }
        if let Ok(n) = s.parse::<i64>() {
            return Self::Int(n);
        }
        if let Ok(n) = s.parse::<f64>() {
            return Self::Float(n);
        }
        Self::Symbol(s.to_owned())
    }

    /// Soft projection onto the [`Self::Symbol`] payload — `Some(&str)`
    /// iff this is a [`Self::Symbol`] variant, `None` for every other
    /// atomic kind (`Keyword`, `Str`, `Int`, `Float`, `Bool`).
    ///
    /// FIRST of the six per-variant soft-projection methods on the typed
    /// [`Atom`] algebra — the typed-EXIT *soft*-projection peer of the
    /// typed-EXIT canonical-form projections ([`fmt::Display for Atom`],
    /// [`Self::to_json`], `Atom::to_iac_forge_sexpr` (removed)) and the typed-ENTRY
    /// classifier ([`Self::from_lexeme`]). Where the canonical-form trio
    /// projects the atomic payload to a *rendered* canonical surface
    /// (string / JSON / iac-forge SExpr) and the classifier projects a
    /// lexeme to the typed `Atom`, this method projects the typed `Atom`
    /// to its inner payload — the soft-decomposition face of the closed
    /// set, completing the algebra surface across BOTH bidirectional axes
    /// (canonical-form rendering + classification on the typed-ENTRY/
    /// typed-EXIT axis; soft decomposition on the typed-EXIT side at the
    /// payload axis).
    ///
    /// Sibling soft-projection peer of [`Sexp::as_quote_form`]: where
    /// `as_quote_form` soft-decomposes the four homoiconic prefix
    /// wrappers into `Option<(QuoteForm, &Sexp)>`, this method (and its
    /// five `as_*` siblings on [`Atom`]) soft-decompose the six atomic
    /// payloads into `Option<&str>` / `Option<i64>` / `Option<f64>` /
    /// `Option<bool>` — there is no inner-sexp body to surface, so the
    /// projection's return type is just the payload. The
    /// `Sexp::as_symbol` consumer at the `Sexp` algebra layer composes
    /// this projection with [`Sexp::as_atom`] (the structural lift to
    /// the inner [`Atom`]) — `Sexp::as_symbol(self) ==
    /// self.as_atom().and_then(Atom::as_symbol)` — so the per-`Atom`-
    /// variant soft-projection binds at ONE method on the typed algebra
    /// rather than at six inline `Self::Atom(Atom::X(s)) => Some(s)` arms
    /// inside the `Sexp` consumer.
    ///
    /// Lifts the inline `Self::Atom(Atom::Symbol(s)) => Some(s)` arm at
    /// [`Sexp::as_symbol`]'s match body onto ONE typed-algebra projection
    /// the `Sexp` consumer routes through via the structural lift
    /// [`Sexp::as_atom`]. Sibling-shape lift to the typed-EXIT
    /// canonical-form projections (`Display for Atom`, `Atom::to_json`,
    /// `Atom::to_iac_forge_sexpr`) and the typed-ENTRY classifier
    /// (`Atom::from_lexeme`) — every per-`Atom`-variant projection
    /// across both the rendering surfaces AND the soft-decomposition
    /// surface now binds at ONE method on the closed-set algebra rather
    /// than at inline arms inside its consumer.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 2 — free middle; the
    /// (Atom variant, downstream-consumer-payload) pairing now binds at
    /// ONE typed projection per consumer surface (six canonical-form
    /// surfaces — `Display`, JSON, iac-forge, plus the soft-projection
    /// FAMILY this method opens), regardless of which consumer reaches
    /// in. THEORY.md §VI.1 — generation over composition; the six inline
    /// `Self::Atom(Atom::X(s)) => Some(_)` arms at `Sexp::as_X` sites
    /// (well past the ≥2 PRIME-DIRECTIVE trigger once the structural
    /// shape is named) collapse onto the closed-set `Atom` algebra so a
    /// future seventh atomic kind (e.g. `Char` for `#\x` reader syntax,
    /// `Bigint` for arbitrary-precision integers) extends `Atom::ALL` +
    /// the per-variant soft-projection method ONCE and rustc enforces
    /// matching across every consumer through the closed-set match.
    /// THEORY.md §V.1 — knowable platform; the (Atom variant, payload)
    /// pairing becomes a TYPE projection on the substrate algebra
    /// rather than six inline arms at the `Sexp` consumer. A typo or
    /// swap at the soft-projection site is no longer a runtime drift
    /// but a compile error against the typed projection.
    ///
    /// Frontier inspiration: Racket's `(symbol? v)` / `(symbol->string
    /// v)` pair — the typed-predicate + typed-projection pair at the
    /// atomic-payload layer; this method (and its five `as_*` siblings)
    /// is the substrate's typed soft-projection peer on the closed-set
    /// `Atom` algebra, with `Option<&str>` standing in for the
    /// predicate-AND-projection pair Racket carries as two functions.
    /// MLIR's `mlir::dyn_cast<SymbolAttribute>(attr)` — the typed-IR
    /// soft-downcast onto a closed-set attribute family; `Atom::as_symbol`
    /// is the unstructured-Rust peer on the `Atom` algebra for the
    /// soft-projection face, with the closed-set `AtomKind` standing in
    /// for MLIR's `AttributeKind` taxonomy.
    #[must_use]
    pub fn as_symbol(&self) -> Option<&str> {
        match self {
            Self::Symbol(s) => Some(s),
            _ => None,
        }
    }

    /// Soft projection onto the [`Self::Keyword`] payload — `Some(&str)`
    /// iff this is a [`Self::Keyword`] variant, `None` for every other
    /// atomic kind. The returned `&str` is the payload AFTER the `:`
    /// prefix has been stripped at the typed-ENTRY classifier
    /// boundary ([`Self::from_lexeme`] strips `:` when constructing a
    /// `Keyword`; this projection surfaces the bare identifier).
    /// SECOND of the six per-variant soft-projection methods on the
    /// typed [`Atom`] algebra — see [`Self::as_symbol`] for the
    /// algebra-level docstring.
    #[must_use]
    pub fn as_keyword(&self) -> Option<&str> {
        match self {
            Self::Keyword(s) => Some(s),
            _ => None,
        }
    }

    /// Soft projection onto the [`Self::Str`] payload — `Some(&str)` iff
    /// this is a [`Self::Str`] variant (the typed `"…"`-quoted string
    /// literal payload at the reader's [`crate::reader::Token::Str`]
    /// branch), `None` for every other atomic kind. THIRD of the six
    /// per-variant soft-projection methods — named `as_string` at the
    /// `Sexp` consumer for consumer-vocabulary continuity with the
    /// pre-lift `Sexp::as_string` projection (the typed payload variant
    /// is `Str` for `String` shortening; the consumer-facing method
    /// keeps `string` for symmetry with the `ExpectedKwargShape::String`
    /// label and the [`SexpShape::String`] outer-shape marker).
    #[must_use]
    pub fn as_string(&self) -> Option<&str> {
        match self {
            Self::Str(s) => Some(s),
            _ => None,
        }
    }

    /// Soft projection onto the [`Self::Int`] payload — `Some(i64)` iff
    /// this is a [`Self::Int`] variant, `None` for every other atomic
    /// kind. FOURTH of the six per-variant soft-projection methods.
    /// The `i64` is returned by value (the payload is `Copy`); contrast
    /// with [`Self::as_symbol`] / [`Self::as_keyword`] / [`Self::as_string`]
    /// which borrow the underlying `String` payload as `&str` because
    /// `String` is not `Copy`.
    ///
    /// Strict typed identity: this method projects `Atom::Int(n)` to
    /// `Some(n)` only. The `Sexp::as_float` consumer at the `Sexp`
    /// algebra layer widens `Int` to `Float` (`Atom::Int(n) → Some(n as
    /// f64)`) for caller convenience at the numeric-kwarg boundary; the
    /// `Atom`-level projection here stays strict so the typed-identity
    /// distinction `Int(1)` vs `Float(1.0)` (the load-bearing typed
    /// identity at the [`Self::from_lexeme`] ⇄ Display round-trip
    /// boundary, dual of [`fmt_float`]'s `.0`-suffix discipline) is
    /// preserved at the algebra layer. The widening lives at the
    /// `Sexp::as_float` consumer (`a.as_float().or_else(|| a.as_int()
    /// .map(|n| n as f64))`) where the convenience is wanted, not at
    /// the algebra-level projection where the typed identity is
    /// load-bearing.
    #[must_use]
    pub fn as_int(&self) -> Option<i64> {
        match self {
            Self::Int(n) => Some(*n),
            _ => None,
        }
    }

    /// Soft projection onto the [`Self::Float`] payload — `Some(f64)`
    /// iff this is a [`Self::Float`] variant, `None` for every other
    /// atomic kind. FIFTH of the six per-variant soft-projection
    /// methods.
    ///
    /// Strict typed identity: `Atom::Int(n)` does NOT project through
    /// this method (it stays `None`). The [`Sexp::as_float`] consumer
    /// widens `Int` to `Float` at the `Sexp` algebra layer for caller
    /// convenience; this algebra-level projection stays strict. See
    /// [`Self::as_int`]'s docstring for the typed-identity contract.
    #[must_use]
    pub fn as_float(&self) -> Option<f64> {
        match self {
            Self::Float(n) => Some(*n),
            _ => None,
        }
    }

    /// Soft projection onto the [`Self::Bool`] payload — `Some(bool)`
    /// iff this is a [`Self::Bool`] variant, `None` for every other
    /// atomic kind. SIXTH and LAST of the six per-variant soft-projection
    /// methods on the typed [`Atom`] algebra; together with the five
    /// siblings ([`Self::as_symbol`], [`Self::as_keyword`],
    /// [`Self::as_string`], [`Self::as_int`], [`Self::as_float`]) the
    /// per-`Atom`-variant soft-projection family is complete across all
    /// six closed-set arms. The CLAUDE.md-pinned `"#t"` / `"#f"` Scheme
    /// bool spellings the reader's typed-ENTRY classifier
    /// [`Self::from_lexeme`] dispatches on bind the lexeme → typed
    /// [`Self::Bool`] direction; this method binds the typed
    /// [`Self::Bool`] → payload direction at the soft-decomposition
    /// face.
    #[must_use]
    pub fn as_bool(&self) -> Option<bool> {
        match self {
            Self::Bool(b) => Some(*b),
            _ => None,
        }
    }

    /// Soft projection onto the *symbol-or-string* union — `Some(&str)` iff
    /// this is a [`Self::Symbol`] variant OR a [`Self::Str`] variant, `None`
    /// for every other atomic kind (`Keyword`, `Int`, `Float`, `Bool`).
    /// The atomic-payload peer of [`Sexp::as_symbol_or_string`] —
    /// disjunctive composition of [`Self::as_symbol`] + [`Self::as_string`]
    /// at the typed [`Atom`] algebra rather than at the [`Sexp`] consumer
    /// layer where the union previously composed two distinct
    /// [`Sexp::as_atom`] traversals.
    ///
    /// Sibling soft-projection peer of the six per-variant projections
    /// ([`Self::as_symbol`], [`Self::as_keyword`], [`Self::as_string`],
    /// [`Self::as_int`], [`Self::as_float`], [`Self::as_bool`]) — this
    /// union projection completes the soft-decomposition family on the
    /// closed-set [`Atom`] algebra by naming the (Symbol ⊎ Str) union
    /// the substrate's named-form NAME gate ([`crate::compile::split_name_slot`]
    /// via [`Sexp::as_symbol_or_string`]) keys on. Both NAME-author
    /// surfaces (`(defcompiler my-name …)` — bare symbol; `(defcompiler
    /// "my-name" …)` — quoted string) project to `Some("my-name")`
    /// through one method on the algebra.
    ///
    /// Composition law binding it to [`Sexp::as_symbol_or_string`]: for
    /// every [`Sexp`] `s`,
    /// `s.as_symbol_or_string() == s.as_atom().and_then(Atom::as_symbol_or_string)`
    /// — the same structural-lift composition pattern [`Sexp::as_symbol`]
    /// / [`Sexp::as_keyword`] / [`Sexp::as_string`] / [`Sexp::as_int`] /
    /// [`Sexp::as_bool`] route through on the six per-variant axis.
    /// Lifts the `self.as_symbol().or_else(|| self.as_string())`
    /// disjunctive composition at [`Sexp::as_symbol_or_string`]'s body
    /// (TWO `Sexp::as_atom` traversals pre-lift) onto ONE typed-algebra
    /// projection the `Sexp` consumer routes through via the structural
    /// lift [`Sexp::as_atom`] (ONE `Sexp::as_atom` traversal post-lift).
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 2 — free middle; the
    /// (Symbol ⊎ Str) union projection now binds at ONE method on the
    /// closed-set [`Atom`] algebra regardless of which consumer reaches
    /// in. THEORY.md §VI.1 — generation over composition; the
    /// disjunctive `as_symbol().or_else(|| as_string())` composition at
    /// [`Sexp::as_symbol_or_string`]'s body collapses onto a SINGLE
    /// structural lift through [`Sexp::as_atom`] + the algebra-level
    /// union projection, eliminating the double-traversal redundancy
    /// the pre-lift consumer-layer composition carried. THEORY.md §V.1
    /// — knowable platform; the (Symbol-or-Str) NAME-slot union becomes
    /// a TYPE projection on the substrate algebra rather than a
    /// disjunctive composition at every NAME-gate consumer.
    ///
    /// Frontier inspiration: Racket's `(or/c symbol? string?)`
    /// contract — a typed disjunctive predicate the consumer binds to
    /// in one place rather than re-deriving the disjunction at every
    /// callsite; [`Self::as_symbol_or_string`] is the substrate's
    /// unstructured-Rust peer with the typed projection (`Option<&str>`)
    /// surfacing the underlying payload alongside the predicate face.
    /// MLIR's `mlir::dyn_cast<StringLike>(attr)` — typed soft-downcast
    /// onto a closed-set attribute union; [`Self::as_symbol_or_string`]
    /// is the substrate's [`Atom`]-algebra peer for the
    /// (Symbol ⊎ Str) union, with `Option<&str>` standing in for MLIR's
    /// typed downcast result.
    #[must_use]
    pub fn as_symbol_or_string(&self) -> Option<&str> {
        self.as_symbol().or_else(|| self.as_string())
    }
}

/// Closed-set typed discriminator for the six [`Atom`] payload variants —
/// `Symbol(String)`, `Keyword(String)`, `Str(String)`, `Int(i64)`,
/// `Float(f64)`, `Bool(bool)` — paired with the projections every
/// per-atom-kind consumer keys on ([`Self::hash_discriminator`] for
/// [`Hash for Atom`]'s cache-key bytes, [`Self::sexp_shape`] for
/// [`crate::domain::sexp_shape`]'s atom-arm collapse, [`Self::label`]
/// for the operator-facing diagnostic vocabulary, [`Self::FromStr`]
/// for the typed-inverse decode that lets LSP / REPL / metric-aggregator
/// consumers round-trip a rendered diagnostic label back into the typed
/// discriminator).
///
/// Atomic-payload peer of [`QuoteForm`] (the four homoiconic prefix
/// wrappers — `Sexp::{Quote, Quasiquote, Unquote, UnquoteSplice}`):
/// where `QuoteForm` carves the closed set on `Sexp`'s wrapper-variant
/// axis, `AtomKind` carves the closed set on `Sexp`'s atomic-payload
/// axis. Together the two closed-set discriminators cover every reachable
/// `Sexp` outermost shape except `Nil` and `List` (the structural
/// constructors `()` and `(…)`) — every other shape is either an
/// `Atom(_)` projecting through this enum's [`Self::sexp_shape`] arm or a
/// quote-family wrapper projecting through [`QuoteForm::sexp_shape`].
/// After this lift the two enums' [`Self::sexp_shape`] arms own ALL TEN
/// of [`SexpShape`]'s twelve canonical labels through ONE typed
/// composition each rather than through per-callsite arm-pairing in
/// [`crate::domain::sexp_shape`].
///
/// Mirror at the atomic-payload boundary of the prior-run [`QuoteForm`]
/// (homoiconic-prefix-wrapper closed set, 4 variants), the cross-crate
/// `tatara-process` closed-set family
/// (`ConditionKind::ALL`, `ProcessPhase::ALL`, `ProcessSignal::ALL`,
/// `ChannelKind::ALL`, `IntentKind::ALL`, `LifetimeKind::ALL`,
/// `RequestorKind::ALL`, `ReceiptKind::ALL`, …) and this crate's own
/// [`SexpShape`] (the twelve reachable Sexp outermost shapes — the
/// SUPERSET this enum projects into via [`Self::sexp_shape`]) and
/// [`UnquoteForm`] (the two template-substitution markers) closed-set
/// lifts: those enums key their respective rejection or projection
/// variants on a typed identity carried inside the variant's data shape;
/// this enum keys the SIX [`Atom`] payload variants on a typed
/// discriminator identity threaded through ALL THREE per-atom-kind
/// dispatch sites ([`Hash for Atom`]'s six byte literals,
/// [`crate::domain::sexp_shape`]'s six atom arms, AND the
/// diagnostic-label vocabulary [`SexpShape::label`] publishes for the
/// atom subset). Adding a hypothetical seventh atomic kind (e.g. a
/// `Char` literal for `#\x` reader syntax, a `Bigint` for arbitrary-
/// precision integers, a `Symbol2` for namespaced symbols) requires
/// extending this enum, which rustc-enforces matching at every
/// projection site ([`Self::label`], [`Self::hash_discriminator`],
/// [`Self::sexp_shape`], [`Atom::kind`], the [`Hash for Atom`] inner
/// match, and the [`Self::FromStr`] sweep keyed on [`Self::ALL`]) — the
/// closed set becomes a TYPE rather than six `&'static str` / `u8`
/// / `SexpShape` literals that could drift independently across the
/// substrate's three per-atom-kind consumer surfaces.
///
/// Theory anchor: THEORY.md §II.1 invariant 1 — typed entry; the
/// atomic-payload discriminator at a typed-entry rejection IS part of
/// the proof of WHAT the gate observed, and naming its closed-set
/// identity lifts the discriminator from per-site literal-pair
/// discipline (a byte at the Hash site, a SexpShape variant at the
/// `sexp_shape` site, a `&'static str` at any future LSP completion
/// site) to ONE typed enum the substrate's diagnostic + cache-key
/// surfaces both bind against. THEORY.md §II.1 invariant 2 — free
/// middle; THREE consumers ([`Hash for Atom`],
/// [`crate::domain::sexp_shape`], and the future diagnostic /
/// completion surface) route through ONE typed closed-set match
/// family, 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 closed set of atomic payload kinds becomes a
/// TYPE rather than six byte literals (Hash) + six SexpShape literals
/// (`sexp_shape`) scattered across distinct files — a typo in any one
/// site is no longer a runtime drift but a compile error against the
/// typed projection. THEORY.md §VI.1 — generation over composition;
/// the (Atom variant, label, discriminator-byte, SexpShape variant)
/// quadruple appeared inline at THREE sites (`Hash for Atom`'s six
/// byte arms, `domain::sexp_shape`'s six atom arms, plus implicit
/// pairing across `SexpShape::label`'s six atom-subset arms) — well
/// past the ≥2 PRIME-DIRECTIVE trigger once the structural shape is
/// named.
#[derive(Debug, Clone, Copy, PartialEq, Eq, tatara_closed_set::DeriveClosedSet)]
#[closed_set(via = "label", display, generate_unknown = "atom kind")]
pub enum AtomKind {
    /// `Atom::Symbol(_)` — `"symbol"` diagnostic label, byte `0u8`
    /// hash discriminator, projects to [`SexpShape::Symbol`].
    Symbol,
    /// `Atom::Keyword(_)` — `"keyword"` diagnostic label, byte `1u8`
    /// hash discriminator, projects to [`SexpShape::Keyword`].
    Keyword,
    /// `Atom::Str(_)` — `"string"` diagnostic label, byte `2u8` hash
    /// discriminator, projects to [`SexpShape::String`].
    Str,
    /// `Atom::Int(_)` — `"int"` diagnostic label, byte `3u8` hash
    /// discriminator, projects to [`SexpShape::Int`].
    Int,
    /// `Atom::Float(_)` — `"float"` diagnostic label, byte `4u8` hash
    /// discriminator, projects to [`SexpShape::Float`].
    Float,
    /// `Atom::Bool(_)` — `"bool"` diagnostic label, byte `5u8` hash
    /// discriminator, projects to [`SexpShape::Bool`].
    Bool,
}

impl AtomKind {
    /// The closed set of six atomic [`Atom`] payload kinds — single
    /// source of truth that drives every per-kind projection
    /// ([`Self::label`] / [`fmt::Display`], [`Self::hash_discriminator`],
    /// [`Self::sexp_shape`], and the [`Self::FromStr`] decode sweep
    /// keyed on [`Self::label`]).
    ///
    /// Adding a hypothetical seventh atomic kind (e.g. `Char` for
    /// `#\x` reader syntax, `Bigint` for arbitrary-precision
    /// integers) lands at one [`Self::ALL`] entry plus one arm per
    /// projection — exhaustively checked by the compiler (the
    /// `[Self; 6]` 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 kind's six),
    /// [`QuoteForm`] (the four homoiconic prefix wrappers — peer
    /// projection on the SAME `Sexp` algebra), [`UnquoteForm`] (the
    /// two template-substitution markers — proper subset of
    /// `QuoteForm`), 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 atom-kind label
    /// (every `expected X, got Y` substring in `LispError`'s rendered
    /// diagnostics for an atomic witness keys on this set's projection
    /// through [`Self::label`]); `tatara-check` coverage assertions
    /// over which atomic kinds reach a `TypeMismatch.got` arm at all
    /// — the typed sweep replaces a per-callsite vocabulary of six
    /// `&'static str` literals; any future audit-trail metric jointly
    /// labeled by [`Self::label`] (e.g.
    /// `tatara_lisp_atom_type_mismatch_total{got="symbol"}`) — the
    /// metric label set IS [`Self::ALL`] mapped through
    /// [`Self::label`]; any future structural rewriter (typed
    /// analogue of MLIR's `op.walk<AtomKind::Symbol>()`) that wants
    /// to sweep over every atomic kind in a typed sequence.
    pub const ALL: [Self; 6] = [
        Self::Symbol,
        Self::Keyword,
        Self::Str,
        Self::Int,
        Self::Float,
        Self::Bool,
    ];

    /// Canonical `&'static str` bytes for the [`Self::Symbol`] atomic-
    /// payload marker — aliases [`SexpShape::SYMBOL_LABEL`] on the
    /// AtomKind ⊂ SexpShape carving so the marker-level per-role bytes
    /// bind at ONE `pub const` on the parent superset's atomic arm
    /// rather than at TWO sites (the per-role `pub const` AND a
    /// parallel inline literal). Per-role peer of `Self::Symbol` on the
    /// closed-set atomic algebra; consumers reach for
    /// `AtomKind::SYMBOL_LABEL` when the caller has a variant in hand
    /// at compile time and wants the canonical diagnostic bytes without
    /// runtime dispatch through [`Self::label`].
    pub const SYMBOL_LABEL: &'static str = SexpShape::SYMBOL_LABEL;

    /// Canonical `&'static str` bytes for the [`Self::Keyword`] atomic-
    /// payload marker — aliases [`SexpShape::KEYWORD_LABEL`] on the
    /// AtomKind ⊂ SexpShape carving. Per-role peer of `Self::Keyword`.
    pub const KEYWORD_LABEL: &'static str = SexpShape::KEYWORD_LABEL;

    /// Canonical `&'static str` bytes for the [`Self::Str`] atomic-
    /// payload marker — aliases [`SexpShape::STRING_LABEL`] on the
    /// AtomKind ⊂ SexpShape carving. Per-role peer of `Self::Str`; the
    /// `Str → "string"` wire-shape rename matches
    /// [`SexpShape::String`]'s label projection so the AtomKind marker
    /// and its SexpShape peer emit byte-identical diagnostic bytes.
    pub const STRING_LABEL: &'static str = SexpShape::STRING_LABEL;

    /// Canonical `&'static str` bytes for the [`Self::Int`] atomic-
    /// payload marker — aliases [`SexpShape::INT_LABEL`] on the
    /// AtomKind ⊂ SexpShape carving. Per-role peer of `Self::Int`.
    pub const INT_LABEL: &'static str = SexpShape::INT_LABEL;

    /// Canonical `&'static str` bytes for the [`Self::Float`] atomic-
    /// payload marker — aliases [`SexpShape::FLOAT_LABEL`] on the
    /// AtomKind ⊂ SexpShape carving. Per-role peer of `Self::Float`.
    pub const FLOAT_LABEL: &'static str = SexpShape::FLOAT_LABEL;

    /// Canonical `&'static str` bytes for the [`Self::Bool`] atomic-
    /// payload marker — aliases [`SexpShape::BOOL_LABEL`] on the
    /// AtomKind ⊂ SexpShape carving. Per-role peer of `Self::Bool`.
    pub const BOOL_LABEL: &'static str = SexpShape::BOOL_LABEL;

    /// Closed-set forced-arity ALL array over the canonical atomic-
    /// payload marker `&'static str` bytes, in declaration order
    /// matching [`Self::ALL`] element-wise (pinned by
    /// `atom_kind_labels_align_with_all_by_index`). Sibling posture to
    /// [`SexpShape::LABELS`] (`[&'static str; 12]` — the superset
    /// carving this AtomKind subset embeds into),
    /// [`crate::error::ExpectedKwargShape::LABELS`] (`[&'static str; 7]`),
    /// [`crate::error::KwargPathKind::LABELS`] (`[&'static str; 3]`),
    /// [`crate::error::MacroDefHead::KEYWORDS`] (`[&'static str; 3]`),
    /// [`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.
    ///
    /// Pre-lift the six atomic-payload marker bytes had NO per-role
    /// primitive on this closed-set algebra — a consumer with an
    /// `AtomKind` variant in hand at compile time reaching for the
    /// canonical diagnostic bytes had to spell
    /// `AtomKind::Symbol.label()` (runtime dispatch through the
    /// composition [`Self::sexp_shape`] + [`SexpShape::label`]) OR
    /// reach across the algebra boundary into
    /// [`SexpShape::SYMBOL_LABEL`] and re-derive the AtomKind ⊂
    /// SexpShape variant pairing at the call site. Post-lift the SIX
    /// canonical bytes bind at ONE `pub const` per role on the typed
    /// [`AtomKind`] algebra AND at [`Self::LABELS`] as a family-wide
    /// forced-arity array — a future LSP / REPL completion bar keyed on
    /// `AtomKind::LABELS`, a `tatara-check` coverage sweep over the
    /// atomic-payload arms of a `TypeMismatch.got` corpus, or a Sekiban
    /// audit-trail metric jointly labeled by the atomic marker
    /// (`tatara_lisp_atom_type_mismatch_total{kind="symbol"}`) reads
    /// through the typed constants on this subset algebra without
    /// re-deriving the 6-of-12 carving inline.
    ///
    /// Each entry is byte-for-byte identical to the corresponding
    /// [`SexpShape`] atomic arm — an intentional cross-axis overlap
    /// pinned by
    /// `atom_kind_per_role_labels_alias_sexp_shape_per_role_labels_byte_for_byte`
    /// so a future label rename on EITHER side (a SexpShape `"string"`
    /// → `"str"` drift, or an AtomKind rename that skips the alias)
    /// fails-loudly at the alias test rather than as a silent
    /// operator-facing vocabulary fracture. Adding a hypothetical
    /// seventh atomic kind (e.g. `Char` for `#\x` reader syntax,
    /// `Bigint` for arbitrary-precision integers) 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 six canonical
    /// atomic-payload marker bytes bind at ONE typed
    /// `[&'static str; 6]` array on the closed-set AtomKind algebra
    /// rather than at zero-primitive-on-this-subset-plus-six-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 six per-role
    /// `pub const *_LABEL` aliases) rather than as per-variant inline
    /// assertions duplicated at each call site.
    pub const LABELS: [&'static str; 6] = [
        Self::SYMBOL_LABEL,
        Self::KEYWORD_LABEL,
        Self::STRING_LABEL,
        Self::INT_LABEL,
        Self::FLOAT_LABEL,
        Self::BOOL_LABEL,
    ];

    /// Canonical `u8` cache-key byte for [`Self::Symbol`]'s
    /// [`Self::hash_discriminator`] arm — `0`. Per-role peer of
    /// [`Self::Symbol`] on the closed-set atomic-payload cache-key-byte
    /// axis; consumers reach for `AtomKind::SYMBOL_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 Atom`], and any renumbering silently
    /// invalidates every cached expansion — post-lift the six canonical
    /// bytes bind at ONE `pub(crate) const` per role rather than at
    /// six inline `u8` literals scattered across
    /// [`Self::hash_discriminator`]'s match arms.
    ///
    /// Sibling posture to [`crate::error::QuoteForm::QUOTE_HASH_DISCRIMINATOR`]
    /// on the quote-family sub-carving — both close their respective
    /// closed-set cache-key algebras at ONE per-role constant per
    /// variant PLUS a family-wide [`Self::HASH_DISCRIMINATORS`] array.
    /// The two families partition their respective cache-key spaces
    /// independently: `AtomKind` at `{0..=5}` NESTED inside
    /// [`crate::ast::Sexp::Atom`]'s outer `1u8` byte (`Hash for Atom`
    /// runs on the [`Atom`] type, not [`Sexp`]), `QuoteForm` at
    /// `{3..=6}` at the outer [`Sexp`] cache-key space itself.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 5 — composition
    /// preserves proofs; the alias-chain composition law
    /// `AtomKind::HASH_DISCRIMINATORS[i] ==
    /// AtomKind::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 six canonical
    /// cache-key bytes bind at ONE `pub(crate) const` per role on the
    /// typed algebra rather than as inline `u8` literals in the
    /// `hash_discriminator` match arms.
    pub(crate) const SYMBOL_HASH_DISCRIMINATOR: u8 = 0;

    /// Canonical `u8` cache-key byte for [`Self::Keyword`]'s
    /// [`Self::hash_discriminator`] arm — `1`. Sibling of
    /// [`Self::SYMBOL_HASH_DISCRIMINATOR`] on the closed-set per-role
    /// atomic-payload cache-key-byte axis; see
    /// [`Self::SYMBOL_HASH_DISCRIMINATOR`] for the algebra-level
    /// round-trip + disjointness contracts every sibling shares.
    pub(crate) const KEYWORD_HASH_DISCRIMINATOR: u8 = 1;

    /// Canonical `u8` cache-key byte for [`Self::Str`]'s
    /// [`Self::hash_discriminator`] arm — `2`. Sibling of
    /// [`Self::SYMBOL_HASH_DISCRIMINATOR`] on the closed-set per-role
    /// atomic-payload cache-key-byte axis.
    pub(crate) const STR_HASH_DISCRIMINATOR: u8 = 2;

    /// Canonical `u8` cache-key byte for [`Self::Int`]'s
    /// [`Self::hash_discriminator`] arm — `3`. Sibling of
    /// [`Self::SYMBOL_HASH_DISCRIMINATOR`] on the closed-set per-role
    /// atomic-payload cache-key-byte axis.
    pub(crate) const INT_HASH_DISCRIMINATOR: u8 = 3;

    /// Canonical `u8` cache-key byte for [`Self::Float`]'s
    /// [`Self::hash_discriminator`] arm — `4`. Sibling of
    /// [`Self::SYMBOL_HASH_DISCRIMINATOR`] on the closed-set per-role
    /// atomic-payload cache-key-byte axis.
    pub(crate) const FLOAT_HASH_DISCRIMINATOR: u8 = 4;

    /// Canonical `u8` cache-key byte for [`Self::Bool`]'s
    /// [`Self::hash_discriminator`] arm — `5`. Sibling of
    /// [`Self::SYMBOL_HASH_DISCRIMINATOR`] on the closed-set per-role
    /// atomic-payload cache-key-byte axis. The HIGHEST byte on the
    /// closed set — a future seventh atomic kind (e.g. `Char` for
    /// `#\x` reader syntax, `Bigint` for arbitrary-precision integers)
    /// would extend the partition to `{0..=6}` and land the new
    /// discriminator at `6u8`.
    pub(crate) const BOOL_HASH_DISCRIMINATOR: u8 = 5;

    /// Closed-set forced-arity ALL array over the canonical atomic-
    /// payload cache-key `u8` bytes, in declaration order matching
    /// [`Self::ALL`] element-wise (pinned by
    /// `atom_kind_hash_discriminators_align_with_all_by_index`).
    /// Sibling posture to [`Self::LABELS`] (`[&'static str; 6]` — the
    /// diagnostic-label `&'static str` axis on the SAME closed set) and
    /// to [`crate::error::QuoteForm::HASH_DISCRIMINATORS`] (`[u8; 4]` —
    /// the quote-family sub-carving's cache-key-byte peer). Every
    /// closed-set outer projection on the substrate's [`AtomKind`]
    /// algebra that carries a `u8` per-variant discriminator now pins
    /// its per-role canonical bytes at ONE `pub(crate) const` per role
    /// PLUS an ALL array for family-wide consumers.
    ///
    /// Pre-lift the six cache-key bytes had NO per-role primitive on
    /// this closed-set algebra — a consumer with an [`AtomKind`]
    /// variant in hand at compile time reaching for the canonical byte
    /// had to spell `AtomKind::Str.hash_discriminator()` (runtime
    /// dispatch through the match arm) OR reach across into the inline
    /// `2u8` at the pre-lift match arm's [`Self::Str`] branch and
    /// re-derive the (variant, byte) pairing at the call site.
    /// Post-lift the SIX canonical bytes bind at ONE `pub(crate) const`
    /// per role on the typed [`AtomKind`] 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 that asserts every atomic arm's
    /// discriminator injective on the nested [`Atom`] axis, a Sekiban
    /// audit-trail metric jointly labeled by the atomic cache-key
    /// partition, a future `TypedRewriter<AtomKindOp>` 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 six-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
    /// `atom_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 an
    /// [`Atom`] participating in [`crate::macro_expand::Expander::cache`],
    /// fails-loudly at the alias test rather than at a silent cache
    /// mis-hash. Adding a hypothetical seventh atomic kind (e.g.
    /// `Char` for `#\x` reader syntax, `Bigint` for arbitrary-
    /// precision integers) 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 `6u8` (the next
    /// free byte on the nested [`Atom`] cache-key space).
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the six
    /// canonical cache-key bytes bind at ONE typed `[u8; 6]` array on
    /// the closed-set [`AtomKind`] algebra rather than at zero-
    /// primitive-plus-six-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 nested [`Atom`] `intent_hash` composition axis
    /// for every atomic arm — binding the six 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
    /// six 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::error::QuoteForm::HASH_DISCRIMINATORS`]: the substrate's
    /// current [`Hash for Atom`] 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 atomic byte-set upfront, a future `tatara-check`
    /// predicate `(check-atom-cache-key-partition-injective …)` that
    /// verifies the `{0..=5}` partition structurally, a future
    /// `TypedRewriter<AtomKindOp>` sweep zipping ALL / LABELS /
    /// HASH_DISCRIMINATORS in lockstep for a family-wide (variant,
    /// label, byte) triple render) bind to ONE `[u8; 6]` primitive
    /// rather than re-deriving the array inline per callsite.
    #[allow(dead_code)]
    pub(crate) const HASH_DISCRIMINATORS: [u8; 6] = [
        Self::SYMBOL_HASH_DISCRIMINATOR,
        Self::KEYWORD_HASH_DISCRIMINATOR,
        Self::STR_HASH_DISCRIMINATOR,
        Self::INT_HASH_DISCRIMINATOR,
        Self::FLOAT_HASH_DISCRIMINATOR,
        Self::BOOL_HASH_DISCRIMINATOR,
    ];

    /// Canonical `u8` OUTER-`Sexp` cache-key byte at which ALL SIX
    /// atomic-payload shapes collapse when hashed at the outer
    /// [`Hash for Sexp`](crate::ast::Sexp) level — `1`. The
    /// outer-carve peer of [`Self::HASH_DISCRIMINATORS`] (the six
    /// nested INNER cache-key bytes `{0..=5}` that specialise INSIDE
    /// [`Hash for Atom`] after the outer marker byte is emitted).
    /// The lift moves the byte the outer-Sexp cache-key algebra uses
    /// to distinguish [`crate::ast::Sexp::Atom(_)`] from every other
    /// outer-Sexp variant off inline `1u8` literals scattered across
    /// [`crate::error::SexpShape::hash_discriminator`]'s six-arm
    /// atomic collapse + the two structural-carve joint-partition
    /// disjointness pins and onto ONE `pub(crate) const` on the
    /// [`AtomKind`] algebra it names.
    ///
    /// Where the byte appears at the outer-Sexp cache-key algebra:
    /// [`crate::error::SexpShape::hash_discriminator`]'s atomic-arm
    /// collapse `Self::Symbol | Self::Keyword | Self::String |
    /// Self::Int | Self::Float | Self::Bool => 1` binds directly to
    /// this constant; every one of the six atomic shapes routes
    /// through the shape-level projection into the outer-Sexp cache
    /// key at THIS byte. The nested inner
    /// [`Self::HASH_DISCRIMINATORS`] `{0..=5}` bytes then specialise
    /// the atomic payload INSIDE [`Hash for Atom`] via a second
    /// discriminator emission (`self.hash_discriminator().hash(h)`
    /// on the [`Atom`] value carrier), so the two byte spaces live
    /// at different hash-sequence positions and do not collide.
    ///
    /// Sibling posture to [`crate::error::StructuralKind::HASH_DISCRIMINATORS`]
    /// (`[u8; 2]` at `{0, 2}` on the outer-Sexp cache-key space) and
    /// to [`crate::error::QuoteForm::HASH_DISCRIMINATORS`] (`[u8; 4]`
    /// at `{3, 4, 5, 6}` on the same space) — together with THIS
    /// scalar the three sibling carvings' byte spaces jointly
    /// partition the outer-Sexp discriminator space `{0..=6}`
    /// injectively. Post-lift the outer-Sexp cache-key algebra
    /// closes over FOUR typed byte primitives:
    ///   * [`Self::OUTER_HASH_DISCRIMINATOR`] (this constant) —
    ///     scalar `1u8` for the atomic-payload outer-carve;
    ///   * [`crate::error::StructuralKind::HASH_DISCRIMINATORS`] —
    ///     `{0, 2}` for the structural-residual carve;
    ///   * [`crate::error::QuoteForm::HASH_DISCRIMINATORS`] —
    ///     `{3..=6}` for the quote-family carve;
    ///   * [`Self::HASH_DISCRIMINATORS`] — the nested inner
    ///     `{0..=5}` byte-set INSIDE [`Hash for Atom`], NOT on the
    ///     outer-Sexp space.
    ///
    /// The scalar shape (single `u8`, NOT an array) is intrinsic to
    /// the carve: all six atomic-payload arms of
    /// [`crate::error::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
    /// [`Self::HASH_DISCRIMINATORS`] carve inside [`Hash for Atom`].
    /// The other two carvings' `HASH_DISCRIMINATORS` are arrays
    /// because their shape-level arms each carry a DISTINCT outer
    /// byte; the atomic carve is a scalar because its arms carry the
    /// SAME outer byte.
    ///
    /// `pub(crate)` because the byte 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::sexp_shape`]) don't already serve.
    /// Same posture as [`Self::HASH_DISCRIMINATORS`] +
    /// [`Self::SYMBOL_HASH_DISCRIMINATOR`] and the sibling carvings'
    /// per-role `pub(crate) const` peers.
    ///
    /// Pre-lift the outer-Atom marker byte lived at THREE sites: the
    /// inline `1u8` literal at
    /// [`crate::error::SexpShape::hash_discriminator`]'s six-arm
    /// atomic collapse; the inline `1u8` literal at
    /// `sexp_shape_hash_discriminator_atomic_arms_collapse_to_outer_atom_marker`'s
    /// assertion body; the inline `1u8` literal at
    /// `sexp_shape_hash_discriminator_partitions_by_three_way_carving_disjointly`'s
    /// `expected_atomic` fixture; PLUS a duplicated local `const
    /// ATOM_OUTER_CARVE_BYTE: u8 = 1` inside
    /// `structural_kind_hash_discriminator_disjoint_from_atom_outer_carve_byte_and_quote_form_hash_discriminator_partition`.
    /// The (byte, algebra) pairing had no typed home — a consumer
    /// with a typed [`AtomKind`] identity in hand reaching for the
    /// outer-Sexp cache-key byte the atomic arm collapses to had to
    /// re-derive the byte from the shape-level projection method's
    /// atomic collapse arm inline, OR re-derive the pre-lift local
    /// `ATOM_OUTER_CARVE_BYTE` fixture at every joint-partition-check
    /// site. Post-lift the byte binds at ONE `pub(crate) const` on
    /// the closed-set [`AtomKind`] algebra it names; every downstream
    /// consumer (the shape-level projection, the joint-partition
    /// disjointness pins, the three-way carving image pin, a future
    /// `tatara-check` predicate that verifies the outer-Sexp cache-
    /// key partition structurally, a future
    /// [`crate::macro_expand::Expander`] cache-warmup pass that
    /// hashes the outer-Sexp byte-set upfront) picks up the same
    /// canonical byte from ONE source of truth.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 5 — composition
    /// preserves proofs; the (AtomKind ⊂ SexpShape carve, outer-Sexp
    /// cache-key byte) pairing binds at rustc time by byte equality
    /// against the shape-level projection's atomic collapse arm.
    /// THEORY.md §III — the typescape; the outer-Atom cache-key byte
    /// binds at ONE `pub(crate) const` on the typed algebra rather
    /// than as inline `1u8` literals at every joint-partition + shape-
    /// level-collapse site. THEORY.md §V.1 — knowable platform; the
    /// outer-Sexp cache-key space's four-way partition (this scalar
    /// PLUS the three sibling carvings' arrays) becomes a TYPE-level
    /// constant on the substrate algebra rather than a per-callsite
    /// hand-rolled `{0, 1, 2, 3, 4, 5, 6}` re-enumeration. THEORY.md
    /// §V.3 — three-pillar attestation; the outer-Sexp cache-key
    /// partition is the substrate's outer [`Sexp`] `intent_hash`
    /// composition axis — binding the four-way partition's atomic-
    /// carve byte on the typed algebra makes attestation-key drift a
    /// compile error rather than a silent BLAKE3 mis-hash. A future
    /// eighth [`Sexp`] 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 the
    /// closed-set [`crate::error::SexpShape`] enum + its shape-level
    /// `hash_discriminator` and either an existing carving OR a fresh
    /// sub-algebra — the outer-Atom scalar itself stays untouched
    /// unless the new variant is also an atomic-payload arm.
    pub(crate) const OUTER_HASH_DISCRIMINATOR: u8 = 1;

    /// Project the typed marker to the canonical `&'static str`
    /// diagnostic label — `"symbol"` for [`Self::Symbol`],
    /// `"keyword"` for [`Self::Keyword`], `"string"` for [`Self::Str`]
    /// (the wire-shape rename `Str → "string"` matches the
    /// [`SexpShape::String`] label projection), `"int"` for
    /// [`Self::Int`], `"float"` for [`Self::Float`], `"bool"` for
    /// [`Self::Bool`]. Each label is byte-for-byte identical to the
    /// corresponding [`SexpShape`] variant's label — and post-lift this
    /// agreement is STRUCTURAL rather than two literal-discipline sites
    /// pinned by a cross-projection test.
    ///
    /// Composition law: `AtomKind::label(k) ==
    /// AtomKind::sexp_shape(k).label()` for every `k: AtomKind`. The
    /// body composes [`Self::sexp_shape`] (the typed projection lifting
    /// each AtomKind variant into its peer [`SexpShape`] variant) with
    /// [`SexpShape::label`] (the canonical `&'static str` projection on
    /// the supeset's twelve-variant closed set), so the six atomic-arm
    /// labels live at ONE canonical site ([`SexpShape::label`]) rather
    /// than at TWO ([`SexpShape::label`] AND a parallel six-arm match
    /// here, pre-lift). Pre-lift the substrate-wide AtomKind ⊂ SexpShape
    /// label-vocabulary agreement was enforced by literal discipline at
    /// the two sites + a cross-projection test
    /// (`atom_kind_label_agrees_with_sexp_shape_label_for_every_atom_arm`);
    /// post-lift the agreement is a TYPED CONSEQUENCE of the composition
    /// — a typo in `SexpShape::label`'s atomic arms is a typo in BOTH
    /// projections, and the cross-projection test is true by
    /// construction. Same lift posture as the prior-run
    /// `Atom::as_X → Atom::as_X` algebra-lift commit (6935416), the
    /// `from_lexeme` reader-atom lift commit (9b95e64), and the
    /// `to_iac_forge_sexpr` Atom-arm lift commit (418be51): 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: it lets the
    /// variant project through this method without an allocation,
    /// parallel to how [`SexpShape::label`], [`QuoteForm::prefix`],
    /// [`QuoteForm::iac_forge_tag`], [`UnquoteForm::marker`], and
    /// [`crate::error::ExpectedKwargShape::label`] project their
    /// respective closed-set surfaces. The composition preserves the
    /// no-allocation contract: [`Self::sexp_shape`] returns a `Copy`
    /// value and [`SexpShape::label`] yields `&'static str`, so the
    /// `&'static str` projection through the composition allocates
    /// nothing at runtime.
    ///
    /// The bidirectional contract is anchored by tests:
    /// `atom_kind_label_renders_canonical_string_for_every_variant`
    /// pins each variant's canonical literal so a typo in
    /// [`SexpShape::label`]'s atomic arms fails-loudly through this
    /// projection too, `atom_kind_display_matches_label_for_every_variant`
    /// pins Display-equals-label so any future
    /// `#[error("... got {got}")]` annotation that threads through
    /// this projection projects byte-for-byte, and
    /// `atom_kind_label_round_trips_through_from_str` pins the
    /// `label` ↔ [`Self::FromStr`] round-trip for every variant in
    /// [`Self::ALL`] so the typed surface and the rendered diagnostic
    /// literal cannot drift. The post-lift composition contract is
    /// pinned by
    /// `atom_kind_label_routes_through_sexp_shape_label_via_sexp_shape_projection`
    /// — a regression that re-inlines the six atomic-arm literals here
    /// and silently drifts ONE arm from the [`SexpShape::label`] axis
    /// fails the routing pin loudly without needing a per-variant
    /// cross-axis literal sweep.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the
    /// AtomKind ⊂ 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 six atomic-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; FOUR consumers of the
    /// [`AtomKind`] algebra ([`Hash for Atom`] via
    /// [`Self::hash_discriminator`], [`crate::domain::sexp_shape`] via
    /// [`Self::sexp_shape`], the diagnostic-rendering surface via this
    /// method, and the `ClosedSet`-trait FromStr/Display surface via
    /// `#[closed_set(via = "label")]`) now 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()
    }

    /// Stable, per-variant byte discriminator that paired with the
    /// recursive payload hash builds the substrate's [`Hash for Atom`]
    /// projection — `0u8` for [`Self::Symbol`], `1u8` for
    /// [`Self::Keyword`], `2u8` for [`Self::Str`], `3u8` for
    /// [`Self::Int`], `4u8` for [`Self::Float`], `5u8` for
    /// [`Self::Bool`]. 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 any
    /// `Atom` participates in that hash — changing a discriminator
    /// silently invalidates every cached expansion across the
    /// substrate.
    ///
    /// The closed set ensures the six arms partition `{0, 1, 2, 3,
    /// 4, 5}` injectively. Disjointness from [`QuoteForm`]'s
    /// `{3, 4, 5, 6}` is structural rather than overlap-induced
    /// hash collision: [`Hash for Atom`] and the quote-family arms of
    /// [`Hash for Sexp`] hash DISTINCT types (`Atom` vs `Sexp`), and
    /// `Atom`'s discriminator lives nested INSIDE `Sexp::Atom`'s outer
    /// `1u8` discriminator — the prefix-uniqueness contract that the
    /// `Hash for Sexp` outer match maintains independently. A future
    /// quote-family or atomic-kind extension must extend BOTH bodies'
    /// arms in lockstep, with rustc binding the consistency through
    /// exhaustiveness over BOTH closed enums.
    ///
    /// `pub(crate)` because the byte-discriminator surface is an
    /// implementation detail of the substrate's [`Hash for Atom`]
    /// cache-key contract; exposing it publicly would leak the
    /// cache-key shape through the API without enabling any external
    /// consumer the public projections ([`Atom::kind`], [`Self::label`],
    /// [`Self::sexp_shape`]) don't already serve. Same posture as
    /// [`QuoteForm::hash_discriminator`] and its outer-value peer
    /// [`Atom::hash_discriminator`] (the outer-`Atom` projection that
    /// composes through this method via `self.kind().hash_discriminator()`
    /// so the [`Hash for Atom`] callsite binds at ONE site on the
    /// outer-`Atom` algebra rather than at the two-hop
    /// `.kind().hash_discriminator()` chain).
    #[must_use]
    pub(crate) fn hash_discriminator(self) -> u8 {
        match self {
            Self::Symbol => Self::SYMBOL_HASH_DISCRIMINATOR,
            Self::Keyword => Self::KEYWORD_HASH_DISCRIMINATOR,
            Self::Str => Self::STR_HASH_DISCRIMINATOR,
            Self::Int => Self::INT_HASH_DISCRIMINATOR,
            Self::Float => Self::FLOAT_HASH_DISCRIMINATOR,
            Self::Bool => Self::BOOL_HASH_DISCRIMINATOR,
        }
    }

    /// Canonical [`SexpShape`] embed target for the [`Self::Symbol`]
    /// atomic-payload arm on the AtomKind ⊂ SexpShape 6-of-12 carving —
    /// [`SexpShape::Symbol`]. Per-role peer of `Self::Symbol` on the
    /// closed-set atomic-payload → outer-shape embed axis; consumers
    /// reach for `AtomKind::SYMBOL_SHAPE` when the caller has a variant
    /// in hand at compile time and wants the canonical outer-shape
    /// identity without runtime dispatch through [`Self::sexp_shape`].
    ///
    /// Sibling posture to the six pre-existing per-role LABEL /
    /// HASH_DISCRIMINATOR aliases on this same closed-set algebra
    /// ([`Self::SYMBOL_LABEL`], [`Self::SYMBOL_HASH_DISCRIMINATOR`]) —
    /// each closes a distinct per-role sub-vocabulary axis on the
    /// AtomKind carving. This constant closes the THIRD per-role
    /// axis on [`AtomKind`] (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.
    pub const SYMBOL_SHAPE: SexpShape = SexpShape::Symbol;

    /// Canonical [`SexpShape`] embed target for the [`Self::Keyword`]
    /// atomic-payload arm on the AtomKind ⊂ SexpShape carving —
    /// [`SexpShape::Keyword`]. Per-role peer of `Self::Keyword`.
    pub const KEYWORD_SHAPE: SexpShape = SexpShape::Keyword;

    /// Canonical [`SexpShape`] embed target for the [`Self::Str`]
    /// atomic-payload arm on the AtomKind ⊂ SexpShape carving —
    /// [`SexpShape::String`]. Per-role peer of `Self::Str`; the
    /// `Str → String` wire-shape rename matches the peer
    /// [`Self::STRING_LABEL`] alias (both bind the AtomKind subset's
    /// `Str` variant to the SexpShape superset's `String` variant on
    /// their respective per-role sub-vocabulary axes).
    pub const STR_SHAPE: SexpShape = SexpShape::String;

    /// Canonical [`SexpShape`] embed target for the [`Self::Int`]
    /// atomic-payload arm on the AtomKind ⊂ SexpShape carving —
    /// [`SexpShape::Int`]. Per-role peer of `Self::Int`.
    pub const INT_SHAPE: SexpShape = SexpShape::Int;

    /// Canonical [`SexpShape`] embed target for the [`Self::Float`]
    /// atomic-payload arm on the AtomKind ⊂ SexpShape carving —
    /// [`SexpShape::Float`]. Per-role peer of `Self::Float`.
    pub const FLOAT_SHAPE: SexpShape = SexpShape::Float;

    /// Canonical [`SexpShape`] embed target for the [`Self::Bool`]
    /// atomic-payload arm on the AtomKind ⊂ SexpShape carving —
    /// [`SexpShape::Bool`]. Per-role peer of `Self::Bool`.
    pub const BOOL_SHAPE: SexpShape = SexpShape::Bool;

    /// Closed-set forced-arity ALL array over the canonical
    /// [`SexpShape`] embed targets on the AtomKind ⊂ SexpShape
    /// 6-of-12 carving, in declaration order matching [`Self::ALL`]
    /// element-wise (pinned by
    /// `atom_kind_shapes_align_with_all_by_index`). Sibling posture
    /// to [`Self::LABELS`] (`[&'static str; 6]` — per-role diagnostic
    /// bytes) and [`Self::HASH_DISCRIMINATORS`] (`[u8; 6]` — per-role
    /// nested-Atom cache-key bytes) on the SAME closed-set AtomKind
    /// algebra; where those two arrays lift the 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 `[_; 6]` forced arity.
    ///
    /// Pre-lift the six [`SexpShape`] embed targets had NO per-role
    /// primitive on this closed-set algebra — a consumer with an
    /// `AtomKind` variant in hand at compile time reaching for the
    /// canonical embed target had to spell
    /// `AtomKind::Symbol.sexp_shape()` (runtime dispatch through the
    /// six-arm match body) OR re-derive the AtomKind ⊂ SexpShape
    /// variant pairing at the call site by importing both enums and
    /// spelling `SexpShape::Symbol` inline. Post-lift the SIX
    /// canonical embed targets bind at ONE `pub const` per role on
    /// the typed [`AtomKind`] algebra AND at [`Self::SHAPES`] as a
    /// family-wide forced-arity array — a future LSP / REPL
    /// completion bar keyed on `AtomKind::SHAPES` for the "which
    /// SexpShape does this AtomKind embed into?" outer-shape column,
    /// a `tatara-check` coverage sweep zipping `AtomKind::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
    /// 6-of-12 carving inline.
    ///
    /// Round-trip identity with the inverse projection
    /// [`crate::error::SexpShape::as_atom_kind`]: for every index `i`,
    /// `Self::SHAPES[i].as_atom_kind() == Some(Self::ALL[i])`
    /// (pinned by
    /// `atom_kind_shapes_align_with_all_by_index_through_as_atom_kind`) —
    /// the embed / project section closes as a family-wide array-
    /// indexed law rather than as a per-variant assertion sweep.
    /// Adding a hypothetical seventh atomic kind (e.g. `Char` for
    /// `#\x` reader syntax, `Bigint` for arbitrary-precision
    /// integers) 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_atom_kind`] arm must
    /// grow in lockstep to preserve the round-trip identity.
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the six
    /// canonical [`SexpShape`] embed targets bind at ONE typed
    /// `[SexpShape; 6]` array on the closed-set AtomKind algebra
    /// rather than at zero-primitive-on-this-subset-plus-six-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
    /// §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 [`crate::error::SexpShape::as_atom_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_atom_kind`, membership through `sexp_shape`) emerge from
    /// the composition of TWO substrate primitives (this `pub const`
    /// array + the six per-role `pub const *_SHAPE` aliases) rather
    /// than as per-variant inline assertions duplicated at each call
    /// site.
    pub const SHAPES: [SexpShape; 6] = [
        Self::SYMBOL_SHAPE,
        Self::KEYWORD_SHAPE,
        Self::STR_SHAPE,
        Self::INT_SHAPE,
        Self::FLOAT_SHAPE,
        Self::BOOL_SHAPE,
    ];

    /// Project the typed marker into its matching [`SexpShape`]
    /// variant — `Symbol → SexpShape::Symbol`, `Keyword →
    /// SexpShape::Keyword`, `Str → SexpShape::String`, `Int →
    /// SexpShape::Int`, `Float → SexpShape::Float`, `Bool →
    /// SexpShape::Bool`. ONE projection on the closed-set atomic-
    /// payload algebra that [`crate::domain::sexp_shape`]'s outer-shape
    /// projection routes through for the six atom arms — so the
    /// (Atom variant, SexpShape variant) pairing binds at ONE site on
    /// the typed algebra rather than at six byte-identical inline arms
    /// in [`crate::domain::sexp_shape`]. Direct sibling to
    /// [`QuoteForm::sexp_shape`] — that closed enum carves the
    /// quote-family arms of [`SexpShape`]'s twelve-variant closed set,
    /// while this enum carves the atomic-payload arms.
    ///
    /// Each arm routes through the per-role `pub const` on `impl Self`
    /// ([`Self::SYMBOL_SHAPE`], [`Self::KEYWORD_SHAPE`],
    /// [`Self::STR_SHAPE`], [`Self::INT_SHAPE`], [`Self::FLOAT_SHAPE`],
    /// [`Self::BOOL_SHAPE`]) so the six canonical embed targets bind
    /// at ONE typed source of truth per role rather than as inline
    /// `SexpShape::X` literals scattered across the `match` body.
    /// Sibling posture to [`Self::label`]'s composition through
    /// [`Self::sexp_shape().label()`] and [`Self::hash_discriminator`]'s
    /// per-role routing through [`Self::SYMBOL_HASH_DISCRIMINATOR`] …
    /// [`Self::BOOL_HASH_DISCRIMINATOR`] — the three per-role axes on
    /// the AtomKind algebra (embed target, diagnostic label, cache-key
    /// byte) each surface their per-role bytes through the SAME
    /// per-role `pub const` shape.
    ///
    /// Composition law: for every [`Atom`] `a`,
    /// `crate::domain::sexp_shape(&Sexp::Atom(a.clone())) ==
    /// a.kind().sexp_shape()`. Pinned by the cross-projection round-trip
    /// test in this module, so a regression that drifts either side
    /// of the typed algebra (an [`Atom::kind`] arm or this
    /// [`Self::sexp_shape`] arm) surfaces immediately rather than as a
    /// silent operator-facing diagnostic drift at every
    /// `LispError::TypeMismatch.got` slot for an atomic witness.
    ///
    /// Post-lift routing pin
    /// `atom_kind_sexp_shape_routes_through_typed_per_role_constants`
    /// catches a regression that re-inlines the six `SexpShape::X`
    /// arm literals here and silently drifts ONE arm from the per-role
    /// `pub const` alias — the routing agreement is a TYPED CONSEQUENCE
    /// of the composition rather than literal discipline at two sites.
    ///
    /// Bidirectional dual: the inverse projection
    /// [`crate::error::SexpShape::as_atom_kind`] (12→6, partial)
    /// covers the 6-of-12 carving of [`SexpShape`] this embed
    /// reaches. The pair `(AtomKind::sexp_shape,
    /// SexpShape::as_atom_kind)` forms an `Iso(AtomKind, AtomShape ⊂
    /// SexpShape)`: every typed marker round-trips through the embed
    /// (`AtomKind::sexp_shape(k).as_atom_kind() == Some(k)` for every
    /// `k: AtomKind`), every atom-shape pre-image recovers the typed
    /// marker. The non-atom shapes (`Nil`, `List`, every quote-family
    /// wrapper) form the kernel of the inverse — `as_atom_kind`
    /// returns `None` for them. See [`crate::error::SexpShape::as_atom_kind`]'s
    /// docstring for the composition law's other direction +
    /// disjointness with the quote-family sibling
    /// `SexpShape::as_quote_form`.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the (Atom
    /// variant, SexpShape variant) pairing becomes a TYPE projection
    /// on the substrate algebra rather than six inline arms in
    /// [`crate::domain::sexp_shape`]. 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; THREE consumers ([`Hash for Atom`] via
    /// [`Self::hash_discriminator`], [`crate::domain::sexp_shape`]
    /// via this method, and the future diagnostic / completion surface
    /// via [`Self::label`]) now route through ONE typed closed-set
    /// match family, so a regression that drifts ONE consumer's
    /// pairing from the others cannot reach the substrate's runtime.
    #[must_use]
    pub fn sexp_shape(self) -> SexpShape {
        match self {
            Self::Symbol => Self::SYMBOL_SHAPE,
            Self::Keyword => Self::KEYWORD_SHAPE,
            Self::Str => Self::STR_SHAPE,
            Self::Int => Self::INT_SHAPE,
            Self::Float => Self::FLOAT_SHAPE,
            Self::Bool => Self::BOOL_SHAPE,
        }
    }
}

// `impl fmt::Display for AtomKind` + `impl std::str::FromStr for AtomKind`
// + `impl tatara_closed_set::ClosedSet for AtomKind` + `pub struct UnknownAtomKind(pub
// String)` are generated by `#[derive(tatara_closed_set::DeriveClosedSet)]` on
// the enum declaration above. `label` delegates to the inherent
// `AtomKind::label` via `#[closed_set(via = "label")]` so the
// domain-canonical lowercase-vocabulary projection stays load-bearing (the
// six labels `"symbol" / "keyword" / "string" / "int" / "float" / "bool"`
// match the `SexpShape` atomic-subset labels byte-for-byte AND the
// diagnostic-rendering shape `LispError::TypeMismatch.got` keys on
// verbatim). The `display` flag emits the substrate-wide
// `f.write_str(Self::label(*self))` block. `#[closed_set(generate_unknown =
// "atom kind")]` emits the typed parse-rejection carrier with the
// substrate-wide `Debug + Clone + PartialEq + Eq + thiserror::Error`
// derives and the `#[error("unknown atom kind: {0}")]` annotation
// byte-for-byte; the explicit label pins the pre-lift wording even though
// the auto-derived `pascal_to_spaced_lowercase("AtomKind")` projects to
// the same `"atom kind"` literal.

impl Sexp {
    /// Canonical `(` char that opens a [`Self::List`] rendering AND
    /// (paired with [`Self::LIST_CLOSE`]) the empty [`Self::Nil`]
    /// rendering `()`. Outer-structural peer of [`Atom::STR_DELIMITER`]
    /// on the atomic-payload delimiter axis: where `STR_DELIMITER` is
    /// the ONE `"` byte the reader's tokenizer's FOUR
    /// `Token::Str`-round-trip sites bind to on the closed-set [`Atom`]
    /// algebra, `LIST_OPEN` is the ONE `(` byte the reader's tokenizer's
    /// `Token::LParen` outer-dispatch arm AND the bare-atom terminator
    /// disjunct AND [`fmt::Display for Sexp`]'s list-opening emission
    /// AND [`Self::Nil`]'s two-char `()` rendering all bind to on the
    /// closed-set outer [`Sexp`] algebra.
    ///
    /// Pre-lift the same `'('` byte lived inline at FOUR sites: two
    /// outer-match arms in `crate::reader::tokenize` (the
    /// `Token::LParen` construction arm AND the bare-atom terminator's
    /// `|| ch == '('` disjunct), and two Display arms in [`fmt::Display
    /// for Sexp`] (the `Self::List(_)` opener AND the `Self::Nil`
    /// two-char `()` rendering's left char). Post-lift the (typed
    /// structural role, canonical byte) pairing binds at ONE constant
    /// on the [`Sexp`] algebra that every consumer routes through; a
    /// refactor that swaps the byte (e.g. a Racket-style port to `[`
    /// for square-bracket list literals, an S-expression-DSL port to
    /// `{` for brace-list syntax) touches ONE constant rather than
    /// four inline bytes that would silently drift out of round-trip
    /// agreement if one was updated without the others.
    ///
    /// Load-bearing paired-delimiter contract:
    /// `Sexp::LIST_OPEN` MUST pair section-for-retraction with
    /// [`Self::LIST_CLOSE`] at every round-trip site — the reader's
    /// `Token::LParen` (from `LIST_OPEN`) MUST be closed by a
    /// `Token::RParen` (from `LIST_CLOSE`) for a well-formed list,
    /// and the Display impl's `Self::List(_)` arm MUST emit
    /// `LIST_OPEN` at the opener AND `LIST_CLOSE` at the closer for
    /// the reader-then-Display round trip
    /// `parse(display(list)) == list` to hold. Guards the paired
    /// disjointness across the closed-set outer [`Sexp`] algebra so a
    /// future refactor that renames one constant without updating the
    /// other fails at rustc / test time rather than as a silent list-
    /// rendering asymmetry.
    ///
    /// Cross-axis disjointness with the sibling delimiters (pinned
    /// structurally at
    /// `sexp_list_delimiters_distinct_from_every_other_algebra_marker`):
    /// `LIST_OPEN`'s byte MUST differ from [`Atom::STR_DELIMITER`]
    /// (`'"'`), [`Atom::KEYWORD_MARKER`] (`":"`), the two
    /// [`Atom::bool_literal`] spellings (`"#t"` / `"#f"`) AND every
    /// [`QuoteForm::lead_char`] projection (`'\''`, `` '`' ``, `','`)
    /// on the substrate's outer-marker axes. Otherwise the reader's
    /// `Token::LParen` outer-dispatch arm would ambiguously route
    /// through a sibling algebra's arm.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 2 — free middle; the
    /// (`Self::List` outer structure, canonical `(` opener) pairing
    /// now binds at ONE constant on the closed-set outer [`Sexp`]
    /// algebra regardless of which of the four consumer surfaces
    /// reaches in. THEORY.md §VI.1 — generation over composition;
    /// four byte-identical inline `'('` char literals across two
    /// substrate files collapse onto ONE named constant, matching
    /// the substrate's three-times rule. THEORY.md §V.1 — knowable
    /// platform; the canonical list-opener byte becomes a
    /// TYPE-level constant on the outer substrate algebra rather
    /// than four inline bytes at four consumer surfaces across two
    /// substrate files (`crate::reader` and `crate::ast`).
    pub const LIST_OPEN: char = '(';

    /// Canonical `)` char that closes a [`Self::List`] rendering AND
    /// (paired with [`Self::LIST_OPEN`]) the empty [`Self::Nil`]
    /// rendering `()`. See [`Self::LIST_OPEN`] for the substrate-wide
    /// paired-delimiter contract, cross-axis disjointness, and theory
    /// anchors — this constant is its section-for-retraction sibling
    /// on the closer axis. Four consumer sites (the reader's
    /// `Token::RParen` outer-dispatch arm, the bare-atom terminator's
    /// `|| ch == ')'` disjunct, [`fmt::Display for Sexp`]'s
    /// `Self::List(_)` closer, [`Self::Nil`]'s two-char `()`
    /// rendering's right char) all bind here.
    pub const LIST_CLOSE: char = ')';

    /// Canonical paired list-delimiter closed-set ALL array — composes
    /// [`Self::LIST_OPEN`] followed by [`Self::LIST_CLOSE`] in canonical
    /// declaration order, forced-arity `[char; 2]` so a hypothetical
    /// third list-delimiter row would extend this array + one algebra
    /// constant in lockstep. Peer to [`Atom::SELF_ESCAPE_TABLE`]
    /// (`[char; 2]` on the Str-payload self-escape sub-vocabulary axis
    /// of the closed-set [`Atom`] algebra): where `SELF_ESCAPE_TABLE`
    /// closes the two pattern-EQUALS-value inner-tokenizer arms of
    /// `Atom::decode_str_escape` as ONE typed forced-arity array,
    /// `LIST_DELIMITERS` closes the two outer-structural list-delimiter
    /// arms of the reader's outer-dispatch as the analogous typed
    /// forced-arity array one axis over on the closed-set outer
    /// [`Sexp`] algebra.
    ///
    /// Pre-lift the two-element `[Self::LIST_OPEN, Self::LIST_CLOSE]`
    /// composition lived inline at TWO sites: the two `|| ch ==
    /// Self::LIST_{OPEN,CLOSE}` disjuncts inside
    /// [`Self::is_bare_atom_boundary`]'s reader-boundary projection
    /// (spanning TWO of the SIX categories the projection carries), AND
    /// the `[Sexp::LIST_OPEN, Sexp::LIST_CLOSE].iter().collect()` array
    /// literal at the `Nil` Display composition-pin test that binds the
    /// two-char `()` rendering to the two typed constants. Post-lift
    /// the sub-vocabulary sweep binds at ONE typed forced-arity array
    /// on the closed-set outer [`Sexp`] algebra rather than at two
    /// inline algebra-constant enumerations per consumer. Adding a
    /// hypothetical Racket-compat square-bracket list mode
    /// (`[Self::LIST_OPEN, Self::LIST_CLOSE, Self::VEC_OPEN,
    /// Self::VEC_CLOSE]`) would extend `LIST_DELIMITERS` ONCE +
    /// `Self::is_bare_atom_boundary`'s sub-vocabulary sweep ONCE + two
    /// new algebra constants (opener + closer) in lockstep; rustc's
    /// forced-arity check on `[char; N]` binds the extension through
    /// the array declaration site.
    ///
    /// Structural invariant carried at the SHAPE level: `[char; 2]`
    /// pairs section-for-retraction one-to-one with
    /// [`Atom::SELF_ESCAPE_TABLE`]'s `[char; 2]` — the two arrays
    /// sit on distinct closed-set algebras (outer-structural
    /// list-delimiter vocabulary on [`Sexp`]; inner-Str-payload
    /// self-escape vocabulary on [`Atom`]) but share the same
    /// forced-arity shape at their respective sub-vocabulary
    /// axes. A consumer that reaches for one of the two arrays
    /// encodes its vocabulary's paired-role identity in the SHAPE
    /// it iterates rather than in a per-site convention.
    ///
    /// Composition law (round-trip): `LIST_DELIMITERS[0] ==
    /// Self::LIST_OPEN` AND `LIST_DELIMITERS[1] == Self::LIST_CLOSE`
    /// AND `LIST_DELIMITERS.len() == 2`. The forced-arity + canonical
    /// declaration order together pin every downstream index-sweep
    /// consumer to the (opener, closer) pairing at rustc time; a
    /// reorder without reordering the underlying algebra constants
    /// fails at the composition pin below.
    ///
    /// Cross-axis disjointness pinned structurally at
    /// [`sexp_list_delimiters_distinct_from_every_other_algebra_marker`]:
    /// neither element aliases any sibling outer-marker char on the
    /// substrate's other closed-set algebras — the Str-payload
    /// delimiter (`Atom::STR_DELIMITER`), the Keyword-marker prefix
    /// (`Atom::KEYWORD_MARKER_LEAD`), the Comment-lead byte
    /// (`Self::COMMENT_LEAD`), every quote-family lead char
    /// (`QuoteForm::lead_char`), and every Bool-literal spelling's
    /// first char.
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the paired
    /// (opener, closer) list-delimiter sub-vocabulary becomes a typed
    /// forced-arity ALL array on the closed-set outer [`Sexp`]
    /// algebra rather than as two inline algebra-constant
    /// enumerations at every consumer that iterates the paired
    /// delimiter axis. THEORY.md §V.1 — knowable platform; the
    /// paired-delimiter sub-vocabulary now binds as load-bearing
    /// typed data at the algebra level rather than as two per-site
    /// disjuncts. THEORY.md §VI.1 — generation over composition; the
    /// paired-delimiter (opener + closer) composition regenerates
    /// identically through this ONE typed forced-arity array rather
    /// than through two inline algebra-constant enumerations per
    /// consumer.
    pub const LIST_DELIMITERS: [char; 2] = [Self::LIST_OPEN, Self::LIST_CLOSE];

    /// Canonical `;` char that begins a line-comment run in the reader's
    /// tokenizer AND (as a bare-atom terminator disjunct) breaks a
    /// `Token::Atom` accumulator when the byte is encountered mid-lexeme.
    /// Outer-structural peer of [`Self::LIST_OPEN`] / [`Self::LIST_CLOSE`]
    /// on the reader-discard axis: where `LIST_OPEN` / `LIST_CLOSE` are
    /// the paired-delimiter constants that shape a `Sexp::List` payload
    /// on the closed-set outer [`Sexp`] algebra, `COMMENT_LEAD` is the
    /// ONE `;` byte the reader's tokenizer's TWO comment-boundary sites
    /// bind to on the same outer algebra — the outer-dispatch arm that
    /// begins a line-comment run (consuming through the trailing `\n`
    /// which is itself absorbed by the whitespace disjunct in the outer
    /// match) AND the bare-atom terminator disjunct that ends a
    /// `Token::Atom` accumulator when it encounters this byte mid-lexeme
    /// so a bare `foo;bar` source tokenizes as `Token::Atom("foo") @ 0`
    /// followed by a discarded line-comment run rather than as ONE
    /// `Token::Atom("foo;bar")` payload.
    ///
    /// Pre-lift the same `';'` byte lived inline at TWO sites in
    /// `crate::reader::tokenize`: the outer-match `';' => { … }`
    /// line-comment arm AND the bare-atom terminator's `|| ch == ';'`
    /// disjunct. Post-lift the (reader-discard role, canonical byte)
    /// pairing binds at ONE constant on the [`Sexp`] algebra that both
    /// consumer sites route through; a refactor that swaps the byte
    /// (e.g. a Scheme R7RS-style port to `#;` datum-comment syntax, an
    /// Emacs-style port to `#!` shebang-comment syntax) touches ONE
    /// constant rather than two inline bytes that would silently drift
    /// out of tokenizer agreement if one was updated without the other.
    ///
    /// Reader-discard contract: `Sexp::COMMENT_LEAD` MUST NOT surface
    /// as an atomic payload in any parsed [`Sexp`] — the outer-dispatch
    /// arm consumes the byte AND every char up to (but not past) the
    /// trailing `\n`, emitting NO token. The bare-atom terminator
    /// disjunct breaks the `Token::Atom` accumulator EXACTLY on this
    /// byte so the subsequent line-comment run reaches the outer arm
    /// with its byte-offset intact. Both sites bind to ONE constant so
    /// a regression that drifts ONE of the two disjuncts (e.g.
    /// re-inlines `';'` at the outer arm while migrating the terminator
    /// to a different byte) fails at rustc / test time rather than as
    /// a silent tokenizer misclassification.
    ///
    /// Cross-axis disjointness with the sibling markers (pinned
    /// structurally at
    /// `sexp_comment_lead_distinct_from_every_other_algebra_marker`):
    /// `COMMENT_LEAD`'s byte MUST differ from [`Self::LIST_OPEN`]
    /// (`'('`), [`Self::LIST_CLOSE`] (`')'`), [`Atom::STR_DELIMITER`]
    /// (`'"'`), [`Atom::KEYWORD_MARKER`]'s lead byte (`':'`), the two
    /// [`Atom::bool_literal`] spellings' lead byte (`'#'`) AND every
    /// [`QuoteForm::lead_char`] projection (`'\''`, `` '`' ``, `','`)
    /// on the substrate's outer-marker axes. Otherwise a bare `;foo`
    /// lexeme would ambiguously route through the line-comment arm AND
    /// a sibling algebra's arm at the reader's outer dispatch.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 2 — free middle; the
    /// (reader-discard role, canonical `;` byte) pairing binds at ONE
    /// constant on the closed-set outer [`Sexp`] algebra regardless of
    /// which of the two consumer sites reaches in. THEORY.md §VI.1 —
    /// generation over composition; two byte-identical inline `';'`
    /// char literals across ONE substrate file collapse onto ONE named
    /// constant, matching the substrate's three-times rule
    /// (`\geq 2` PRIME-DIRECTIVE trigger). THEORY.md §V.1 — knowable
    /// platform; the canonical comment-lead byte becomes a TYPE-level
    /// constant on the outer substrate algebra rather than two inline
    /// bytes at two consumer surfaces in `crate::reader`.
    pub const COMMENT_LEAD: char = ';';

    /// Canonical `\n` char that terminates a line-comment run in the
    /// reader's tokenizer — the section-for-retraction sibling of
    /// [`Self::COMMENT_LEAD`] on the reader-discard axis. Paired
    /// opener/terminator peer of [`Self::LIST_OPEN`] /
    /// [`Self::LIST_CLOSE`] on the outer-structural axis: where
    /// [`Self::LIST_OPEN`] / [`Self::LIST_CLOSE`] are the two typed
    /// constants that shape a `Sexp::List` payload, [`Self::COMMENT_LEAD`]
    /// / [`Self::COMMENT_TERM`] are the two typed constants that shape
    /// the reader's line-comment discard run. Both pairs live on the
    /// closed-set outer [`Sexp`] algebra so the reader-discard axis
    /// carries the same opener/closer discipline the outer-structural
    /// axis has carried since the initial [`Self::LIST_OPEN`] /
    /// [`Self::LIST_CLOSE`] lift.
    ///
    /// Pre-lift the same `'\n'` byte lived inline at ONE site in
    /// `crate::reader::tokenize` — the line-comment discard loop's
    /// terminator check `if ch == '\n' { break; }`. Post-lift the
    /// (reader-discard terminator role, canonical byte) pairing binds
    /// at ONE constant on the [`Sexp`] algebra that the consumer site
    /// routes through; a refactor that ports the reader to a different
    /// line-break convention (e.g. Scheme R7RS `#;` datum-comment
    /// terminated at the next well-formed datum, an Emacs-style port
    /// with `\r\n` CRLF sequences, a Common-Lisp-style `#|…|#` block
    /// comment closed by `|#`) touches ONE constant (or extends the
    /// algebra by ONE peer method) rather than an inline byte.
    ///
    /// Reader-discard contract: `Sexp::COMMENT_TERM` MUST NOT surface
    /// as an atomic payload in any parsed [`Sexp`] — the reader's
    /// [`Self::COMMENT_LEAD`] outer-dispatch arm consumes every byte
    /// (INCLUDING this terminator) up to and including the FIRST
    /// occurrence of [`Self::COMMENT_TERM`], emitting NO token. The
    /// (lead, term) pair carries the SAME reader-discard invariant as
    /// (LIST_OPEN, LIST_CLOSE) does on the outer-structural axis: both
    /// bytes are structural markers that never appear in a token
    /// payload.
    ///
    /// Cross-axis disjointness with the sibling closed-set markers
    /// (pinned structurally at
    /// `sexp_comment_term_distinct_from_every_non_whitespace_algebra_marker`):
    /// `COMMENT_TERM`'s byte MUST differ from every NON-whitespace
    /// outer-marker char — [`Self::LIST_OPEN`], [`Self::LIST_CLOSE`],
    /// [`Self::COMMENT_LEAD`], [`Atom::STR_DELIMITER`],
    /// [`Atom::STR_ESCAPE_LEAD`], [`Atom::KEYWORD_MARKER`]'s lead byte,
    /// the two [`Atom::bool_literal`] spellings' lead byte, AND every
    /// [`QuoteForm::lead_char`] projection. The terminator IS a
    /// whitespace char (it satisfies `char::is_whitespace`) so the
    /// disjointness test explicitly excludes the whitespace-family
    /// axis: the terminator's role IS to be whitespace-family, so the
    /// disjointness contract binds only against the non-whitespace
    /// outer-marker axes.
    ///
    /// Interaction with the escape-decode codomain axis: the terminator
    /// byte `'\n'` COINCIDES with the C0 control byte
    /// [`Atom::decode_str_escape`]`('n')` produces — the two roles are
    /// distinct algebraic axes (reader-discard structural marker on
    /// the outer [`Sexp`] algebra vs. Str-escape shorthand codomain
    /// value on the inner [`Atom`] algebra) so the collision at the
    /// byte level is by design, NOT a disjointness violation. A `\n`
    /// byte APPEARING inside a `Token::Str` payload's decoded output
    /// (via `\n` shorthand) is orthogonal to a `\n` byte APPEARING as
    /// the line-comment terminator at the reader's outer-dispatch
    /// discard loop.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 2 — free middle; the
    /// (reader-discard terminator role, canonical `\n` byte) pairing
    /// binds at ONE constant on the closed-set outer [`Sexp`] algebra
    /// regardless of which consumer reaches in. THEORY.md §II.1
    /// invariant 5 — composition preserves proofs; the paired
    /// (COMMENT_LEAD, COMMENT_TERM) shape now lives at the algebra
    /// alongside (LIST_OPEN, LIST_CLOSE), so the reader-discard axis
    /// carries the SAME opener/closer discipline as the outer-
    /// structural axis. THEORY.md §VI.1 — generation over composition;
    /// the reader's inline `'\n'` char literal at the line-comment
    /// discard loop's terminator check collapses onto ONE named
    /// constant on the substrate algebra. THEORY.md §V.1 — knowable
    /// platform; the canonical line-comment terminator byte becomes
    /// a TYPE-level constant on the outer substrate algebra rather
    /// than an inline `'\n'` at one consumer surface in
    /// `crate::reader::tokenize`.
    pub const COMMENT_TERM: char = '\n';

    /// Canonical paired line-comment delimiter closed-set ALL array —
    /// composes [`Self::COMMENT_LEAD`] followed by [`Self::COMMENT_TERM`]
    /// in canonical (opener, terminator) declaration order, forced-arity
    /// `[char; 2]` so a hypothetical alternative comment convention (a
    /// Scheme R7RS `#;` datum-comment lead paired with a next-datum
    /// terminator, an Emacs-style CRLF paired terminator, a Common-Lisp
    /// `#|…|#` block comment closed by `|#`) would extend this array +
    /// one algebra constant per new row in lockstep — rustc's forced-
    /// arity check on `[char; N]` binds the extension through the array
    /// declaration site.
    ///
    /// Cross-axis peer to [`Self::LIST_DELIMITERS`] (`[char; 2]` on the
    /// outer-structural paired-delimiter axis of the SAME closed-set
    /// outer [`Sexp`] algebra) — both close a paired-role byte
    /// sub-vocabulary at the SAME shape (`[char; 2]`, `(opener,
    /// closer_or_terminator)` canonical declaration order) but on
    /// DISTINCT roles: [`Self::LIST_DELIMITERS`] closes the two typed
    /// constants that shape a [`Self::List`] payload
    /// ([`Self::LIST_OPEN`] / [`Self::LIST_CLOSE`], BOTH of which
    /// classify as bare-atom boundaries and both non-whitespace);
    /// [`Self::COMMENT_DELIMITERS`] closes the two typed constants that
    /// shape the reader's line-comment discard run
    /// ([`Self::COMMENT_LEAD`] / [`Self::COMMENT_TERM`], where the LEAD
    /// row is a bare-atom boundary AND non-whitespace, and the TERM row
    /// is a whitespace-family char absorbed by the reader's
    /// `ch.is_whitespace()` outer-dispatch arm rather than a distinct
    /// bare-atom boundary). The two arrays partition the SIX-category
    /// outer-dispatch arm-set into a per-axis paired shape (2 rows for
    /// list delimiters + 2 rows for comment delimiters + 1 row for
    /// [`Atom::STR_DELIMITER`] + 3-of-4 rows for [`QuoteForm::LEADS`] +
    /// the residual whitespace family), each axis carrying its own
    /// forced-arity ALL array.
    ///
    /// Also sibling-shape to [`Atom::SELF_ESCAPE_TABLE`] (`[char; 2]` on
    /// the inner-Str-payload self-escape sub-vocabulary axis of the
    /// closed-set [`Atom`] algebra), [`Atom::BOOL_LITERALS`]
    /// (`[&'static str; 2]` on the Scheme-bool spelling axis), and
    /// [`crate::error::UnquoteForm::MARKERS`] / [`crate::error::UnquoteForm::IAC_FORGE_TAGS`]
    /// (`[&'static str; 2]` on the template-substitution subset algebra
    /// — the 2-of-4 subset carving of [`QuoteForm`]) — every closed-set
    /// outer projection on the substrate that carries a paired-role
    /// two-row axis now pins its canonical bytes at ONE `pub const` per
    /// role plus a forced-arity ALL array for family-wide consumers.
    ///
    /// Pre-lift the two-element `[Self::COMMENT_LEAD, Self::COMMENT_TERM]`
    /// composition had NO typed source of truth on the substrate — the
    /// two constants each existed independently on the algebra
    /// ([`Self::COMMENT_LEAD`] shipped in the initial reader-discard
    /// lift; [`Self::COMMENT_TERM`] shipped in the follow-on paired-
    /// terminator lift `bb1bd5e`) and consumers that wanted the
    /// (opener, terminator) shape had to reach across the algebra
    /// through TWO `pub const` sites. Post-lift the paired-role
    /// sub-vocabulary binds at ONE forced-arity ALL array on the closed-
    /// set outer [`Sexp`] algebra alongside the peer
    /// [`Self::LIST_DELIMITERS`] array on the outer-structural axis; a
    /// consumer that walks EITHER axis of the outer-structural /
    /// reader-discard cross-product reads the paired-role identity off
    /// the shared `[char; 2]` shape.
    ///
    /// Structural invariant carried at the SHAPE level: [`char; 2`]
    /// pairs section-for-retraction one-to-one with
    /// [`Self::LIST_DELIMITERS`]'s `[char; 2]` — the two arrays sit at
    /// distinct roles on the SAME closed-set outer [`Sexp`] algebra
    /// (outer-structural payload-delimiter role for `LIST_DELIMITERS`;
    /// reader-discard opener/terminator role for `COMMENT_DELIMITERS`)
    /// but share the same forced-arity shape at their respective axes.
    /// A consumer that reaches for one of the two arrays encodes its
    /// axis's paired-role identity in the SHAPE it iterates rather than
    /// in a per-site convention.
    ///
    /// Composition law (round-trip): `COMMENT_DELIMITERS[0] ==
    /// Self::COMMENT_LEAD` AND `COMMENT_DELIMITERS[1] ==
    /// Self::COMMENT_TERM` AND `COMMENT_DELIMITERS.len() == 2`. The
    /// forced-arity + canonical declaration order together pin every
    /// downstream index-sweep consumer to the (opener, terminator)
    /// pairing at rustc time; a reorder without reordering the
    /// underlying algebra constants fails at the composition pin below.
    ///
    /// Path-uniformity contract pinned per-row: `COMMENT_DELIMITERS[0]`
    /// (the LEAD row) MUST classify as a bare-atom boundary via
    /// [`Self::is_bare_atom_boundary`] (the reader's outer-dispatch's
    /// dedicated line-comment arm is one of the SIX categories that
    /// projection covers), AND `COMMENT_DELIMITERS[1]` (the TERM row)
    /// MUST classify as a whitespace-family char via
    /// [`char::is_whitespace`] (the reader's `ch.is_whitespace()` arm
    /// absorbs the terminator so the discard loop's post-loop hand-off
    /// to the outer-dispatch fires the whitespace arm rather than a
    /// distinct comment-terminator arm). The per-row asymmetry is
    /// LOAD-BEARING and structurally distinct from
    /// [`Self::LIST_DELIMITERS`]'s BOTH-rows-are-bare-atom-boundaries
    /// contract (both `(` and `)` are non-whitespace outer-dispatch
    /// arms). Pinned by
    /// `sexp_comment_delimiters_lead_row_is_bare_atom_boundary` +
    /// `sexp_comment_delimiters_term_row_is_whitespace_family_char`.
    ///
    /// Cross-axis disjointness pinned structurally at
    /// `sexp_comment_delimiters_disjoint_from_list_delimiters`: no row
    /// of `COMMENT_DELIMITERS` aliases any row of
    /// [`Self::LIST_DELIMITERS`] — the reader-discard sub-vocabulary
    /// and the outer-structural list-delimiter sub-vocabulary partition
    /// their respective bytes disjointly on the SAME closed-set outer
    /// [`Sexp`] algebra. Cross-algebra disjointness pinned at
    /// `sexp_comment_delimiters_disjoint_from_str_delimiter`: no row
    /// aliases [`Atom::STR_DELIMITER`] — the reader-discard arm and the
    /// Str-payload arm partition their bytes across the two closed-set
    /// algebras disjointly.
    ///
    /// Future consumers that compose against [`Self::COMMENT_DELIMITERS`]:
    /// a hypothetical `tatara_lisp_comment_delimiter_total{delimiter=";"|"\n"}`
    /// Sekiban metric surface at Prometheus recording time — the
    /// label-set generator sweeps this array verbatim rather than
    /// re-typing the two paired bytes inline at each recorder, and
    /// rustc-binds the metric-label set to the closed set through the
    /// forced-arity ALL array; an LSP / structural-editor that
    /// highlights line-comment runs — the (opener, terminator) pair the
    /// editor spans over IS this array's two rows; a hypothetical
    /// `Sexp::BLOCK_COMMENT_DELIMITERS` peer array for a future
    /// `#|…|#` block-comment mode would follow the same shape
    /// mechanically, extending the reader-discard axis by ONE peer
    /// array without touching this one's shape.
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the paired
    /// (opener, terminator) reader-discard sub-vocabulary of the
    /// reader's outer-dispatch arm-set now binds at ONE typed `[char;
    /// 2]` array on the closed-set outer [`Sexp`] algebra rather than
    /// as two independent algebra constants (`Self::COMMENT_LEAD`,
    /// `Self::COMMENT_TERM`) accessed independently at every consumer
    /// that wants the paired-role shape. The shared `[char; 2]` shape
    /// with [`Self::LIST_DELIMITERS`] encodes the paired-role identity
    /// relation across the two axes of the SAME closed-set algebra at
    /// the type system level. THEORY.md §V.1 — knowable platform; the
    /// paired-discard-delimiter sub-vocabulary becomes load-bearing
    /// typed data on the closed-set outer [`Sexp`] algebra. THEORY.md
    /// §VI.1 — generation over composition; the paired-delimiter
    /// (opener + terminator) composition regenerates identically
    /// through this ONE typed forced-arity array rather than through
    /// two independent algebra constants at every consumer. THEORY.md
    /// §II.1 invariant 5 — composition preserves proofs; the two-axis
    /// (outer-structural, reader-discard) cross-product on the closed-
    /// set outer [`Sexp`] algebra now carries the SAME opener/closer
    /// discipline on BOTH axes through two forced-arity ALL arrays
    /// with byte-identical shape.
    pub const COMMENT_DELIMITERS: [char; 2] = [Self::COMMENT_LEAD, Self::COMMENT_TERM];

    /// Closed-set forced-arity ALL array over the SEVEN non-whitespace
    /// category-leading chars the reader's outer-dispatch cascade
    /// specialises on — the reader-level boundary sub-vocabulary that
    /// paired with `char::is_whitespace()` closes the six-clause
    /// [`Self::is_bare_atom_boundary`] disjunction. Composes through
    /// seven typed `pub const` primitives spanning THREE type namespaces
    /// on the SAME reader-outer-dispatch axis of the substrate:
    ///   * [`Self::LIST_OPEN`] (`'('`) — the outer-structural list-opening
    ///     delimiter on the outer [`Sexp`] algebra;
    ///   * [`Self::LIST_CLOSE`] (`')'`) — the outer-structural list-closing
    ///     delimiter on the outer [`Sexp`] algebra;
    ///   * [`QuoteForm::QUOTE_LEAD`] (`'\''`) — the [`QuoteForm::Quote`]
    ///     reader-punctuation lead byte on the quote-family sub-algebra;
    ///   * [`QuoteForm::QUASIQUOTE_LEAD`] (`` '`' ``) — the
    ///     [`QuoteForm::Quasiquote`] reader-punctuation lead byte;
    ///   * [`QuoteForm::UNQUOTE_LEAD`] (`','`) — the shared
    ///     [`QuoteForm::Unquote`] / [`QuoteForm::UnquoteSplice`] reader-
    ///     punctuation lead byte (disambiguated at the second-char peek
    ///     via [`QuoteForm::promote_via_next_char`]);
    ///   * [`Atom::STR_DELIMITER`] (`'"'`) — the Str-payload opening /
    ///     closing delimiter on the closed-set [`Atom`] algebra;
    ///   * [`Self::COMMENT_LEAD`] (`';'`) — the line-comment opener on
    ///     the outer [`Sexp`] algebra (paired with [`Self::COMMENT_TERM`]
    ///     inside the discard loop — but the TERM is a run-boundary
    ///     marker inside a comment run, NOT a reader-outer-dispatch
    ///     category-leading char, so it is intentionally omitted from
    ///     this ALL array).
    ///
    /// Cross-axis peer to [`Self::LIST_DELIMITERS`] (`[char; 2]` on the
    /// outer-structural payload-delimiter axis) and [`Self::COMMENT_DELIMITERS`]
    /// (`[char; 2]` on the reader-discard opener/terminator axis) at
    /// ONE algebra level up: those two arrays close their respective
    /// paired-role sub-vocabularies (opener + closer, opener + terminator)
    /// on the reader-INNER axis of the outer [`Sexp`] algebra; this
    /// array closes the reader-OUTER-dispatch category-leading char
    /// sub-vocabulary across the SAME closed-set outer [`Sexp`] algebra
    /// PLUS its two sibling sub-algebras ([`QuoteForm`], [`Atom`]) at
    /// ONE family-wide `[char; 7]` primitive. Sibling-shape peer of the
    /// intra-algebra sub-vocabulary array [`QuoteForm::LEADS`]
    /// (`[char; 3]` — the three DISTINCT quote-family reader-lead
    /// bytes) which this array embeds as its middle three positions:
    /// where [`QuoteForm::LEADS`] closes the quote-family sub-carving's
    /// reader-lead sub-vocabulary at ONE forced-arity array on ONE
    /// closed-set algebra, this array closes the FULL reader-outer-
    /// dispatch non-whitespace category-leading char sub-vocabulary at
    /// ONE forced-arity array on the outer [`Sexp`] algebra by
    /// composing through the three-arm quote-family sub-carving + the
    /// two-arm structural-delimiter sub-carving + the two-arm atomic-
    /// carve delimiter + comment-lead singletons.
    ///
    /// Pre-lift the seven category-leading chars had NO family-wide
    /// array on the outer [`Sexp`] algebra — [`Self::is_bare_atom_boundary`]
    /// carried them as three sub-expressions (`Self::LIST_DELIMITERS.contains(&ch)`
    /// on the structural-delimiter axis, `QuoteForm::from_lead_char(ch).is_some()`
    /// on the quote-family axis, `ch == Atom::STR_DELIMITER || ch ==
    /// Self::COMMENT_LEAD` on the singleton axes) unified through boolean
    /// disjunction. Post-lift the WHOLE non-whitespace terminator sub-
    /// vocabulary binds at ONE `pub const [char; 7]` array on the outer
    /// [`Sexp`] algebra so [`Self::is_bare_atom_boundary`] collapses to
    /// `ch.is_whitespace() || Self::NON_WHITESPACE_BARE_ATOM_TERMINATORS.contains(&ch)`
    /// — TWO clauses (one whitespace-partial predicate + one
    /// contains-check on the family-wide ARRAY) rather than five
    /// sub-clauses spanning three type namespaces. Consumers keyed on
    /// the whole family (a `tatara-check` predicate `(check-reader-
    /// outer-dispatch-terminator-partition-injective …)` that verifies
    /// the seven-arm partition structurally, a future REPL / LSP
    /// tokenizer-boundary hint that scans the source for the reader-
    /// outer-dispatch category-leading chars upfront, a future
    /// completion generator that suggests the seven bytes at every
    /// bare-atom-lexeme insertion site) read through
    /// [`Self::NON_WHITESPACE_BARE_ATOM_TERMINATORS`] without re-deriving
    /// the three-part sub-expression composition inline.
    ///
    /// Composition law (forward): for every `ch: char`,
    /// `Self::NON_WHITESPACE_BARE_ATOM_TERMINATORS.contains(&ch) ==
    /// (Self::LIST_DELIMITERS.contains(&ch) ||
    ///  QuoteForm::from_lead_char(ch).is_some() ||
    ///  ch == Atom::STR_DELIMITER || ch == Self::COMMENT_LEAD)` — pinned
    /// by `sexp_non_whitespace_bare_atom_terminators_agree_with_pre_lift_sub_expression_disjunction`.
    /// Boundary-predicate composition law:
    /// `Self::is_bare_atom_boundary(ch) == (ch.is_whitespace() ||
    /// Self::NON_WHITESPACE_BARE_ATOM_TERMINATORS.contains(&ch))` —
    /// pinned by `sexp_is_bare_atom_boundary_agrees_with_terminators_array_on_non_whitespace_partition`.
    ///
    /// Adding a hypothetical seventh reader-outer-dispatch category
    /// (e.g. `#|…|#` block-comment lead byte, `#\` char-literal prefix,
    /// `#[` vector-literal prefix — each pinning a new lead byte on
    /// [`Self`] or a fresh sub-algebra) extends this array AND
    /// [`Self::is_bare_atom_boundary`]'s indirect coverage in
    /// LOCKSTEP — rustc's forced-arity check on `[char; 7]` fails
    /// compilation if the algebra grows without the array (or the
    /// array without the algebra).
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 2 — free middle; the
    /// (reader-outer-dispatch category, canonical char) family-wide
    /// pairing binds at ONE typed `[char; 7]` array on the outer
    /// [`Sexp`] algebra regardless of which of the three sub-algebras
    /// the individual chars name their per-role `pub const` primitive
    /// on. THEORY.md §III — the typescape; the seven canonical
    /// reader-outer-dispatch category-leading bytes bind at ONE typed
    /// `[char; 7]` array on the outer [`Sexp`] algebra rather than at
    /// three-part sub-expression composition inline at
    /// [`Self::is_bare_atom_boundary`]. 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 seven chars. THEORY.md §VI.1 — generation over
    /// composition; the family-wide contract sweeps (routing through
    /// typed sub-algebra `pub const` primitives, pairwise distinctness,
    /// agreement with the pre-lift sub-expression disjunction) emerge
    /// from the composition of EIGHT substrate primitives (this
    /// `pub const [char; 7]` array + the seven sub-algebra `pub const`
    /// primitives) rather than as inline disjunctions at each call site.
    pub const NON_WHITESPACE_BARE_ATOM_TERMINATORS: [char; 7] = [
        Self::LIST_OPEN,
        Self::LIST_CLOSE,
        QuoteForm::QUOTE_LEAD,
        QuoteForm::QUASIQUOTE_LEAD,
        QuoteForm::UNQUOTE_LEAD,
        Atom::STR_DELIMITER,
        Self::COMMENT_LEAD,
    ];

    /// Reader-level boundary predicate — returns `true` iff `ch` is one
    /// of the SIX outer-dispatch category-leading chars the reader's
    /// tokenizer specialises on: whitespace, [`Self::LIST_OPEN`],
    /// [`Self::LIST_CLOSE`], any [`QuoteForm::lead_char`] (via the
    /// closed-set [`QuoteForm::from_lead_char`] decode),
    /// [`Atom::STR_DELIMITER`], AND [`Self::COMMENT_LEAD`]. The ONE
    /// typed projection on the outer [`Sexp`] algebra that names the
    /// disjunction of "the char would start a NEW reader-level token
    /// (or a discarded run) rather than feed the current bare-atom
    /// accumulator."
    ///
    /// Structural dual of the reader's outer-dispatch cascade in
    /// `crate::reader::tokenize`: the outer-dispatch has FIVE specific
    /// arms (`ws if ws.is_whitespace()`, `Self::COMMENT_LEAD`,
    /// `Self::LIST_OPEN`, `Self::LIST_CLOSE`, `Atom::STR_DELIMITER`)
    /// plus ONE pre-match `QuoteForm::from_lead_char(c).is_some()`
    /// gate — SIX categories in total. The default `_ => { …
    /// bare-atom accumulator … }` arm fires EXACTLY when every specific
    /// arm rejects. This method is the typed projection of that
    /// implicit disjunction: `Sexp::is_bare_atom_boundary(ch) == true`
    /// iff `ch` would trigger one of the SIX specific arms, and
    /// `false` iff `ch` would fall through to the bare-atom
    /// accumulator's default arm. The two consumer sites in
    /// `crate::reader::tokenize` — the outer-dispatch's implicit "no
    /// specific arm fires" residual predicate AND the bare-atom
    /// accumulator's terminator disjunct — now share ONE typed source
    /// of truth on the closed-set outer [`Sexp`] algebra.
    ///
    /// Pre-lift the SIX-clause boolean chain
    /// (`ch.is_whitespace() || ch == Sexp::LIST_OPEN || ch ==
    /// Sexp::LIST_CLOSE || QuoteForm::from_lead_char(ch).is_some() ||
    /// ch == Atom::STR_DELIMITER || ch == Sexp::COMMENT_LEAD`) lived
    /// inline at the bare-atom accumulator's terminator gate in
    /// `crate::reader::tokenize`, spanning THREE type namespaces
    /// ([`Sexp`], [`Atom`], [`QuoteForm`]) at ONE consumer site.
    /// Post-lift the WHOLE disjunction binds at ONE typed projection
    /// on the outer [`Sexp`] algebra so a refactor that adds a
    /// SEVENTH outer-dispatch category (e.g. `#|…|#` block-comment
    /// lead byte, `#\` char-literal prefix, `#[` vector-literal
    /// prefix) extends the algebra ONCE (via a new arm on THIS method
    /// AND a matching outer-dispatch arm in the reader) rather than
    /// mutating an inline six-clause boolean chain that would silently
    /// drift out of tokenizer agreement if one clause was added
    /// without the other. Sibling-shape peer of the outer-dispatch's
    /// closed-set per-category projections
    /// ([`QuoteForm::from_lead_char`] on the quote-family axis;
    /// [`Atom::decode_str_escape`] on the Str-escape axis): where those
    /// two methods each lift ONE outer-dispatch category's decode onto
    /// its typed algebra, THIS method lifts the DISJUNCTION of ALL SIX
    /// outer-dispatch categories onto the outer [`Sexp`] algebra as
    /// a bool predicate.
    ///
    /// Composition law (forward): for every char `ch` and every
    /// substrate-marker enumeration
    /// `Self::{LIST_OPEN, LIST_CLOSE, COMMENT_LEAD}`,
    /// `Atom::STR_DELIMITER`, `QuoteForm::from_lead_char(ch).is_some()`,
    /// `is_bare_atom_boundary` returns `true`; for every char that
    /// isn't whitespace AND isn't listed on any marker axis, returns
    /// `false`. Reader-level composition law:
    /// `read(format!("foo{ch}"))` tokenizes as `[Token::Atom("foo"),
    /// …trailing token(s) from `ch`]` when
    /// `Self::is_bare_atom_boundary(ch)` is `true`, and as
    /// `[Token::Atom(format!("foo{ch}"))]` (ONE token) when it is
    /// `false`.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 2 — free middle; the
    /// (reader-level boundary role, canonical char) pairing binds at
    /// ONE typed projection on the outer [`Sexp`] algebra regardless
    /// of which of the SIX outer-dispatch category-leading chars is
    /// under test. THEORY.md §VI.1 — generation over composition; a
    /// SIX-clause inline boolean disjunction spanning THREE type
    /// namespaces collapses onto ONE named method — the substrate's
    /// three-times rule saturated at the outer-dispatch's disjunction.
    /// THEORY.md §V.1 — knowable platform; the canonical reader-level
    /// boundary predicate becomes a TYPE-level method on the outer
    /// substrate algebra rather than an inline six-clause boolean
    /// chain at ONE consumer site inside `crate::reader::tokenize`.
    #[must_use]
    pub fn is_bare_atom_boundary(ch: char) -> bool {
        ch.is_whitespace() || Self::NON_WHITESPACE_BARE_ATOM_TERMINATORS.contains(&ch)
    }

    /// Canonical [`Self::Atom`]-[`Atom::Symbol`] outer constructor —
    /// composes [`Atom::symbol`] (the typed-construct method on the
    /// closed-set [`Atom`] algebra) under the [`Self::Atom`] outer
    /// wrapper. The first of six `Self::Atom(Atom::X(_))` outer
    /// constructors all routing through the typed [`Atom`] construct
    /// family at the inner algebra so the `.into()` coercion + tuple-
    /// variant constructor pair lives at ONE site per kind on the
    /// [`Atom`] algebra rather than at this outer constructor's body.
    /// Sibling-shape lift to the [`Atom::as_X`] /
    /// [`Self::as_X`] composition through [`Self::as_atom`] on the
    /// projection axis: where projections route OUTER `Self::as_X`
    /// through `self.as_atom().and_then(Atom::as_X)`, constructions
    /// route OUTER `Self::X` through `Self::Atom(Atom::X(payload))`.
    ///
    /// Composition law (forward): `Sexp::symbol(s) ==
    /// Sexp::Atom(Atom::symbol(s))` for every `s: impl Into<String>`.
    /// Round-trip law (with the soft-projection sibling): for every
    /// `s: &str`, `Sexp::symbol(s).as_symbol() == Some(s)` — the inner
    /// algebra's section-for-retraction surfaces through the outer
    /// algebra without re-derivation. Same posture across the six
    /// sibling pairs.
    #[must_use]
    pub fn symbol(s: impl Into<String>) -> Self {
        Self::Atom(Atom::symbol(s))
    }
    /// Canonical [`Self::Atom`]-[`Atom::Keyword`] outer constructor —
    /// composes [`Atom::keyword`] under [`Self::Atom`]. See
    /// [`Self::symbol`] for the outer-algebra docstring.
    #[must_use]
    pub fn keyword(s: impl Into<String>) -> Self {
        Self::Atom(Atom::keyword(s))
    }
    /// Canonical [`Self::Atom`]-[`Atom::Str`] outer constructor —
    /// composes [`Atom::string`] under [`Self::Atom`].
    #[must_use]
    pub fn string(s: impl Into<String>) -> Self {
        Self::Atom(Atom::string(s))
    }
    /// Canonical [`Self::Atom`]-[`Atom::Int`] outer constructor —
    /// composes [`Atom::int`] under [`Self::Atom`].
    #[must_use]
    pub fn int(n: i64) -> Self {
        Self::Atom(Atom::int(n))
    }
    /// Canonical [`Self::Atom`]-[`Atom::Float`] outer constructor —
    /// composes [`Atom::float`] under [`Self::Atom`].
    #[must_use]
    pub fn float(n: f64) -> Self {
        Self::Atom(Atom::float(n))
    }
    /// Canonical [`Self::Atom`]-[`Atom::Bool`] outer constructor —
    /// composes [`Atom::boolean`] under [`Self::Atom`].
    #[must_use]
    pub fn boolean(b: bool) -> Self {
        Self::Atom(Atom::boolean(b))
    }

    /// Canonical [`Self::Quote`] outer constructor — composes
    /// [`QuoteForm::wrap`] on the [`QuoteForm::Quote`] marker so the
    /// `Box::new(inner)` allocation + tuple-variant pair lives at ONE
    /// site on the closed-set [`QuoteForm`] algebra rather than at
    /// this outer-constructor body. The first of four `Self::Quote*`
    /// outer constructors all routing through the typed
    /// [`QuoteForm::wrap`] family at the inner algebra — the
    /// quote-family-axis section peer of the six `Self::Atom(Atom::X(_))`
    /// outer constructors ([`Self::symbol`], [`Self::keyword`],
    /// [`Self::string`], [`Self::int`], [`Self::float`],
    /// [`Self::boolean`]) all routing through the typed [`Atom`]
    /// construct family on the atomic-payload axis. Sibling-shape lift
    /// to the [`Self::as_quote_form`] soft-projection sibling on the
    /// projection axis: where the projection soft-decomposes a
    /// quote-family wrapper into `Option<(QuoteForm, &Sexp)>` (surfacing
    /// the typed marker alongside the borrowed inner body), each of
    /// these four typed constructors embeds a fresh inner body under
    /// the typed marker into the matching tuple-variant wrapper.
    ///
    /// Composition law (forward): `Sexp::quote(inner) ==
    /// QuoteForm::Quote.wrap(inner) == Sexp::Quote(Box::new(inner))`
    /// for every `inner: Sexp`. Round-trip law (section-for-retraction
    /// with the soft-projection sibling): `Sexp::quote(inner)
    /// .as_quote_form() == Some((QuoteForm::Quote, &inner))` for every
    /// `inner: Sexp` — the inner algebra's typed constructor pairs
    /// section-for-retraction with the outer algebra's soft
    /// projection, and the marker + inner body cross-projection
    /// preserves identity. Same posture across the four sibling
    /// pairs (`Sexp::quote` / `Sexp::quasiquote` / `Sexp::unquote` /
    /// `Sexp::unquote_splice`).
    ///
    /// Pre-lift the `Self::Quote(Box::new(inner))` welded triple
    /// (`Self::Quote`, `Box::new`, `inner`) appeared inline at every
    /// consumer that builds a quote-family wrapper — well past the ≥2
    /// PRIME-DIRECTIVE trigger once the structural shape is named. The
    /// welded triple already lives at ONE site on the closed-set
    /// [`QuoteForm::wrap`] algebra for the marker-driven consumer path;
    /// this outer constructor binds the per-variant `Sexp::X(Box::new(
    /// inner))` welded triple to ONE typed-algebra method per marker on
    /// the outer [`Sexp`] algebra, so consumers that know the marker at
    /// compile time bind to the typed method directly rather than
    /// re-deriving the `Self::X(Box::new(_))` pair inline. A future
    /// allocation-policy change (e.g. arena-allocated wrappers for
    /// span-aware [`Sexp`]) lands as ONE edit at [`QuoteForm::wrap`]
    /// (the single site the allocation composition lives) and
    /// propagates through these four typed constructors byte-for-byte.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 2 — free middle; the
    /// (QuoteForm variant, [`Sexp`] tuple-variant constructor) pairing
    /// binds at ONE typed-algebra method per marker on the outer
    /// [`Sexp`] algebra regardless of which consumer reaches in.
    /// THEORY.md §VI.1 — generation over composition; the welded
    /// `Self::X(Box::new(_))` triple at every quote-family construct
    /// site regenerates through `QuoteForm::X.wrap(_)` composition over
    /// the typed algebra rather than per-site re-derivation. THEORY.md
    /// §V.1 — knowable platform; the typed-construct family becomes a
    /// TYPE projection on the substrate's outer [`Sexp`] algebra sitting
    /// next to the typed-project family [`Self::as_quote_form`] rather
    /// than as bare tuple-variant constructor + per-site `Box::new`
    /// discipline. A future fifth homoiconic prefix syntax (e.g. syntax
    /// quotation `#'x` for hygienic macros) extends [`QuoteForm::ALL`] +
    /// [`QuoteForm::wrap`]'s arm + this construct family in lockstep,
    /// rustc-enforced through the closed-set exhaustiveness.
    ///
    /// Frontier inspiration: Racket's `(quote x)` /
    /// `(quasiquote x)` / `(unquote x)` / `(unquote-splicing x)` typed
    /// syntactic-form construct face paired one-for-one with the
    /// [`Self::as_quote_form`] closed-set soft-projection sibling on
    /// the outer syntax algebra — the typed-construct + typed-project
    /// algebra dual is closed at one method per direction per marker
    /// on Racket's surface, and the [`Self::quote`] /
    /// [`Self::quasiquote`] / [`Self::unquote`] / [`Self::unquote_splice`]
    /// family is the Rust-typed peer on the closed-set outer [`Sexp`]
    /// algebra with [`QuoteForm::wrap`] standing in for Racket's typed
    /// dispatch face. MLIR's `mlir::OpBuilder::create<QuoteOp>(loc,
    /// inner)` typed-IR wrapper construction paired with
    /// `mlir::dyn_cast<QuoteOp>(op)` on the projection face — the typed
    /// factory + typed downcast pair the IR algebra closes over on
    /// every wrapper op; [`Self::quote`] / [`Self::as_quote_form`] is
    /// the Rust-typed peer on the outer [`Sexp`] algebra with the
    /// closed-set [`QuoteForm`] standing in for MLIR's `OperationName`
    /// taxonomy over the wrapper-op family.
    #[must_use]
    pub fn quote(inner: Sexp) -> Self {
        QuoteForm::Quote.wrap(inner)
    }
    /// Canonical [`Self::Quasiquote`] outer constructor — composes
    /// [`QuoteForm::wrap`] on the [`QuoteForm::Quasiquote`] marker.
    /// See [`Self::quote`] for the outer-algebra docstring.
    #[must_use]
    pub fn quasiquote(inner: Sexp) -> Self {
        QuoteForm::Quasiquote.wrap(inner)
    }
    /// Canonical [`Self::Unquote`] outer constructor — composes
    /// [`QuoteForm::wrap`] on the [`QuoteForm::Unquote`] marker.
    /// See [`Self::quote`] for the outer-algebra docstring.
    #[must_use]
    pub fn unquote(inner: Sexp) -> Self {
        QuoteForm::Unquote.wrap(inner)
    }
    /// Canonical [`Self::UnquoteSplice`] outer constructor — composes
    /// [`QuoteForm::wrap`] on the [`QuoteForm::UnquoteSplice`] marker.
    /// See [`Self::quote`] for the outer-algebra docstring.
    #[must_use]
    pub fn unquote_splice(inner: Sexp) -> Self {
        QuoteForm::UnquoteSplice.wrap(inner)
    }

    /// Canonical marker-driven quote-family outer constructor — routes
    /// through [`QuoteForm::wrap`] on the caller-supplied [`QuoteForm`]
    /// marker at ONE site on the closed-set [`Sexp`] algebra. The outer-
    /// algebra section-for-retraction sibling of the existing
    /// [`Self::as_quote_form`] soft-projection ([`Option<(QuoteForm,
    /// &Sexp)>`]): where the projection soft-decomposes a quote-family
    /// wrapper into its typed [`QuoteForm`] marker + borrowed inner body
    /// on the (marker, borrowed-inner) product, this constructor embeds
    /// a typed [`QuoteForm`] marker + owned inner body pair into the
    /// matching tuple-variant wrapper on the (marker, owned-inner)
    /// product. Marker-driven parent of the four per-variant siblings
    /// [`Self::quote`] / [`Self::quasiquote`] / [`Self::unquote`] /
    /// [`Self::unquote_splice`] — each of the four is `Self::quote_form(
    /// QuoteForm::X, inner)` restricted to a compile-time-known marker;
    /// this constructor is the marker-abstracted parent every consumer
    /// that binds the marker as a runtime value routes through.
    ///
    /// Sibling posture across the outer-algebra construct-family layer:
    /// where [`Self::call`](Self::call) and [`Self::named_call`](Self::named_call)
    /// close the (construct, project) dual on the call-form + named-
    /// call-form typed decompositions of the residual-axis List arm,
    /// and [`Self::list`](Self::list) closes it on the residual-axis
    /// List arm itself, this constructor closes it on the quote-family-
    /// axis wrapper decomposition — the outer [`Sexp`] algebra now
    /// carries a (marker, project) construct-family dual pair for every
    /// axis of the [`SexpShape`] closed set at ONE typed method per
    /// corner, with `Sexp::quote_form(qf, inner)` as the marker-driven
    /// quote-family construct entry and [`Self::as_quote_form`] as its
    /// marker-recovering projection sibling.
    ///
    /// Composition law (forward): `Sexp::quote_form(marker, inner) ==
    /// marker.wrap(inner)` for every `marker: QuoteForm` and every
    /// `inner: Sexp`. The body routes through the SAME closed-set
    /// `QuoteForm::wrap` method the four per-variant siblings
    /// ([`Self::quote`] / [`Self::quasiquote`] / [`Self::unquote`] /
    /// [`Self::unquote_splice`]) already reach for, so the (marker,
    /// [`Sexp`] tuple-variant constructor) pairing binds at ONE closed-
    /// set match on the substrate algebra — a regression that drifts
    /// one consumer's marker→wrapper mapping from the others (e.g. a
    /// copy-edit that pairs [`QuoteForm::Quote`] with the
    /// [`Sexp::Quasiquote`] tuple variant, or that drops a
    /// [`QuoteForm::UnquoteSplice`] value through the
    /// [`Sexp::Unquote`] tuple variant) cannot reach the substrate's
    /// runtime.
    ///
    /// Round-trip law (section-for-retraction with the outer-algebra
    /// soft-projection): for every `marker: QuoteForm` and every
    /// `inner: Sexp`, `Sexp::quote_form(marker, inner.clone())
    /// .as_quote_form() == Some((marker, &inner))` — the outer
    /// algebra's marker-driven quote-family constructor pairs section-
    /// for-retraction with the outer algebra's soft quote-family
    /// projection, and the (marker, inner body) cross-projection
    /// preserves identity for every `QuoteForm` variant.
    ///
    /// Marker-recovering projection composition: `Sexp::quote_form(
    /// marker, inner).as_quote_form_marker() == Some(marker)` for every
    /// input — the marker-only projection sibling
    /// ([`Self::as_quote_form_marker`]) recovers the constructor's
    /// marker byte-for-byte. Outer-shape composition law:
    /// `Sexp::quote_form(marker, inner).shape() == marker.sexp_shape()`
    /// — the outer-shape identity binds through the typed-shape lattice
    /// at ONE arm per [`QuoteForm`] variant, symmetric with the atomic
    /// construct family's `Sexp::X_atom(payload).shape() ==
    /// AtomKind::X.sexp_shape()` composition and the residual construct
    /// family's `Sexp::list(items).shape() == SexpShape::List`
    /// composition.
    ///
    /// Per-variant restriction laws (structural identity between the
    /// marker-driven parent + the four per-variant siblings):
    ///   * `Sexp::quote_form(QuoteForm::Quote, inner) == Sexp::quote(inner)`
    ///   * `Sexp::quote_form(QuoteForm::Quasiquote, inner) == Sexp::quasiquote(inner)`
    ///   * `Sexp::quote_form(QuoteForm::Unquote, inner) == Sexp::unquote(inner)`
    ///   * `Sexp::quote_form(QuoteForm::UnquoteSplice, inner) == Sexp::unquote_splice(inner)`
    ///
    /// The four per-variant constructors ARE the marker-driven parent
    /// specialized on a compile-time-known marker; the marker-abstracted
    /// parent binds every consumer that routes a runtime `QuoteForm`
    /// value through a quote-family construct to ONE typed method on
    /// the outer [`Sexp`] algebra rather than a four-arm inline
    /// `match qf { QuoteForm::X => Sexp::x(inner), … }` dispatch.
    ///
    /// Pre-lift consumers with a runtime `QuoteForm` marker routed
    /// through `marker.wrap(inner)` directly (the reader's
    /// `read_quoted` production consumer at `reader.rs`, the domain
    /// module's quote-family round-trip test site) — well past the ≥2
    /// PRIME-DIRECTIVE trigger once the marker-driven pattern is
    /// named. Post-lift consumers bind to ONE typed-algebra method on
    /// the outer [`Sexp`] algebra sitting next to the typed-project
    /// family ([`Self::as_quote_form`] / [`Self::as_quote_form_marker`])
    /// rather than reaching into the closed-set [`QuoteForm::wrap`]
    /// method directly. A future allocation-policy change (e.g. arena-
    /// allocated wrappers for span-aware [`Sexp`]) lands as ONE edit at
    /// the single [`QuoteForm::wrap`] composition site and propagates
    /// through this constructor byte-for-byte.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 1 — typed entry; the
    /// (typed [`QuoteForm`] marker, owned inner body, [`QuoteForm::wrap`]
    /// composition) triple binds at ONE typed-algebra method on the
    /// outer [`Sexp`] algebra, closing the marker-driven quote-family
    /// (construct, project) algebra dual pair with
    /// [`Self::as_quote_form`] on the projection side. THEORY.md §II.1
    /// invariant 2 — free middle; every consumer that has a runtime
    /// [`QuoteForm`] marker + an owned inner body and wants to build a
    /// quote-family wrapper routes through the SAME typed method, so a
    /// regression that drifts one consumer's marker→wrapper mapping
    /// cannot reach the substrate's runtime. THEORY.md §V.1 — knowable
    /// platform; the marker-driven quote-family typed-construct becomes
    /// a TYPE projection on the substrate's outer [`Sexp`] algebra
    /// sitting next to the typed-project family
    /// [`Self::as_quote_form`] / [`Self::as_quote_form_marker`] rather
    /// than the closed-set [`QuoteForm::wrap`] method threaded as a
    /// method call on a bound-marker value. THEORY.md §VI.1 —
    /// generation over composition; the marker-driven quote-family
    /// pair emerges from ONE typed-algebra composition through
    /// [`QuoteForm::wrap`] rather than from per-consumer marker→wrapper
    /// dispatch literals; a future fifth homoiconic prefix syntax
    /// (e.g. `#'x` for hygienic macros) extends [`QuoteForm::ALL`] +
    /// [`QuoteForm::wrap`]'s match arm + [`Self::as_quote_form`]'s
    /// match arm in lockstep — rustc-enforced through the closed-set
    /// exhaustiveness — with THIS constructor inheriting the extension
    /// through the [`QuoteForm::wrap`] composition site without a per-
    /// site edit.
    ///
    /// Frontier inspiration: Racket's `(datum->syntax stx (list #'qf
    /// inner))` marker-abstracted quote-family construct paired one-
    /// for-one with `syntax-e` on the projection face — the typed-
    /// construct + typed-project algebra dual is closed on Racket's
    /// syntax algebra at one method per direction, and
    /// `Sexp::quote_form` / `Sexp::as_quote_form` is the Rust-typed peer
    /// on the closed-set outer [`Sexp`] algebra with [`QuoteForm`]
    /// standing in for Racket's syntactic-form taxonomy over the four
    /// homoiconic prefix wrappers. MLIR's typed-IR
    /// `mlir::OpBuilder::create(loc, OperationName, operands)` marker-
    /// driven op construction paired with `mlir::Operation::getName()`
    /// on the projection face — the typed factory + typed downcast pair
    /// the IR algebra closes over on every op kind at one method per
    /// direction; `Sexp::quote_form` / [`Self::as_quote_form_marker`]
    /// is the Rust-typed peer on the outer [`Sexp`] algebra with the
    /// closed-set [`QuoteForm`] standing in for MLIR's `OperationName`
    /// taxonomy over the four homoiconic prefix-wrapper op kinds.
    #[must_use]
    pub fn quote_form(marker: QuoteForm, inner: Sexp) -> Self {
        marker.wrap(inner)
    }

    /// Canonical marker-driven template-substitution outer constructor —
    /// routes through [`UnquoteForm::wrap`] on the caller-supplied
    /// [`UnquoteForm`] marker at ONE site on the closed-set [`Sexp`]
    /// algebra. Subset-algebra peer of the marker-driven quote-family
    /// parent [`Self::quote_form`]: where [`Self::quote_form`] embeds a
    /// caller-supplied [`QuoteForm`] marker + owned inner body on the
    /// 4-of-12 quote-family carving through the closed-set
    /// [`QuoteForm::wrap`] composition site, THIS constructor embeds a
    /// caller-supplied [`UnquoteForm`] marker + owned inner body on the
    /// 2-of-12 template-substitution subset carving through the
    /// [`UnquoteForm::wrap`] composition site (which itself composes
    /// [`UnquoteForm::to_quote_form`] then [`QuoteForm::wrap`], so the
    /// welded `Sexp::X(Box::new(_))` triple ultimately still binds at
    /// the ONE canonical [`QuoteForm::wrap`] site the four per-variant
    /// siblings [`Self::quote`] / [`Self::quasiquote`] / [`Self::unquote`]
    /// / [`Self::unquote_splice`] and the marker-driven parent
    /// [`Self::quote_form`] all route through). Closes the (construct,
    /// project) algebra dual on the (`UnquoteForm`, `Sexp`) product
    /// against the pre-existing projection sibling [`Self::as_unquote`]
    /// (soft-decomposition into `Option<(UnquoteForm, &Sexp)>`) and its
    /// marker-only peer [`Self::as_unquote_form`] (soft-decomposition
    /// into `Option<UnquoteForm>`) — post-lift the outer [`Sexp`]
    /// algebra carries a marker-driven (construct, project) dual pair
    /// `Sexp::unquote_form` / `Sexp::as_unquote` at ONE typed method per
    /// direction on the template-substitution subset alongside the
    /// marker-only projection sibling [`Self::as_unquote_form`],
    /// symmetric with the pair `Sexp::quote_form` / `Sexp::as_quote_form`
    /// / `Sexp::as_quote_form_marker` the superset carries.
    ///
    /// Sibling posture across the outer-algebra construct-family layer:
    /// where [`Self::call`](Self::call) and [`Self::named_call`](Self::named_call)
    /// close the (construct, project) dual on the call-form + named-call-
    /// form typed decompositions of the residual-axis List arm,
    /// [`Self::list`](Self::list) closes it on the residual-axis List
    /// arm itself, and [`Self::quote_form`](Self::quote_form) closes it
    /// on the quote-family-axis marker-driven decomposition (the parent
    /// 4-of-12 quote-family carving), THIS constructor closes it on the
    /// template-substitution-subset marker-driven decomposition (the
    /// 2-of-4 subset of the quote-family carving, equivalently the
    /// 2-of-12 substitution carving of the outer [`SexpShape`] closed
    /// set) — the outer [`Sexp`] algebra now carries a marker-driven
    /// construct-family dual pair for every closed-set carving on the
    /// quote-family axis at ONE typed method per corner.
    ///
    /// Composition law (forward): `Sexp::unquote_form(marker, inner) ==
    /// marker.wrap(inner)` for every `marker: UnquoteForm` and every
    /// `inner: Sexp`. The body routes through the SAME
    /// [`UnquoteForm::wrap`] method the subset-algebra consumer path
    /// already reaches for, so the (subset marker, [`Sexp`] tuple-variant
    /// wrapper) pairing binds at ONE closed-set composition site on the
    /// substrate — a regression that drifts one consumer's subset
    /// marker → wrapper mapping from the others (e.g. a copy-edit that
    /// pairs [`UnquoteForm::Unquote`] with the [`Sexp::UnquoteSplice`]
    /// tuple variant, or that drops a [`UnquoteForm::Splice`] value
    /// through the [`Sexp::Unquote`] tuple variant) cannot reach the
    /// substrate's runtime.
    ///
    /// Round-trip law (section-for-retraction with the outer-algebra
    /// soft-projection): for every `marker: UnquoteForm` and every
    /// `inner: Sexp`, `Sexp::unquote_form(marker, inner.clone())
    /// .as_unquote() == Some((marker, &inner))` — the outer algebra's
    /// marker-driven template-substitution constructor pairs section-
    /// for-retraction with the outer algebra's soft template-substitution
    /// projection, and the (subset marker, inner body) cross-projection
    /// preserves identity for every [`UnquoteForm`] variant.
    ///
    /// Marker-recovering projection composition: `Sexp::unquote_form(
    /// marker, inner).as_unquote_form() == Some(marker)` for every input
    /// — the marker-only projection sibling [`Self::as_unquote_form`]
    /// recovers the constructor's subset marker byte-for-byte. Outer-
    /// shape composition law: `Sexp::unquote_form(marker, inner).shape()
    /// == marker.sexp_shape()` — the outer-shape identity binds through
    /// the typed-shape lattice at ONE arm per [`UnquoteForm`] variant,
    /// symmetric with the quote-family construct family's
    /// `Sexp::quote_form(marker, inner).shape() == marker.sexp_shape()`
    /// composition and the atomic construct family's
    /// `Sexp::X_atom(payload).shape() == AtomKind::X.sexp_shape()`
    /// composition. Superset-routing composition law:
    /// `Sexp::unquote_form(marker, inner) == Sexp::quote_form(
    /// marker.to_quote_form(), inner)` for every input — the subset-
    /// algebra construct routes through the same closed-set
    /// [`QuoteForm::wrap`] composition site the superset construct
    /// routes through, threaded via the typed 2-of-4 subset → superset
    /// projection [`UnquoteForm::to_quote_form`]. A regression that
    /// drifts either direction of this composition fails at the
    /// superset-routing pin.
    ///
    /// Per-variant restriction laws (structural identity between the
    /// marker-driven parent + the two per-variant siblings):
    ///   * `Sexp::unquote_form(UnquoteForm::Unquote, inner) == Sexp::unquote(inner)`
    ///   * `Sexp::unquote_form(UnquoteForm::Splice,  inner) == Sexp::unquote_splice(inner)`
    ///
    /// The two per-variant constructors ARE the marker-driven parent
    /// specialized on a compile-time-known subset marker; the marker-
    /// abstracted parent binds every consumer that routes a runtime
    /// [`UnquoteForm`] value through a template-substitution construct
    /// to ONE typed method on the outer [`Sexp`] algebra rather than a
    /// two-arm inline `match uf { UnquoteForm::Unquote => Sexp::unquote(
    /// inner), UnquoteForm::Splice => Sexp::unquote_splice(inner) }`
    /// dispatch.
    ///
    /// Pre-lift consumers with a runtime `UnquoteForm` marker routed
    /// through `marker.wrap(inner)` directly (reaching into the
    /// [`UnquoteForm::wrap`] subset-algebra method) OR through the two-
    /// step `Sexp::quote_form(marker.to_quote_form(), inner)`
    /// composition (routing via the superset marker-driven parent).
    /// Post-lift consumers bind to ONE typed-algebra method on the outer
    /// [`Sexp`] algebra sitting next to the typed-project family
    /// ([`Self::as_unquote`] / [`Self::as_unquote_form`]) rather than
    /// reaching into the closed-set [`UnquoteForm::wrap`] method
    /// directly or composing the superset parent with the subset →
    /// superset projection. A future allocation-policy change (e.g.
    /// arena-allocated wrappers for span-aware [`Sexp`]) lands as ONE
    /// edit at the single [`QuoteForm::wrap`] composition site and
    /// propagates through this constructor byte-for-byte (via the
    /// [`UnquoteForm::wrap`] composition).
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 1 — typed entry; the
    /// (typed [`UnquoteForm`] marker, owned inner body,
    /// [`UnquoteForm::wrap`] composition) triple binds at ONE typed-
    /// algebra method on the outer [`Sexp`] algebra, closing the marker-
    /// driven template-substitution (construct, project) algebra dual
    /// pair with [`Self::as_unquote`] on the projection side. THEORY.md
    /// §II.1 invariant 2 — free middle; every consumer that has a
    /// runtime [`UnquoteForm`] marker + an owned inner body and wants to
    /// build a template-substitution wrapper routes through the SAME
    /// typed method, so a regression that drifts one consumer's subset
    /// marker → wrapper mapping cannot reach the substrate's runtime.
    /// THEORY.md §V.1 — knowable platform; the marker-driven template-
    /// substitution typed-construct becomes a TYPE projection on the
    /// substrate's outer [`Sexp`] algebra sitting next to the typed-
    /// project family [`Self::as_unquote`] / [`Self::as_unquote_form`]
    /// rather than the closed-set [`UnquoteForm::wrap`] method threaded
    /// as a method call on a bound-marker value or the two-step subset
    /// → superset then [`Self::quote_form`] composition. THEORY.md
    /// §VI.1 — generation over composition; the marker-driven template-
    /// substitution pair emerges from ONE typed-algebra composition
    /// through [`UnquoteForm::wrap`] rather than from per-consumer
    /// subset-marker → wrapper dispatch literals; a future third
    /// template-substitution marker (e.g. a `,~` reverse-unquote)
    /// extends [`UnquoteForm::ALL`] + [`UnquoteForm::to_quote_form`]'s
    /// dispatch table in lockstep — rustc-enforced through the closed-
    /// set exhaustiveness — with THIS constructor inheriting the
    /// extension through the [`UnquoteForm::wrap`] composition site
    /// without a per-site edit.
    ///
    /// Frontier inspiration: Racket's `(datum->syntax stx (list #'uf
    /// inner))` marker-abstracted template-substitution construct
    /// restricted to the substitution-subset of syntactic-form kinds,
    /// paired one-for-one with `syntax-e` on the projection face — the
    /// typed-construct + typed-project algebra dual is closed on
    /// Racket's syntax algebra at one method per direction per subset,
    /// and `Sexp::unquote_form` / `Sexp::as_unquote` is the Rust-typed
    /// peer on the closed-set outer [`Sexp`] algebra with
    /// [`UnquoteForm`] standing in for Racket's substitution-subset
    /// syntactic-form taxonomy. MLIR's typed factory
    /// `mlir::OpBuilder::create<UnquoteFamilyOp>(loc, marker, operands)`
    /// paired with the projection sibling
    /// `mlir::dyn_cast<UnquoteFamilyOp>(op)` — the typed factory + typed
    /// downcast pair the IR algebra closes over on every op-family
    /// subset at one method per direction; `Sexp::unquote_form` /
    /// [`Self::as_unquote_form`] is the Rust-typed peer on the outer
    /// [`Sexp`] algebra with the closed-set [`UnquoteForm`] standing in
    /// for MLIR's `OperationName` subset taxonomy over the template-
    /// substitution op family.
    #[must_use]
    pub fn unquote_form(marker: UnquoteForm, inner: Sexp) -> Self {
        marker.wrap(inner)
    }

    pub fn is_list(&self) -> bool {
        matches!(self, Self::List(_))
    }
    pub fn as_list(&self) -> Option<&[Sexp]> {
        match self {
            Self::List(xs) => Some(xs),
            _ => None,
        }
    }

    /// Canonical [`Self::List`] outer constructor — collects an
    /// `impl IntoIterator<Item = Sexp>` into the tuple-variant payload
    /// `Vec<Sexp>` at ONE site on the closed-set [`Sexp`] algebra. The
    /// residual-axis section-for-retraction sibling of the existing
    /// [`Self::as_list`] soft-projection ([`Option<&[Sexp]>`]): where
    /// the projection soft-decomposes a [`Self::List`] arm into its
    /// borrowed inner slice, this constructor embeds a fresh owned
    /// item sequence into the matching tuple-variant wrapper. Sibling
    /// of the atomic-payload construct family ([`Self::symbol`],
    /// [`Self::keyword`], [`Self::string`], [`Self::int`],
    /// [`Self::float`], [`Self::boolean`] — all routing through the
    /// typed [`Atom`] construct family on the 6-of-12 atomic-payload
    /// carving) and the quote-family construct family ([`Self::quote`],
    /// [`Self::quasiquote`], [`Self::unquote`], [`Self::unquote_splice`]
    /// — all routing through the typed [`QuoteForm::wrap`] family on
    /// the 4-of-12 quote-family carving); closes the (construct,
    /// project) algebra dual on the third and final structural carving
    /// of the outer [`Sexp`] closed set — the 2-of-12 residual axis
    /// covering [`Self::Nil`] and [`Self::List`]. [`Self::Nil`] is a
    /// unit variant carrying no payload — the residual-axis
    /// construct family closes at ONE constructor (this method) for
    /// the sole payload-bearing residual arm.
    ///
    /// Composition law (forward): `Sexp::list(items) ==
    /// Sexp::List(items.into_iter().collect::<Vec<Sexp>>())` for every
    /// `items: impl IntoIterator<Item = Sexp>`. Round-trip law
    /// (section-for-retraction with the soft-projection sibling): for
    /// every `items: Vec<Sexp>`, `Sexp::list(items.clone()).as_list()
    /// == Some(items.as_slice())` — the outer algebra's typed
    /// constructor pairs section-for-retraction with the outer
    /// algebra's soft projection, and the borrowed-slice cross-
    /// projection preserves identity. Sibling posture across the
    /// three axis-construct families on the outer [`Sexp`] algebra
    /// (atomic + quote-family + residual).
    ///
    /// Outer-shape composition law: `Sexp::list(items).shape() ==
    /// SexpShape::List` for every `items: impl IntoIterator<Item =
    /// Sexp>` — the residual-arm outer-shape identity binds through
    /// the typed-shape lattice at ONE arm, symmetric with the
    /// quote-family construct family's outer-shape composition
    /// `Sexp::X_variant(inner).shape() == QuoteForm::X.sexp_shape()`
    /// and the atomic construct family's `Sexp::X_atom(payload).shape()
    /// == AtomKind::X.sexp_shape()`. Structural-carving-marker
    /// composition law: `Sexp::list(items).as_structural_kind() ==
    /// Some(StructuralKind::List)` for every `items: impl
    /// IntoIterator<Item = Sexp>` — the residual-axis carving marker
    /// binds through the closed-set [`StructuralKind`] algebra at ONE
    /// arm, symmetric with the atomic-axis's `Sexp::X_atom(payload)
    /// .as_atom_kind() == Some(AtomKind::X)` marker composition.
    ///
    /// Pre-lift the [`Self::List(Vec<Sexp>)`] welded pair
    /// ([`Self::List`] tuple-variant constructor + `Vec<Sexp>`
    /// payload) appeared inline at every consumer that builds a
    /// list-shaped [`Sexp`] value — well past the ≥2 PRIME-DIRECTIVE
    /// trigger once the structural shape is named. Post-lift the
    /// welded pair binds at ONE typed-algebra method on the outer
    /// [`Sexp`] algebra with an `impl IntoIterator<Item = Sexp>`
    /// bound so consumers that have a `Vec<Sexp>`, a `[Sexp; N]`
    /// array, an `iter().cloned()` sequence, a
    /// `.map(...).collect()`-worthy chain, or a
    /// `once(head).chain(tail)` composition can hand the sequence
    /// directly to the algebra without a per-site `.collect::<Vec<
    /// Sexp>>()` coercion. A future allocation-policy change (e.g.
    /// arena-allocated lists for span-aware [`Sexp`]) lands as ONE
    /// edit at this method site and propagates through consumers
    /// byte-for-byte.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 1 — typed entry; the
    /// (list-shaped inner sequence, [`Self::List`] tuple-variant
    /// constructor) pairing binds at ONE typed-algebra method on the
    /// outer [`Sexp`] algebra, closing the outer-algebra construct
    /// family across ALL THREE structural carvings of the [`SexpShape`]
    /// closed set (atomic-payload + quote-family + residual). THEORY.md
    /// §II.1 invariant 2 — free middle; every consumer that has an
    /// owned or iterable sequence of [`Sexp`] and wants to build a
    /// list-shaped wrapper routes through the SAME typed method, so a
    /// regression that drifts one consumer's construction from the
    /// others cannot reach the substrate's runtime. THEORY.md §V.1 —
    /// knowable platform; the typed-construct family becomes a TYPE
    /// projection on the substrate's outer [`Sexp`] algebra sitting
    /// next to the typed-project family [`Self::as_list`] rather than
    /// bare tuple-variant constructor + per-site `Vec<Sexp>` discipline.
    /// THEORY.md §VI.1 — generation over composition; the residual-
    /// arm outer-shape + carving-marker pairings emerge from ONE
    /// typed-algebra composition on the outer [`Sexp`] algebra rather
    /// than from per-consumer per-variant literals.
    ///
    /// Frontier inspiration: Racket's `(list x y z)` typed list-
    /// construct primitive paired one-for-one with `(list? v)` /
    /// `(car v)` / `(cdr v)` predicate/projection siblings on the
    /// same closed-set list shape — the typed-construct + typed-
    /// project algebra dual is closed at one method per direction on
    /// Racket's surface, and [`Self::list`] / [`Self::as_list`] is
    /// the Rust-typed peer on the closed-set outer [`Sexp`] algebra
    /// with `impl IntoIterator<Item = Sexp>` standing in for Racket's
    /// variadic collect face. MLIR's `mlir::OpBuilder::create<
    /// ListOp>(loc, elements)` typed-IR list-op construction paired
    /// with `mlir::dyn_cast<ListOp>(op)` on the projection face —
    /// the typed factory + typed downcast pair the IR algebra closes
    /// over on every list-shaped op; [`Self::list`] / [`Self::as_list`]
    /// is the Rust-typed peer on the outer [`Sexp`] algebra with
    /// [`StructuralKind::List`] standing in for MLIR's `OperationName`
    /// taxonomy over the list-shaped op family.
    #[must_use]
    pub fn list<I: IntoIterator<Item = Sexp>>(items: I) -> Self {
        Self::List(items.into_iter().collect())
    }

    /// Soft projection onto the closed-set [`StructuralKind`] residual
    /// carving marker — the 2-of-12 carving of the [`SexpShape`] algebra
    /// covering [`Self::Nil`] and [`Self::List`] (the outer shapes that
    /// lie OUTSIDE both the atomic-payload carving
    /// [`AtomKind`](crate::error::SexpShape::as_atom_kind) and the
    /// quote-family carving
    /// [`QuoteForm`](crate::error::SexpShape::as_quote_form)). Returns
    /// `Some(StructuralKind::Nil)` for [`Self::Nil`],
    /// `Some(StructuralKind::List)` for [`Self::List`], `None` for
    /// every other outer shape (every [`Self::Atom`] variant, every
    /// quote-family wrapper: [`Self::Quote`], [`Self::Quasiquote`],
    /// [`Self::Unquote`], [`Self::UnquoteSplice`]).
    ///
    /// Sibling soft-projection peer of [`Self::as_quote_form`] (the
    /// soft-decomposition of the four homoiconic prefix wrappers into
    /// `(QuoteForm, &Sexp)`) and [`Self::as_unquote`] (the
    /// soft-decomposition of the two template-substitution wrappers
    /// into `(UnquoteForm, &Sexp)`). Direct value-level peer of the
    /// shape-level projection
    /// [`SexpShape::as_structural_kind`](crate::error::SexpShape::as_structural_kind)
    /// — the pair `(Sexp::as_structural_kind, SexpShape::as_structural_kind)`
    /// binds the (Sexp value, StructuralKind carving marker) pairing at
    /// ONE typed method on each algebra, symmetric with the existing
    /// (Sexp value → AtomKind via
    /// `Sexp::as_atom().map(Atom::kind)`) atomic-axis composition and
    /// the direct (Sexp value → QuoteForm) marker projection
    /// [`Self::as_quote_form`] returns.
    ///
    /// Composition law: `s.as_structural_kind() ==
    /// s.shape().as_structural_kind()` for every `s: &Sexp`. Pre-lift
    /// the residual-carving marker at the value level was reachable
    /// only via the two-step composition
    /// `s.shape().as_structural_kind()` (walking through the full
    /// 12-variant [`SexpShape`] closed set to arrive at the 2-of-12
    /// carving marker); post-lift the composition lands at ONE typed
    /// method on the value algebra — the Nil arm returns `Some(Nil)`
    /// directly and the List arm returns `Some(List)` directly,
    /// matching the residual-carving membership at the value level.
    /// The composition law is pinned by
    /// `sexp_as_structural_kind_agrees_with_shape_as_structural_kind_for_every_variant`
    /// in this module, so a regression that drifts either projection
    /// from the other surfaces immediately.
    ///
    /// Sibling-shape lift to [`Self::is_list`] (the bare List-arm
    /// predicate) and [`Self::is_kwargs_list`] (the narrower
    /// kwargs-shaped List cohort predicate): where `is_list` returns
    /// `true` iff the value inhabits the List arm of the residual
    /// carving, `as_structural_kind` returns the typed carving marker
    /// that binds BOTH residual arms (Nil and List) at ONE typed
    /// projection — the operator answering "which residual arm?"
    /// rather than the bare "is this the List arm?" predicate.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the
    /// (Sexp variant, StructuralKind carving marker) pairing becomes a
    /// TYPE projection on the substrate `Sexp` algebra rather than a
    /// two-step composition through the shape-level projection. A typo
    /// or swap at the value-projection site is no longer a runtime
    /// drift but a compile error against the typed projection.
    /// THEORY.md §VI.1 — generation over composition; the
    /// residual-carving marker projection now lives on the typed
    /// `Sexp` algebra alongside [`Self::as_atom`], [`Self::as_list`],
    /// [`Self::as_quote_form`], [`Self::as_unquote`], completing the
    /// (Sexp value → closed-set carving marker) family at the residual
    /// axis. THEORY.md §II.1 invariant 2 — free middle; every consumer
    /// that needs the residual-carving marker at the value level (a
    /// future `tatara-check` predicate keyed on the Nil/List cohort, a
    /// future LSP structural-navigation filter that keys on the
    /// residual carving, a future typed-rewriter walk over the
    /// residual arm) binds to ONE typed method on the value algebra
    /// rather than a two-step composition through the shape-level
    /// projection.
    ///
    /// Frontier inspiration: MLIR's `mlir::dyn_cast<StructuralOp>(val)`
    /// typed soft-downcast on the residual carving of a closed-set
    /// value algebra — the (value, typed carving marker) pairing lives
    /// at ONE typed projection on the outer value-algebra sibling. The
    /// Rust-typed peer here uses the substrate's outer `Sexp` algebra
    /// with `Sexp::as_structural_kind` closing the residual-carving
    /// cell of the value-level soft-projection surface, symmetric with
    /// the atomic-axis composition through [`Self::as_atom`] and the
    /// quote-family projection [`Self::as_quote_form`].
    #[must_use]
    pub fn as_structural_kind(&self) -> Option<StructuralKind> {
        match self {
            Self::Nil => Some(StructuralKind::Nil),
            Self::List(_) => Some(StructuralKind::List),
            _ => None,
        }
    }

    /// Structural-shape predicate — `true` iff this is a [`Self::List`]
    /// whose items form a non-empty, even-length `(:k v :k v …)` kwargs
    /// sequence with every even-indexed item being an [`Atom::Keyword`].
    /// `false` for every other outer shape ([`Self::Nil`], every
    /// [`Self::Atom`] variant, every quote-family wrapper) and for every
    /// [`Self::List`] that fails the kwargs convention (empty list, odd
    /// length, or any even-indexed non-keyword).
    ///
    /// The structural witness that [`Self::to_json`] will project this
    /// value as [`serde_json::Value::Object`] rather than
    /// [`serde_json::Value::Array`] at the [`Self::List`] arm — the
    /// `(Sexp variant + kwargs shape, JSON canonical-form)` pairing
    /// binds at ONE inherent method on the algebra rather than at a
    /// free function consumers must reach into the `domain` module
    /// path to invoke. Inverse round-trip law: every
    /// [`Self::from_json`] projection of a [`serde_json::Value::Object`]
    /// satisfies this predicate (the [`Self::List`] arm
    /// [`Self::from_json`] builds for an `Object` is non-empty by the
    /// `Object`'s non-empty-keys invariant when present, even-length by
    /// the alternating `:k v` build, and keyword-headed at every even
    /// index by the `Self::keyword(camel_to_kebab(k))` build — except
    /// for the structurally degenerate empty `Object` which projects to
    /// `Sexp::List(vec![])` and returns `false` here, matching
    /// [`Self::to_json`]'s "empty-list ↛ kwargs" gate).
    ///
    /// Composes through [`Self::as_list`] (the structural soft-projection
    /// onto `&[Sexp]`) and [`Atom::as_keyword`] (the typed soft-projection
    /// onto the keyword payload from the [`Atom`] algebra) — the predicate
    /// is rebuilt from already-lifted algebra primitives rather than
    /// inline-matching the [`Self::List`] arm. Sibling-shape predicate
    /// peer of [`Self::is_list`] (the unconditional [`Self::List`]-arm
    /// predicate), with this method narrowing the structural witness to
    /// the kwargs-shaped sub-cohort. The two predicates partition the
    /// list-typed cell of the algebra: every [`Self::List`] either
    /// satisfies `is_kwargs_list` (projects as [`serde_json::Value::Object`]
    /// through [`Self::to_json`]) or does not (projects as
    /// [`serde_json::Value::Array`]).
    ///
    /// Theory anchor: THEORY.md §VI.1 — generation over composition; the
    /// kwargs-shape predicate, previously a `pub(crate)` free function in
    /// `domain.rs` reached across the module boundary by [`Self::to_json`],
    /// is lifted ONE algebra level higher onto the inherent method on
    /// the [`Sexp`] algebra — completing the structural-predicate family
    /// alongside [`Self::is_list`] and the soft-projection family
    /// ([`Self::as_atom`], [`Self::as_list`], [`Self::as_quote_form`]).
    /// THEORY.md §II.1 invariant 2 — free middle; every consumer that
    /// queries "would [`Self::to_json`] project this as `Object`?" (the
    /// `Self::to_json` arm itself, future authoring-tool diagnostics, a
    /// future LSP completion fallback, a future REPL pretty-printer that
    /// chooses between `(…)` and `{…}` rendering, a future `tatara-check`
    /// typed-pattern matcher) routes through ONE inherent algebra method
    /// rather than reaching into the `domain` module path for a free
    /// function. THEORY.md §V.1 — knowable platform; the JSON-format
    /// witness becomes a TYPE projection on the substrate `Sexp` algebra
    /// next to its sibling `Sexp::is_list` / `Sexp::as_list` pair rather
    /// than living in a `domain.rs` `pub(crate)` helper consumers must
    /// import via module path.
    ///
    /// Frontier inspiration: MLIR's `mlir::Operation::hasTrait<T>()` —
    /// typed-IR operations carry their structural traits as inherent
    /// methods on the operation algebra rather than as free functions
    /// in a sibling module; `Sexp::is_kwargs_list` is the
    /// unstructured-Rust peer on the `Sexp` algebra for the
    /// "would-this-project-as-Object" structural trait. Racket's
    /// `(keyword-apply-procedure? stx)` — the syntax-class predicate
    /// that gates a kwargs-style application form's printer / expander
    /// path on the syntax algebra; `Sexp::is_kwargs_list` is the
    /// substrate's peer at the [`Sexp`] layer, with the `as_list().
    /// is_some_and(…)` composition standing in for Racket's
    /// `syntax-parse` pattern matcher.
    #[must_use]
    pub fn is_kwargs_list(&self) -> bool {
        self.as_list().is_some_and(|items| {
            !items.is_empty()
                && items.len().is_multiple_of(2)
                && items.iter().step_by(2).all(|s| s.as_keyword().is_some())
        })
    }

    /// Soft projection onto the inner [`Atom`] payload — `Some(&Atom)`
    /// iff this is a [`Self::Atom`] variant, `None` for every other
    /// outer shape (`Nil`, `List`, `Quote`, `Quasiquote`, `Unquote`,
    /// `UnquoteSplice`). The structural-lift face of the per-atomic-
    /// payload soft-projection family — composes with the typed
    /// [`Atom::as_symbol`] / [`Atom::as_keyword`] / [`Atom::as_string`]
    /// / [`Atom::as_int`] / [`Atom::as_float`] / [`Atom::as_bool`]
    /// projections to give the six `Sexp::as_X` consumers ONE typed
    /// boundary instead of six inline `Self::Atom(Atom::X(s)) => Some(s)`
    /// arms.
    ///
    /// Sibling soft-projection peer of [`Self::as_quote_form`] (the
    /// soft-decomposition of the four homoiconic prefix wrappers into
    /// `(QuoteForm, &Sexp)`) and [`Self::as_list`] (the soft-decomposition
    /// of the structural list constructor into `&[Sexp]`). Together the
    /// three projections (`as_atom`, `as_list`, `as_quote_form`) and
    /// their nullary peer ([`Self::Nil`] via `matches!(self, Self::Nil)`)
    /// cover every outer-shape arm of the `Sexp` algebra: Nil + Atom +
    /// List + 4 quote-family arms = 7 outer shapes, with the typed-
    /// projection set partitioning them by structural axis.
    ///
    /// Composition law binding `Sexp::as_X` to the typed `Atom` algebra:
    /// for every [`Sexp`] `s`,
    /// `s.as_symbol()` (and each `as_keyword` / `as_string` / `as_int` /
    /// `as_bool` sibling) `== s.as_atom().and_then(Atom::as_<variant>)`.
    /// The `Sexp::as_float` consumer specializes through the widening
    /// inline composition `s.as_atom().and_then(|a| a.as_float()
    /// .or_else(|| a.as_int().map(|n| n as f64)))` so the algebra-level
    /// `Atom::as_float` stays strict and the typed-identity
    /// distinction `Int(1)` vs `Float(1.0)` is preserved at the algebra
    /// layer (see [`Atom::as_int`]'s docstring for the discipline).
    ///
    /// Theory anchor: THEORY.md §VI.1 — generation over composition;
    /// the six inline `Self::Atom(Atom::X(s)) => Some(_)` arms across
    /// the `Sexp::as_X` family is past the three-times rule. THEORY.md
    /// §II.1 invariant 2 — free middle; SIX consumers (`as_symbol`,
    /// `as_keyword`, `as_string`, `as_int`, `as_float`, `as_bool`) now
    /// route through ONE typed structural lift (this method) AND ONE
    /// per-variant projection family on the closed-set `Atom` algebra
    /// rather than six byte-identical outer-arm matches each.
    /// THEORY.md §V.1 — knowable platform; the (Sexp variant, inner
    /// payload kind) pairing becomes a TYPE projection on the substrate
    /// algebra rather than six inline arms scattered across the six
    /// `Sexp::as_X` consumers.
    #[must_use]
    pub fn as_atom(&self) -> Option<&Atom> {
        match self {
            Self::Atom(a) => Some(a),
            _ => None,
        }
    }

    /// Soft projection onto the closed-set [`AtomKind`] atomic-payload
    /// carving marker — the 6-of-12 carving of the [`SexpShape`] algebra
    /// covering [`Self::Atom`]'s six per-payload variants ([`Atom::Symbol`],
    /// [`Atom::Keyword`], [`Atom::Str`], [`Atom::Int`], [`Atom::Float`],
    /// [`Atom::Bool`]). Returns `Some(a.kind())` iff this is a
    /// [`Self::Atom`] variant, `None` for every other outer shape
    /// ([`Self::Nil`], [`Self::List`], every quote-family wrapper:
    /// [`Self::Quote`], [`Self::Quasiquote`], [`Self::Unquote`],
    /// [`Self::UnquoteSplice`]).
    ///
    /// Direct value-level peer of the shape-level projection
    /// [`SexpShape::as_atom_kind`](crate::error::SexpShape::as_atom_kind)
    /// — the pair `(Sexp::as_atom_kind, SexpShape::as_atom_kind)` binds
    /// the (Sexp value, AtomKind carving marker) pairing at ONE typed
    /// method on each algebra, closing the atomic-axis cell of the
    /// (Sexp value → carving marker) matrix. Sibling soft-projection
    /// peer of [`Self::as_structural_kind`] (the 2-of-12 residual
    /// carving returning `Option<StructuralKind>`) and
    /// [`Self::as_quote_form`] (the 4-of-12 quote-family carving
    /// returning `Option<(QuoteForm, &Sexp)>`) — post-lift ALL THREE
    /// carvings that partition the twelve outer shapes of the
    /// [`SexpShape`] algebra have a marker-only value-level projection
    /// on `Sexp`: `as_atom_kind` (atomic axis), `as_quote_form`
    /// (quote-family axis, marker + inner), `as_structural_kind`
    /// (residual axis). The `Sexp::as_atom` projection stays available
    /// for consumers that need the inner [`Atom`] payload for further
    /// per-variant typed projection ([`Atom::as_symbol`] et al.); this
    /// projection is the shortcut for consumers that only need the
    /// carving-marker identity.
    ///
    /// Composition laws (dual bindings): `s.as_atom_kind() ==
    /// s.as_atom().map(Atom::kind) == s.shape().as_atom_kind()` for
    /// every `s: &Sexp`. Pre-lift the atomic carving marker at the
    /// value level was reachable only via one of these two-step
    /// compositions — either through the [`Atom`] algebra
    /// (`as_atom().map(Atom::kind)`) or through the shape algebra
    /// (`shape().as_atom_kind()`). Post-lift the projection lands at
    /// ONE typed method on the value algebra, and both compositions
    /// are pinned as agreement laws (see
    /// `sexp_as_atom_kind_agrees_with_as_atom_map_kind_for_every_variant`
    /// and
    /// `sexp_as_atom_kind_agrees_with_shape_as_atom_kind_for_every_variant`
    /// in this module). A regression that drifts any of the three
    /// projections from the others surfaces immediately.
    ///
    /// Symmetric with [`Self::as_structural_kind`]'s shape (returns
    /// just the marker, no inner-payload borrow) — where
    /// [`Self::as_quote_form`] and [`Self::as_unquote`] surface both
    /// the marker AND the wrapped inner `&Sexp` (because the four
    /// quote-family arms and the two substitution arms structurally
    /// carry a boxed inner value), `as_atom_kind` and
    /// `as_structural_kind` return marker-only projections (the atomic
    /// arm's inner payload is heterogeneous across the six variants —
    /// `String` / `i64` / `f64` / `bool` — and the residual arms
    /// carry no or list-heterogeneous payload). Consumers that need
    /// the payload compose through [`Self::as_atom`] +
    /// [`Atom::as_symbol`] et al. (atomic axis) or [`Self::as_list`]
    /// (residual axis); this projection is the payload-agnostic
    /// carving-marker cell.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the (Sexp
    /// variant, AtomKind carving marker) pairing becomes a TYPE
    /// projection on the substrate `Sexp` algebra rather than a
    /// two-step composition through either the [`Atom`] algebra or the
    /// shape algebra. A typo or swap at the value-projection site is
    /// no longer a runtime drift but a compile error against the
    /// typed projection. THEORY.md §VI.1 — generation over composition;
    /// the atomic-carving marker projection now lives on the typed
    /// `Sexp` algebra alongside [`Self::as_atom`], [`Self::as_list`],
    /// [`Self::as_quote_form`], [`Self::as_unquote`],
    /// [`Self::as_structural_kind`], completing the (Sexp value →
    /// closed-set carving marker) family across ALL THREE axes
    /// (atomic + quote-family + structural-residual). THEORY.md §II.1
    /// invariant 2 — free middle; every consumer that needs the
    /// atomic-carving marker at the value level (a future
    /// `tatara-check` predicate keyed on the atomic cohort, a future
    /// LSP structural-navigation filter that keys on the atomic
    /// carving, a future typed-rewriter walk over the atomic arm)
    /// binds to ONE typed method on the value algebra rather than a
    /// two-step composition.
    ///
    /// Sibling posture across the value-level marker family — the
    /// three projections (`as_atom_kind`, `as_quote_form`,
    /// `as_structural_kind`) form a partition of the seven outer-shape
    /// variants of the `Sexp` algebra: for every `s: &Sexp`, EXACTLY
    /// ONE returns `Some(_)` (pinned by the joint sweep
    /// `sexp_as_atom_kind_partitions_outer_shapes_jointly_with_as_quote_form_and_as_structural_kind`
    /// in this module, sibling to the pre-existing partition sweep
    /// keyed on `as_atom` rather than `as_atom_kind`). The value-level
    /// partition-total invariant across the three carvings is the
    /// value-level peer of the shape-level partition-total invariant
    /// (`sexp_shape_partition_is_total_across_atom_quote_structural_carvings`
    /// in error.rs); each axis has BOTH invariants pinned.
    ///
    /// Frontier inspiration: MLIR's `mlir::dyn_cast<AtomOp>(val)` typed
    /// soft-downcast onto the atomic carving of a closed-set value
    /// algebra — the (value, typed carving marker) pairing lives at
    /// ONE typed projection on the outer value-algebra sibling. The
    /// Rust-typed peer here uses the substrate's outer `Sexp` algebra
    /// with `Sexp::as_atom_kind` closing the atomic-carving cell of
    /// the value-level soft-projection surface, symmetric with the
    /// residual-carving projection [`Self::as_structural_kind`] and
    /// the quote-family projection [`Self::as_quote_form`]. Racket's
    /// `(atom? stx)` predicate paired with `(syntax->datum stx)` on
    /// the atomic branch — the substrate's `as_atom_kind` surfaces the
    /// typed witness (`AtomKind`) alongside the predicate verdict in
    /// ONE `Option<AtomKind>` projection.
    #[must_use]
    pub fn as_atom_kind(&self) -> Option<AtomKind> {
        self.as_atom().map(Atom::kind)
    }

    /// Project this [`Sexp`] to its closed-set [`SexpShape`] outer-shape
    /// marker — `Nil → SexpShape::Nil`, `Atom(a) → a.kind().sexp_shape()`,
    /// `List(_) → SexpShape::List`, and each quote-family wrapper routes
    /// through `as_quote_form().map(|(qf, _)| qf.sexp_shape())`. The
    /// outer-shape peer on the [`Sexp`] algebra of [`Atom::kind`] (the
    /// atomic-payload axis) and [`QuoteForm::sexp_shape`] (the
    /// quote-family axis) — completes the substrate's Sexp-shape
    /// projection family by lifting the free-function dispatcher
    /// [`crate::domain::sexp_shape`] onto the typed `Sexp` algebra
    /// alongside its [`Atom`] / [`QuoteForm`] peers.
    ///
    /// Composition law: `s.shape() == crate::domain::sexp_shape(s)` for
    /// every `s: &Sexp`. The free function continues to exist as a thin
    /// delegate (its callers in `domain.rs`'s diagnostic-builder paths,
    /// `compile.rs`'s `TypeMismatch.got` builder, and downstream tests
    /// route through `s.shape()` after this lift), so the (Sexp variant,
    /// SexpShape variant) pairing now binds at ONE inherent method on
    /// the algebra rather than at a free function `domain` consumers
    /// must reach into the module path to invoke.
    ///
    /// Sibling-shape lift to the typed-EXIT projection trio on [`Atom`]
    /// ([`fmt::Display for Atom`], [`Atom::to_json`],
    /// `Atom::to_iac_forge_sexpr` (removed)) and the typed-ENTRY classifier
    /// ([`Atom::from_lexeme`]): where the atomic-payload algebra carries
    /// its own per-variant projection family at the atomic-payload
    /// level, the `Sexp` algebra carries this single outer-shape
    /// projection that composes through [`Self::as_atom`] +
    /// [`Atom::kind`] (atomic axis) and [`Self::as_quote_form`] (quote-
    /// family axis) — every other arm (`Nil`, `List`) projects to its
    /// own [`SexpShape`] variant directly.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the
    /// (Sexp variant, SexpShape variant) pairing becomes an inherent
    /// algebra projection rather than a free function in `domain.rs`,
    /// so the projection sits next to the rest of the typed `Sexp`
    /// algebra ([`Self::as_atom`], [`Self::as_list`],
    /// [`Self::as_quote_form`], [`Self::head_symbol`],
    /// [`Self::as_call`]) the substrate carries. THEORY.md §II.1
    /// invariant 2 — free middle; every consumer that needs the
    /// outer shape (diagnostic builders at
    /// [`crate::domain::sexp_witness`] / [`crate::domain::missing_head_err`],
    /// [`crate::compile`]'s `TypeMismatch.got` projection, future LSP /
    /// REPL / `tatara-check` typed-pattern matchers) now reaches a
    /// method on the value rather than a free function imported from
    /// `domain`. THEORY.md §VI.1 — generation over composition; the
    /// inline dispatch lifted to [`crate::domain::sexp_shape`] is now
    /// lifted ONE algebra level higher — from the free function to
    /// the inherent method — so a future `Sexp` variant lands at the
    /// algebra's match site without a module-path indirection. A
    /// future extension (e.g. `Sexp::Vector` for `#(...)` reader
    /// syntax, `Sexp::Map` for `{...}`) extends THIS method + the
    /// `SexpShape` algebra + the free function's delegation in
    /// lockstep — exhaustively checked by rustc across the `Sexp`
    /// match.
    ///
    /// Frontier inspiration: MLIR's `mlir::Operation::getName()` —
    /// the typed-IR operation projects through an inherent method
    /// to its closed-set name on the operation algebra; `Sexp::shape`
    /// is the unstructured-Rust peer on the [`Sexp`] algebra for the
    /// outer-shape projection surface, with [`SexpShape`] standing in
    /// for MLIR's `OperationName` taxonomy. Racket's `(syntax-e stx)`
    /// composed with a datum-prim classifier on the closed-set
    /// syntax-taxonomy projects a syntax object to its outer shape via
    /// a single primitive on the syntax algebra; `Sexp::shape` is the
    /// substrate's typed-Rust peer.
    #[must_use]
    pub fn shape(&self) -> SexpShape {
        // Each variant routes through its closed-set carving-marker's
        // `sexp_shape` projection — the atomic-payload carving via
        // `AtomKind::sexp_shape`, the structural-residual carving via
        // `StructuralKind::sexp_shape`, the quote-family carving via
        // `QuoteForm::sexp_shape`. Post-lift the twelve outer-shape
        // arms of the SexpShape closed set are reached through THREE
        // carving-marker `sexp_shape` projections (6 + 2 + 4 = 12),
        // symmetric across the partition — no arm hits a raw
        // `SexpShape::*` literal here. A future thirteenth variant
        // (e.g. `Sexp::Vector` for `#(...)` reader syntax) extends the
        // carving-marker family the same way and lands at one arm
        // here + one carving-marker `sexp_shape` arm in lockstep.
        match self {
            Self::Nil => StructuralKind::Nil.sexp_shape(),
            Self::Atom(a) => a.kind().sexp_shape(),
            Self::List(_) => StructuralKind::List.sexp_shape(),
            Self::Quote(_) | Self::Quasiquote(_) | Self::Unquote(_) | Self::UnquoteSplice(_) => {
                let (qf, _) = self.expect_quote_form();
                qf.sexp_shape()
            }
        }
    }

    /// Project this `Sexp` to its [`SexpWitness`] — the typed joint
    /// identity pairing the structural [`SexpShape`] with the
    /// renderable [`Sexp::Display`] projection in ONE owned value.
    /// The joint-identity peer on the [`Sexp`] algebra of
    /// [`Self::shape`] (the structural-shape-only projection) and
    /// [`fmt::Display for Sexp`] (the rendered-literal-only
    /// projection) — completes the substrate's Sexp-projection
    /// family by lifting the free-function dispatcher
    /// [`crate::domain::sexp_witness`] onto the typed `Sexp` algebra
    /// alongside its [`Self::shape`] peer.
    ///
    /// Composition law: `s.witness() ==
    /// crate::domain::sexp_witness(s)` for every `s: &Sexp`. The
    /// free function continues to exist as a thin delegate (its
    /// callers in `macro_expand.rs`'s 8 typed-entry rejection
    /// builders, `domain.rs`'s `missing_head_err` caller +
    /// `rewriter_non_list_err` typed-exit builder, and downstream
    /// tests route through `s.witness()` after this lift), so the
    /// (Sexp variant, SexpWitness identity) pairing now binds at
    /// ONE inherent method on the algebra rather than at a free
    /// function `domain` consumers must reach into the module path
    /// to invoke. Body composes the two algebra-level projections
    /// — `self.shape()` for the structural identity, `self.to_string()`
    /// for the renderable identity — into ONE
    /// [`SexpWitness::new`] call. Pre-lift the dispatcher lived as
    /// a free function in `domain.rs`; post-lift the canonical site
    /// is the inherent method and the free function delegates
    /// (mirrors the [`Self::shape`] lift in 121bb60 exactly).
    ///
    /// Sibling-shape lift to [`Self::shape`] (the structural-shape
    /// projection): where `shape()` carries the typed-shape axis on
    /// the `Sexp` algebra, `witness()` carries the JOINT typed-shape
    /// and renderable-literal axis — the typed identity an authoring
    /// tool diagnostic owes the operator AT the typed-entry or
    /// typed-exit rejection boundary. Every rejection-builder
    /// helper in `macro_expand.rs` that previously projected `&Sexp`
    /// through `crate::domain::sexp_witness(_)` at the variant
    /// boundary now reaches a method on the value rather than a
    /// free function imported from `domain`.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the
    /// (Sexp variant, SexpWitness identity) pairing becomes an
    /// inherent algebra projection rather than a free function in
    /// `domain.rs`, so the projection sits next to the rest of the
    /// typed `Sexp` algebra ([`Self::shape`], [`Self::as_atom`],
    /// [`Self::as_list`], [`Self::as_quote_form`],
    /// [`Self::head_symbol`], [`Self::as_call`]) the substrate
    /// carries. THEORY.md §II.1 invariant 2 — free middle; every
    /// consumer that needs the typed joint identity at a
    /// rejection-boundary slot (`NonSymbolUnquoteTarget.got`,
    /// `SpliceOutsideList.got`, `NonSymbolParam.got`,
    /// `RestParamMissingName.got`, `RestParamTrailingTokens.first`,
    /// `OptionalParamMalformed.got`, `DefmacroNonSymbolName.got`,
    /// `DefmacroNonListParams.got`, `MissingHeadSymbol.got`,
    /// `RewriterNonList.got`, future LSP / REPL / `tatara-check`
    /// typed-pattern matchers) now reaches a method on the value
    /// rather than a free function imported from `domain`.
    /// THEORY.md §VI.1 — generation over composition; the inline
    /// dispatch lifted to [`crate::domain::sexp_witness`] is now
    /// lifted ONE algebra level higher — from the free function
    /// to the inherent method — completing the Sexp-projection
    /// family alongside [`Self::shape`]. A future `Sexp` variant
    /// extension (e.g. `Sexp::Vector` for `#(...)` reader syntax,
    /// `Sexp::Map` for `{...}`) reaches this method through the
    /// already-lifted [`Self::shape`] + [`fmt::Display for Sexp`]
    /// pair — no new arm needed here.
    ///
    /// Frontier inspiration: MLIR's diagnostic builder pattern —
    /// `op.emitOpError() << op` projects the offending operation
    /// through inherent methods (`getName()`, `print()`) into ONE
    /// diagnostic value; `Sexp::witness` is the unstructured-Rust
    /// peer on the [`Sexp`] algebra for the joint typed-shape +
    /// renderable-literal projection surface, with [`SexpWitness`]
    /// standing in for MLIR's `InFlightDiagnostic` typed payload.
    #[must_use]
    pub fn witness(&self) -> SexpWitness {
        SexpWitness::new(self.shape(), self.to_string())
    }

    /// Project this `Sexp` to its stable, human-readable outer-shape
    /// label — the `&'static str` axis on the [`Sexp`] algebra. Lifts
    /// the free-function dispatcher [`crate::domain::sexp_type_name`]
    /// onto the typed `Sexp` algebra alongside its [`Self::shape`] /
    /// [`Self::witness`] / [`Self::to_json`] / [`Self::from_json`]
    /// sibling projections, completing the substrate's
    /// Sexp-projection family at the canonical-label axis the way
    /// [`Self::shape`] completes the typed-shape axis and
    /// [`fmt::Display for Sexp`] completes the canonical-string axis.
    ///
    /// Composition law: `s.type_name() == s.shape().label() ==
    /// crate::domain::sexp_type_name(s)` for every `s: &Sexp`.
    /// Pre-lift the projection lived as a free function in
    /// `domain.rs` consumers (in particular the `LispError::TypeMismatch`
    /// `got` slot in `compile.rs` and the legacy substring-grep
    /// rejection-message tests) reached across module boundaries to
    /// invoke; post-lift the canonical site is the inherent method on
    /// the [`Sexp`] algebra and the free function delegates so existing
    /// callers continue to compile. Body composes through
    /// [`Self::shape`] + [`SexpShape::label`] so a future `Sexp`
    /// variant (e.g. `Sexp::Vector` for `#(...)` reader syntax,
    /// `Sexp::Map` for `{...}`) lands at one extension site
    /// ([`Self::shape`]'s exhaustive arm) rather than a parallel
    /// `&'static str` match — the projection is structurally derived,
    /// not duplicated.
    ///
    /// Sibling-shape lift to [`Self::shape`] (the typed-shape
    /// projection): where `shape()` carries the typed
    /// [`SexpShape`] identity (matchable, exhaustive across `Sexp`
    /// variants), `type_name()` carries the `&'static str` literal
    /// the rendered diagnostic surface wants (still derived from
    /// the typed identity, but flattened through
    /// [`SexpShape::label`] for substring-grep callers and the
    /// `TypeMismatch.got` slot). The `&'static str` lifetime makes
    /// the projection cheap to embed in any error variant without
    /// allocation.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the
    /// (Sexp variant, `&'static str` label) pairing becomes an
    /// inherent algebra projection rather than a free function in
    /// `domain.rs`, so the projection sits next to the rest of the
    /// typed `Sexp` algebra ([`Self::shape`], [`Self::witness`],
    /// [`Self::to_json`], [`Self::from_json`], [`Self::as_atom`],
    /// [`Self::as_list`], [`Self::as_quote_form`],
    /// [`Self::head_symbol`], [`Self::as_call`]) the substrate
    /// carries. THEORY.md §II.1 invariant 2 — free middle; every
    /// consumer that needs the outer-shape label
    /// (`LispError::TypeMismatch.got` projection in `compile.rs`,
    /// legacy substring-grep rejection-message tests, future LSP /
    /// REPL diagnostic surfaces) now reaches a method on the value
    /// rather than a free function imported from `domain`.
    /// THEORY.md §VI.1 — generation over composition; the inline
    /// `s.shape().label()` recipe lifted to
    /// [`crate::domain::sexp_type_name`] is now lifted ONE algebra
    /// level higher — from the free function to the inherent
    /// method — completing the Sexp-projection family alongside
    /// [`Self::shape`] / [`Self::witness`] / [`Self::to_json`] /
    /// [`Self::from_json`]. The `domain.rs` `sexp_*` free-function
    /// namespace is now structurally reserved for free functions
    /// that genuinely need a `domain`-module reach (registry
    /// dispatch, kwargs gates, registry suggestions), not
    /// algebra-layer projections.
    ///
    /// Frontier inspiration: MLIR's `mlir::Operation::getName()`
    /// composed with `OperationName::getStringRef()` — the typed-IR
    /// operation projects through inherent methods to its closed-set
    /// label on the operation algebra; `Sexp::type_name` is the
    /// unstructured-Rust peer on the [`Sexp`] algebra for the
    /// canonical-label projection surface, with [`SexpShape::label`]
    /// standing in for MLIR's `OperationName::getStringRef` second
    /// hop. Racket's `(syntax-name stx)` — the typed inverse of
    /// `(syntax-e stx)` on the syntax algebra; `Sexp::type_name`
    /// composes the typed-shape projection with its closed-set
    /// label projection at the inherent-method site rather than
    /// the typeclass-method site, matching pleme-io's
    /// "rust-typed, not trait-typed" idiom for closed-set algebras.
    #[must_use]
    pub fn type_name(&self) -> &'static str {
        self.shape().label()
    }

    /// Project this `Sexp` to its canonical [`serde_json::Value`]
    /// rendering — the typed-algebra peer of [`Atom::to_json`] at the
    /// `Sexp` layer. Lifts the free-function dispatcher
    /// [`crate::domain::sexp_to_json`] onto the typed `Sexp` algebra
    /// alongside its [`Self::shape`] / [`Self::witness`] sibling
    /// projections, completing the JSON-projection axis at the
    /// algebra layer the way [`fmt::Display for Sexp`] completes the
    /// canonical-string axis. The free function continues to exist
    /// as a thin delegate (its callers in `tatara-lisp-derive`'s
    /// derive output route through it via the
    /// `crate::domain::sexp_to_json` import); the
    /// `from_value_with_path` private helper in `domain.rs` and the
    /// recursive sub-calls inside this method route through the
    /// inherent method directly so the canonical-site indirection
    /// disappears at every internal callsite.
    ///
    /// Rules (preserve byte-identical pre-lift behavior at the
    /// `sexp_to_json` callsite):
    ///   - [`Self::Nil`] → [`serde_json::Value::Null`].
    ///   - [`Self::Atom`] → [`Atom::to_json`] (the typed-algebra
    ///     peer at the atomic-payload layer; pinned by
    ///     `sexp_to_json_atom_arms_route_through_atom_to_json` in
    ///     `domain.rs`).
    ///   - [`Self::List`] with kwargs shape `(:k v :k v …)` →
    ///     [`serde_json::Value::Object`] keyed by
    ///     [`crate::domain::kebab_to_camel`] of each `:k`'s name.
    ///     A duplicate kebab→camel key inside any nested kwargs-list
    ///     fails with [`crate::domain::duplicate_kwarg`] — same
    ///     typed-entry posture
    ///     [`crate::domain::parse_kwargs`] takes at the top level.
    ///   - [`Self::List`] otherwise → [`serde_json::Value::Array`]
    ///     mapping each element through this method recursively.
    ///   - [`Self::Quote`] / [`Self::Quasiquote`] / [`Self::Unquote`]
    ///     / [`Self::UnquoteSplice`] → recurse on the inner via
    ///     [`Self::expect_quote_form`] (strips the wrapper; the
    ///     round-trip via [`crate::domain::json_to_sexp`] re-emits
    ///     the inner without an enclosing wrapper). All four arms
    ///     route through ONE [`Self::as_quote_form`]-derived
    ///     projection so the per-variant pairing binds at ONE site
    ///     on the [`QuoteForm`] algebra rather than four
    ///     byte-identical inline arms.
    ///
    /// Composition law: `s.to_json() == crate::domain::sexp_to_json(s)`
    /// for every `s: &Sexp`. Pre-lift the dispatcher lived as a free
    /// function in `domain.rs`; post-lift the canonical site is the
    /// inherent method and the free function delegates (same lift
    /// posture as [`Self::shape`] in 121bb60 and [`Self::witness`]
    /// in a427e3b).
    ///
    /// Sibling-shape lift to [`Self::shape`] (the structural-shape
    /// projection), [`Self::witness`] (the joint structural-shape +
    /// renderable-literal projection), and [`fmt::Display for Sexp`]
    /// (the renderable-literal projection): where those three carry
    /// the Lisp-canonical-form / structural-identity axes on the
    /// algebra, `to_json` carries the JSON canonical-form axis. The
    /// substrate's `Sexp` algebra now binds ALL THREE canonical-form
    /// projection surfaces (Lisp Display, JSON, and the feature-gated
    /// iac-forge `From<&Sexp> for SExpr`) at the algebra layer, with
    /// per-variant atomic rendering composed through the corresponding
    /// [`Atom`] projection family (`Atom::Display`, [`Atom::to_json`],
    /// `Atom::to_iac_forge_sexpr`).
    ///
    /// Theory anchor: THEORY.md §VI.1 — generation over composition;
    /// the inline dispatch the prior runs lifted onto
    /// [`crate::domain::sexp_to_json`] (the free function) is now
    /// lifted ONE algebra level higher — from the free function to
    /// the inherent method — completing the Sexp-projection family
    /// alongside [`Self::shape`] and [`Self::witness`]. THEORY.md
    /// §II.1 invariant 2 — free middle; the typed-exit JSON
    /// projection (every consumer that round-trips a Sexp through
    /// `serde_json::from_value::<T>` for typed-domain
    /// deserialization, the typed-rewriter at
    /// [`crate::domain::TypedRewriter`], the derive macro's
    /// `compile_from_args` fallthrough, and any future canonical-
    /// form surface) all route through ONE inherent algebra method
    /// rather than reach into the `domain` module path for a free
    /// function. THEORY.md §V.1 — knowable platform; a future
    /// `Sexp` variant extension (e.g. `Sexp::Vector` for `#(...)`
    /// reader syntax, `Sexp::Map` for `{...}`) reaches this method
    /// through the already-lifted [`Self::as_quote_form`] +
    /// [`Atom::to_json`] pair — one arm added here for the new
    /// outer-shape variant; rustc enforces the per-variant body is
    /// named.
    ///
    /// Frontier inspiration: MLIR's `mlir::AsmPrinter::printOp` —
    /// the typed-IR printer dispatches on the closed-set `Op` so
    /// every printer body for an op lives at ONE implementation site;
    /// `Sexp::to_json` is the unstructured-Rust peer on the `Sexp`
    /// algebra for the JSON canonical-form surface (where
    /// [`fmt::Display for Sexp`] is the Lisp-canonical-form peer
    /// and `From<&Sexp> for iac_forge::SExpr` is the
    /// canonical-attestation-form peer). Racket's `(syntax->datum
    /// stx)` then a serializer over the datum prim — `to_json` is
    /// the substrate's serializer at the Sexp layer composed
    /// through [`Atom::to_json`] at the atomic-payload layer, with
    /// the closed-set [`AtomKind`] standing in for Racket's
    /// datum-prim taxonomy.
    pub fn to_json(&self) -> crate::error::Result<serde_json::Value> {
        Ok(match self {
            Self::Nil => serde_json::Value::Null,
            Self::Atom(a) => a.to_json(),
            Self::List(items) => {
                if self.is_kwargs_list() {
                    let mut map = serde_json::Map::with_capacity(items.len() / 2);
                    let mut i = 0;
                    while i + 1 < items.len() {
                        if let Some(k) = items[i].as_keyword() {
                            let value = items[i + 1].to_json()?;
                            if map
                                .insert(crate::domain::kebab_to_camel(k), value)
                                .is_some()
                            {
                                return Err(crate::domain::duplicate_kwarg(k));
                            }
                            i += 2;
                        } else {
                            break;
                        }
                    }
                    serde_json::Value::Object(map)
                } else {
                    serde_json::Value::Array(
                        items
                            .iter()
                            .map(Self::to_json)
                            .collect::<crate::error::Result<Vec<_>>>()?,
                    )
                }
            }
            Self::Quote(_) | Self::Quasiquote(_) | Self::Unquote(_) | Self::UnquoteSplice(_) => {
                let (_, inner) = self.expect_quote_form();
                inner.to_json()?
            }
        })
    }

    /// Inverse of [`Self::to_json`] — project a [`serde_json::Value`] back
    /// onto a [`Sexp`]. The closed-set [`serde_json::Value`] discriminator
    /// maps directly onto the corresponding [`Sexp`] constructor:
    ///
    ///   - [`serde_json::Value::Null`] → [`Self::Nil`].
    ///   - [`serde_json::Value::Bool`] → [`Self::boolean`].
    ///   - [`serde_json::Value::Number`] → [`Self::int`] when the value
    ///     fits an [`i64`], otherwise [`Self::float`] when it fits an
    ///     [`f64`]; the structural impossibility "neither i64 nor f64"
    ///     collapses to [`Self::int(0)`](Self::int) as a typed floor —
    ///     [`serde_json::Number`]'s closed-set discriminator excludes
    ///     this case in practice (every [`serde_json::Number`] is either
    ///     i64-fitting, u64-fitting projected through f64, or f64-fitting
    ///     directly), but the typed floor stays explicit so a future
    ///     `serde_json` extension does not silently misroute. Mirror of
    ///     [`Atom::to_json`]'s [`Self::int`] / [`Self::float`] bifurcation.
    ///   - [`serde_json::Value::String`] → [`Self::string`]. The
    ///     `serde_json::Value::String` discriminator is type-erased — a
    ///     serde-projected symbol AND a serde-projected keyword AND a
    ///     genuine string literal ALL inhabit it on the JSON side — so
    ///     the back-projection chooses [`Self::string`] as the lossless
    ///     floor for the `Atom::Symbol` / `Atom::Keyword` / `Atom::Str`
    ///     three-way collapse. Consumers that need the symbol-vs-string
    ///     distinction must preserve it BEFORE the JSON round-trip
    ///     (e.g. through a typed enum's serde projection rather than a
    ///     raw `Sexp`-to-`JValue` round-trip).
    ///   - [`serde_json::Value::Array`] → [`Self::List`] mapping each
    ///     element through this method recursively.
    ///   - [`serde_json::Value::Object`] → [`Self::List`] of alternating
    ///     `:key value` pairs in [`serde_json::Map`]'s iteration order
    ///     (sorted by key under `serde_json`'s default `BTreeMap`
    ///     backing; insertion order under the optional `preserve_order`
    ///     feature, which the substrate does NOT enable today), with
    ///     each JSON key projected through
    ///     [`crate::domain::camel_to_kebab`] to recover the `:k`'s
    ///     kebab-case authoring shape and each JSON value recursed
    ///     through this method. Inverse of [`Self::to_json`]'s
    ///     [`Self::List`] kwargs-shape arm: that arm projects
    ///     `:k v :k v …` into a JSON object via
    ///     [`crate::domain::kebab_to_camel`]; this arm projects the
    ///     object back into a `Self::List` of alternating keyword /
    ///     value via the inverse [`crate::domain::camel_to_kebab`].
    ///
    /// Composition law: `Self::from_json(&s.to_json()?)` projects back
    /// to a `Sexp` whose [`Self::to_json`] re-projection produces the
    /// SAME `JValue` (modulo the lossy `Symbol` / `Keyword` / `Str`
    /// three-way collapse documented above; for the round-trippable
    /// subset, `Sexp::Nil`, the six [`Atom`] kinds within their
    /// discriminator class, and recursively `Sexp::List` of round-
    /// trippable elements, the law holds byte-for-byte).
    ///
    /// Sibling-lift posture: this method mirrors the prior
    /// [`crate::domain::sexp_to_json`] → [`Self::to_json`] (commit
    /// 875ee3b) / [`crate::domain::sexp_shape`] → [`Self::shape`]
    /// (commit 121bb60) / [`crate::domain::sexp_witness`] →
    /// [`Self::witness`] (commit a427e3b) family of lifts, all of which
    /// promoted a free function in `domain.rs` to the inherent-method
    /// canonical site on the [`Sexp`] algebra. Pre-lift the
    /// `json_to_sexp` dispatcher lived in `domain.rs` as the canonical
    /// site; post-lift this inherent method is the canonical site and
    /// the free function delegates so every existing caller continues
    /// to compile.
    ///
    /// Sibling-shape lift on the round-trip closure: the substrate's
    /// `Sexp` ↔ `serde_json::Value` round-trip now lives entirely as
    /// two inherent methods on the [`Sexp`] algebra — [`Self::to_json`]
    /// (forward) and [`Self::from_json`] (inverse). Consumers that
    /// previously round-tripped a typed value through Lisp forms via
    /// `domain::sexp_to_json` + `domain::json_to_sexp` now bind to ONE
    /// algebra (the inherent-method family) rather than reaching across
    /// the `domain` module path for two free functions. A future
    /// canonical-form surface (e.g., a YAML round-trip via
    /// [`serde_yaml`], a Nix-expression round-trip via the typed Nix
    /// surface in `tatara-nix`) hangs off the SAME `Sexp` algebra at
    /// `Self::to_yaml` / `Self::from_yaml` / `Self::to_nix` /
    /// `Self::from_nix` — the naming pattern is now structurally
    /// established by this pair.
    ///
    /// Theory anchor: THEORY.md §VI.1 — generation over composition;
    /// the inline `json_to_sexp` dispatcher in `domain.rs` is lifted
    /// ONE algebra level higher (from free function to inherent
    /// method), completing the Sexp ↔ JValue round-trip closure
    /// alongside [`Self::to_json`]. THEORY.md §V.1 — knowable
    /// platform; the inverse projection becomes a NAMED primitive on
    /// the substrate's `Sexp` algebra rather than a `domain`-module
    /// free function consumers reach across module boundaries to call.
    /// THEORY.md §II.1 invariant 2 — free middle; every consumer that
    /// round-trips through JSON (the typed-rewriter at
    /// [`crate::domain::TypedRewriter`], the derive macro's
    /// `compile_from_args` JSON fallthrough, the test round-trip
    /// fixtures) routes through ONE inherent algebra method — the
    /// typed round-trip closure is structurally complete on the
    /// `Sexp` algebra.
    ///
    /// Frontier inspiration: MLIR's `mlir::parseAttribute(str, ctx)` —
    /// the typed-IR parser inverse of `printAttribute` lives on the
    /// same `Attribute` algebra as its printer dual; the substrate's
    /// [`Self::from_json`] is the unstructured-Rust peer on the
    /// `Sexp` algebra for the JSON canonical-form inverse, paired
    /// with [`Self::to_json`] as the closed round-trip. Racket's
    /// `(datum->syntax stx datum)` — the round-trip inverse of
    /// `(syntax->datum stx)`, projected at the `datum` algebra layer;
    /// `Self::from_json` is the substrate's peer at the `Sexp` layer
    /// (one algebra level lower than Racket's `syntax` wrapper).
    #[must_use]
    pub fn from_json(v: &serde_json::Value) -> Self {
        match v {
            serde_json::Value::Null => Self::Nil,
            serde_json::Value::Bool(b) => Self::boolean(*b),
            // Numeric arm — the (JSON `Number` → typed [`Atom`]
            // numeric variant) bifurcation lifts onto the closed-set
            // [`Atom`] algebra via [`Atom::from_json_number`]. Pre-lift
            // this arm carried its own inline three-branch cascade
            // (`n.as_i64()` sink to [`Self::int`] then `n.as_f64()`
            // sink to [`Self::float`] then a `Self::int(0)` typed
            // floor for the structural-impossibility residual);
            // post-lift the WHOLE cascade binds at ONE typed projection
            // on the algebra so a delimiter swap of the numeric axis
            // (e.g. adding a `u64`-fitting arm for the
            // `serde-preserve-order` feature's `arbitrary_precision`
            // mode, extending [`Atom`] with a `Bigint` variant) extends
            // [`Atom::from_json_number`] ONCE — the outer [`Self::from_json`]
            // arm here delegates through the algebra with zero edits.
            // Structural dual of [`Atom::to_json`]'s [`Atom::Int`] /
            // [`Atom::Float`] arms one algebra layer over: the paired
            // FORWARD (typed variant → `JValue::Number`) AND INVERSE
            // (`JValue::Number` → typed variant) numeric-axis
            // projections both live on the closed-set [`Atom`] algebra,
            // and this outer [`Self::from_json`] arm binds to the
            // inverse peer at ONE typed method. Sibling-shape pin to
            // [`Self::Atom`]'s general delegation posture — the outer
            // `Sexp` layer wraps the atomic algebra's typed projection
            // via [`Self::Atom`] rather than re-deriving the
            // per-variant construction at this consumer.
            serde_json::Value::Number(n) => Self::Atom(Atom::from_json_number(n)),
            serde_json::Value::String(s) => Self::string(s.clone()),
            serde_json::Value::Array(items) => {
                Self::List(items.iter().map(Self::from_json).collect())
            }
            serde_json::Value::Object(map) => {
                let mut out = Vec::with_capacity(map.len() * 2);
                for (k, v) in map {
                    out.push(Self::keyword(crate::domain::camel_to_kebab(k)));
                    out.push(Self::from_json(v));
                }
                Self::List(out)
            }
        }
    }

    pub fn as_symbol(&self) -> Option<&str> {
        self.as_atom().and_then(Atom::as_symbol)
    }
    pub fn as_keyword(&self) -> Option<&str> {
        self.as_atom().and_then(Atom::as_keyword)
    }
    pub fn as_string(&self) -> Option<&str> {
        self.as_atom().and_then(Atom::as_string)
    }
    pub fn as_int(&self) -> Option<i64> {
        self.as_atom().and_then(Atom::as_int)
    }
    /// `Some(f)` for `Atom::Float(f)`, AND `Some(n as f64)` for
    /// `Atom::Int(n)` — caller convenience at the numeric-kwarg
    /// boundary. The Int-widening face lives at this consumer layer
    /// rather than at [`Atom::as_float`] (strict per the typed-identity
    /// discipline pinned at [`Atom::as_int`]'s docstring); the typed
    /// soft-projection algebra on `Atom` stays strict, and the
    /// `Sexp::as_float` consumer composes the strict typed projection
    /// with a fallback widening branch on `Atom::as_int`.
    pub fn as_float(&self) -> Option<f64> {
        let a = self.as_atom()?;
        a.as_float().or_else(|| a.as_int().map(|n| n as f64))
    }
    pub fn as_bool(&self) -> Option<bool> {
        self.as_atom().and_then(Atom::as_bool)
    }
    /// `foo` or `"foo"` — useful for names that may be authored either way.
    ///
    /// Structural-lift composition: routes through [`Sexp::as_atom`] + the
    /// algebra-level [`Atom::as_symbol_or_string`] union projection — the
    /// same `as_atom().and_then(Atom::as_X)` composition pattern
    /// [`Sexp::as_symbol`] / [`Sexp::as_keyword`] / [`Sexp::as_string`] /
    /// [`Sexp::as_int`] / [`Sexp::as_bool`] route through on the
    /// per-variant axis. Lifts the disjunctive
    /// `self.as_symbol().or_else(|| self.as_string())` composition at this
    /// site's pre-lift body (TWO `Sexp::as_atom` traversals — one per
    /// per-variant projection) onto ONE typed-algebra union projection
    /// reached via ONE `Sexp::as_atom` traversal.
    ///
    /// Composition law: `s.as_symbol_or_string() == s.as_atom().and_then(Atom::as_symbol_or_string)`
    /// for every [`Sexp`] `s`. See [`Atom::as_symbol_or_string`] for the
    /// algebra-level peer's docstring (per-variant family completion +
    /// theory grounding).
    pub fn as_symbol_or_string(&self) -> Option<&str> {
        self.as_atom().and_then(Atom::as_symbol_or_string)
    }

    /// The symbol in operator position — `Some(s)` iff this is a non-empty
    /// list whose first element is a symbol (`(defpoint …)` → `Some("defpoint")`).
    /// `None` for every other shape: a non-list (`foo`, `5`, `:kw`), the
    /// empty list `()`, and a list whose head is not a symbol (`(5 …)`,
    /// `(:kw …)`, `((nested) …)`).
    ///
    /// This is the *operator-position projection* — the structural query
    /// every form-dispatch site in the substrate keys on: "what operator
    /// does this form invoke?" Macroexpansion (`Expander::expand` looks up
    /// the head against the macro table; `macro_def_from` reads it to
    /// recognize a `defmacro` head) and the typed compilers
    /// (`compile_typed` / `compile_named_from_forms` match it against
    /// `T::KEYWORD`) all asked the same `self.as_list()?.first()?.as_symbol()`
    /// question inline. Naming it once makes "operator position" a primitive
    /// of the `Sexp` algebra rather than four byte-identical inline chains.
    ///
    /// This is the SOFT face of operator-position dispatch — it answers
    /// "is this form an invocation of some operator?" and yields `None`
    /// (skip / fall through) for everything that isn't, with no diagnostic.
    /// Its STRICT sibling is `TataraDomain::compile_from_sexp`, which on a
    /// matched-arity form distinguishes the empty-list and
    /// present-but-not-a-symbol head sub-modes to emit a rich
    /// `MissingHeadSymbol` rejection. The two are the dispatch (`head_symbol`)
    /// and the gate (`compile_from_sexp`) faces of the same projection;
    /// keeping both lets a site choose "skip silently" or "reject loudly"
    /// without re-deriving the head.
    ///
    /// `head_symbol` is the operator projection of [`Sexp::as_call`]: it
    /// keeps the head and discards the argument tail. The
    /// `as_list()?.first()?.as_symbol()` chain lives in ONE place
    /// (`as_call`); this is its first component.
    pub fn head_symbol(&self) -> Option<&str> {
        self.as_call().map(|(head, _)| head)
    }

    /// Decompose a call form into its operator and argument tail —
    /// `Some((op, args))` iff this is a non-empty list whose first element
    /// is a symbol, where `op` is that head symbol and `args` is the
    /// remaining elements (`&self[1..]`, possibly empty). `None` for every
    /// shape `head_symbol` rejects: a non-list, the empty list, and a list
    /// whose head is present but not a symbol.
    ///
    /// This is the *call-form decomposition* — the structural shape of a
    /// Lisp invocation: an operator applied to an argument tail. It pairs
    /// the operator-position projection (`head_symbol`) with the argument
    /// tail every dispatch site reads immediately after matching the
    /// operator. Macroexpansion (`Expander::expand`) applies the matched
    /// macro to `&list[1..]`; the typed compilers (`compile_typed`,
    /// `compile_named_from_forms`) feed `&list[1..]` into
    /// `T::compile_from_args`. Before this query each site bound
    /// `as_list()` for the tail AND independently called `head_symbol()`
    /// (which itself re-derives `as_list().first()`) for the operator —
    /// two traversals of the same list, two projections. `as_call` yields
    /// both from one match, so the operator and its arguments can never
    /// drift out of agreement at a dispatch site.
    ///
    /// Soft face, like `head_symbol`: it answers "is this an invocation of
    /// some operator, and what are its arguments?" and yields `None` (skip
    /// / fall through) for everything that isn't, with no diagnostic. The
    /// strict gate sibling is `TataraDomain::compile_from_sexp`, which
    /// distinguishes the empty-list and non-symbol-head sub-modes to reject
    /// loudly.
    pub fn as_call(&self) -> Option<(&str, &[Sexp])> {
        let list = self.as_list()?;
        let head = list.first()?.as_symbol()?;
        Some((head, &list[1..]))
    }

    /// Canonical call-form outer constructor — composes the atomic-
    /// payload construct family's [`Self::symbol`] (the head-position
    /// construct on the 6-of-12 atomic carving of [`SexpShape`]) with
    /// the residual-axis construct family's [`Self::list`] (via
    /// `std::iter::once(head_sexp).chain(args)`) to build a symbol-
    /// headed list-shaped [`Sexp`] value at ONE site on the closed-set
    /// [`Sexp`] algebra. The call-form section-for-retraction sibling
    /// of the existing [`Self::as_call`] soft-projection ([`Option<(&
    /// str, &[Sexp])>`]): where the projection soft-decomposes a
    /// symbol-headed list into its head symbol and argument tail, this
    /// constructor embeds a fresh (head string, item sequence) pair
    /// into the matching call-shaped wrapper.
    ///
    /// Composition sibling of the atomic-payload construct family
    /// ([`Self::symbol`], [`Self::keyword`], [`Self::string`],
    /// [`Self::int`], [`Self::float`], [`Self::boolean`] — routing
    /// through the typed [`Atom`] family on the 6-of-12 atomic carving),
    /// the quote-family construct family ([`Self::quote`],
    /// [`Self::quasiquote`], [`Self::unquote`], [`Self::unquote_splice`]
    /// — routing through the typed [`QuoteForm::wrap`] family on the
    /// 4-of-12 quote-family carving), and the residual-axis construct
    /// [`Self::list`] (routing owned or iterable item sequences into
    /// the tuple-variant on the 2-of-12 residual carving): those close
    /// the (construct, project) algebra dual on their respective
    /// STRUCTURAL carvings; this closes the (construct, project)
    /// algebra dual on the SYMBOL-HEADED-LIST TYPED DECOMPOSITION — the
    /// load-bearing shape every Lisp invocation, every `(defX …)`
    /// typed-domain call form, and every macroexpander template head
    /// takes on the outer [`Sexp`] algebra.
    ///
    /// Composition law (forward, through the outer algebra's atomic +
    /// residual construct families): `Sexp::call(head, args) ==
    /// Sexp::list(std::iter::once(Sexp::symbol(head)).chain(args))` for
    /// every `head: impl Into<String>` + `args: impl IntoIterator<Item
    /// = Sexp>`. The body binds through the SAME two construct methods
    /// consumers already reach for when threading a head-then-rest
    /// sequence into a call form — the composition law lifts that
    /// two-method inline pattern to ONE named query on the outer
    /// [`Sexp`] algebra.
    ///
    /// Round-trip law (section-for-retraction with the soft-projection
    /// sibling): for every `head: &str` + `args: Vec<Sexp>`,
    /// `Sexp::call(head, args.clone()).as_call() == Some((head,
    /// args.as_slice()))` — the outer algebra's call-form typed
    /// constructor pairs section-for-retraction with the outer
    /// algebra's soft call-form projection, and the (head symbol,
    /// args slice) cross-projection preserves identity. Keyword-
    /// matched round-trip law: for every `head: &str` + `args:
    /// Vec<Sexp>`, `Sexp::call(head, args.clone()).as_call_to(head) ==
    /// Some(args.as_slice())` — the keyword-typed projection recovers
    /// the args tail iff its argument keyword matches the constructor's
    /// head. Head-symbol composition law: `Sexp::call(head,
    /// args).head_symbol() == Some(head.as_str())` for every `head:
    /// impl Into<String>` + `args: impl IntoIterator<Item = Sexp>` —
    /// the head-position projection recovers the constructor's head
    /// byte-for-byte.
    ///
    /// Outer-shape composition law: `Sexp::call(head, args).shape() ==
    /// SexpShape::List` for every input — a call form is a list-shaped
    /// [`Sexp`], and the outer-shape identity binds through the typed-
    /// shape lattice at the residual arm. Structural-carving-marker
    /// composition law: `Sexp::call(head, args).as_structural_kind()
    /// == Some(StructuralKind::List)` — the residual-axis carving
    /// marker binds through the closed-set [`StructuralKind`] algebra
    /// at ONE arm, symmetric with the atomic-axis's `Sexp::X_atom(
    /// payload).as_atom_kind() == Some(AtomKind::X)` marker
    /// composition.
    ///
    /// Pre-lift the `Sexp::List(std::iter::once(Sexp::symbol(head))
    /// .chain(args).collect())` composition (or equivalently the
    /// `Sexp::List(vec![Sexp::symbol(head), args...])` welded triple)
    /// appeared inline at every consumer that builds a call-shaped
    /// [`Sexp`] value — well past the ≥2 PRIME-DIRECTIVE trigger once
    /// the call-form shape is named. Post-lift consumers that have a
    /// head string + an owned or iterable sequence of args bind to ONE
    /// typed-algebra method on the outer [`Sexp`] algebra with the
    /// `impl Into<String>` bound on the head absorbing `&str` /
    /// `String` / `&String` and the `impl IntoIterator<Item = Sexp>`
    /// bound on the args absorbing `Vec<Sexp>` / `[Sexp; N]` /
    /// `.map(...)` chains without a per-site `.collect::<Vec<Sexp>>()`
    /// coercion.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 1 — typed entry; the
    /// (head string, args sequence, [`Self::List`] tuple-variant
    /// constructor) triple binds at ONE typed-algebra method on the
    /// outer [`Sexp`] algebra, closing the call-form (construct,
    /// project) algebra dual pair with [`Self::as_call`] /
    /// [`Self::as_call_to`] / [`Self::head_symbol`]. THEORY.md §II.1
    /// invariant 2 — free middle; every consumer that has a head
    /// string + an owned or iterable sequence of args and wants to
    /// build a call-shaped [`Sexp`] routes through the SAME typed
    /// method, so a regression that drifts one consumer's construction
    /// from the others (e.g. a copy-edit that emits `Sexp::keyword(
    /// head)` for the head position, or that swaps in a `Sexp::string`
    /// head that [`Self::as_call`] then rejects at the projection
    /// site) cannot reach the substrate's runtime. THEORY.md §V.1 —
    /// knowable platform; the call-form typed-construct becomes a TYPE
    /// projection on the substrate's outer [`Sexp`] algebra sitting
    /// next to the typed-project family [`Self::as_call`] /
    /// [`Self::as_call_to`] rather than bare tuple-variant constructor
    /// paired with per-site `Sexp::List(vec![Sexp::symbol(...), ...])`
    /// discipline. THEORY.md §VI.1 — generation over composition; the
    /// call-form pair emerges from ONE typed-algebra composition
    /// through [`Self::list`] composed with [`Self::symbol`] rather
    /// than from per-consumer per-callsite literals; a future call-
    /// form shape extension (e.g. a keyword-headed call form for a
    /// Kernel-style applicative-vs-operative split) lands as ONE peer
    /// constructor on this algebra alongside the residual, quote-
    /// family, and atomic-payload construct families.
    #[must_use]
    pub fn call<H, I>(head: H, args: I) -> Self
    where
        H: Into<String>,
        I: IntoIterator<Item = Sexp>,
    {
        Self::list(std::iter::once(Self::symbol(head)).chain(args))
    }

    /// Canonical named-call-form outer constructor — composes the call-
    /// form typed constructor [`Self::call`] with the atomic-payload
    /// construct family's [`Self::symbol`] (for the NAME slot) via
    /// `std::iter::once(Self::symbol(name)).chain(spec_args)` to build a
    /// `(head NAME spec_args…)` symbol-headed named list-shaped [`Sexp`]
    /// value at ONE site on the closed-set [`Sexp`] algebra. The named-
    /// call-form section-for-retraction sibling of the existing
    /// [`Self::as_named_call_to`] soft-projection ([`Option<crate::error::
    /// Result<(&str, &[Sexp])>>`]): where the projection soft-decomposes
    /// a `(<keyword> NAME spec_args…)` symbol-headed list into its NAME
    /// symbol and spec args tail through the named-form gate
    /// ([`crate::compile::split_name_slot`]), this constructor embeds a
    /// fresh `(head string, name string, spec_args sequence)` triple
    /// into the matching named-call-shaped wrapper. Composition sibling
    /// of the call-form construct [`Self::call`] on the outer algebra:
    /// where [`Self::call`] closes the (construct, project) dual on the
    /// CALL-FORM TYPED DECOMPOSITION (`(head args…)`), this closes the
    /// dual on the NAMED-CALL-FORM TYPED DECOMPOSITION (`(head NAME
    /// spec_args…)`) — the load-bearing shape every `(defX NAME …)`
    /// typed-domain named authoring form takes on the outer [`Sexp`]
    /// algebra, and the section-for-retraction dual of the
    /// [`crate::compile::split_name_slot`] gate at the value level.
    ///
    /// Composition law (forward, through the call-form + atomic-payload
    /// construct families): `Sexp::named_call(head, name, spec_args) ==
    /// Sexp::call(head, std::iter::once(Sexp::symbol(name)).chain(
    /// spec_args))` for every `head: impl Into<String>` + `name: impl
    /// Into<String>` + `spec_args: impl IntoIterator<Item = Sexp>`. The
    /// body binds through the SAME two construct methods consumers
    /// already reach for when threading a head-then-name-then-rest
    /// sequence into a named call form — the composition law lifts that
    /// two-method inline pattern to ONE named query on the outer
    /// [`Sexp`] algebra.
    ///
    /// Round-trip law (section-for-retraction with the named-form soft-
    /// projection): for every `head: &'static str` + `name: &str` +
    /// `spec_args: Vec<Sexp>`, `Sexp::named_call(head, name, spec_args
    /// .clone()).as_named_call_to(head) == Some(Ok((name, spec_args
    /// .as_slice())))` — the outer algebra's named-call-form typed
    /// constructor pairs section-for-retraction with the outer
    /// algebra's soft named-call-form projection, and the (head symbol,
    /// NAME symbol, spec args slice) cross-projection preserves
    /// identity. Call-form projection composition: `Sexp::named_call(
    /// head, name, spec_args).as_call() == Some((head,
    /// once(Sexp::symbol(name)).chain(spec_args).collect().as_slice()
    /// ))` — the call-form soft-projection recovers `(head, [name,
    /// spec_args…])` with the NAME symbol as the first arg, mirroring
    /// the [`Self::call`] round-trip on the encompassing call algebra.
    /// Keyword-matched round-trip law: for every `head: &'static str` +
    /// `name: &str` + `spec_args: Vec<Sexp>`, `Sexp::named_call(head,
    /// name, spec_args.clone()).as_call_to(head) == Some(
    /// [Sexp::symbol(name), spec_args…].as_slice())` — the keyword-
    /// typed projection recovers the NAME-headed args tail iff its
    /// argument keyword matches the constructor's head. Head-symbol
    /// composition law: `Sexp::named_call(head, name, spec_args)
    /// .head_symbol() == Some(head.as_str())` — the head-position
    /// projection recovers the constructor's head byte-for-byte.
    ///
    /// Outer-shape composition law: `Sexp::named_call(head, name,
    /// spec_args).shape() == SexpShape::List` for every input — a
    /// named call form is a list-shaped [`Sexp`], the outer-shape
    /// identity binds through the typed-shape lattice at the residual
    /// arm. Structural-carving-marker composition law: `Sexp::
    /// named_call(head, name, spec_args).as_structural_kind() ==
    /// Some(StructuralKind::List)` — the residual-axis carving marker
    /// binds through the closed-set [`StructuralKind`] algebra at ONE
    /// arm, symmetric with [`Self::call`]'s residual-arm marker
    /// composition.
    ///
    /// Named-form gate composition law: `crate::compile::split_name_slot(
    /// &Sexp::named_call(head, name, spec_args).as_call_to(head)
    /// .unwrap(), head) == Ok((name, spec_args.as_slice()))` — the
    /// substrate's named-form arity + NAME-shape gate accepts every
    /// output of this constructor byte-for-byte, closing the section-
    /// for-retraction pair at the gate level as well as at the
    /// projection level. A constructor emission that drifts into a
    /// missing-NAME shape (empty spec_args yields `(head)`, which the
    /// call-form projection recovers but the named-form gate rejects
    /// with `NamedFormMissingName`) or a non-symbol-NAME shape
    /// (`Sexp::keyword(name)` for the NAME position, which the gate
    /// rejects with `NamedFormNonSymbolName`) becomes structurally
    /// impossible — the `impl Into<String>` NAME bound admits string
    /// payloads only, and the [`Self::symbol`] wrap routes to the
    /// symbol atom variant `as_symbol_or_string` accepts.
    ///
    /// Pre-lift the `Sexp::call(head, std::iter::once(Sexp::symbol(
    /// name)).chain(spec_args))` composition (or equivalently the
    /// `Sexp::List(vec![Sexp::symbol(head), Sexp::symbol(name),
    /// spec_args...])` welded quadruple) appeared inline at every
    /// consumer that builds a `(defX NAME …)`-shaped [`Sexp`] value
    /// — well past the ≥2 PRIME-DIRECTIVE trigger once the named
    /// call-form shape is named. Post-lift consumers that have a head
    /// string + a NAME string + an owned or iterable sequence of spec
    /// args bind to ONE typed-algebra method on the outer [`Sexp`]
    /// algebra with the two `impl Into<String>` bounds absorbing `&str`
    /// / `String` / `&String` on both string positions and the
    /// `impl IntoIterator<Item = Sexp>` bound on the spec args
    /// absorbing `Vec<Sexp>` / `[Sexp; N]` / `.map(...)` chains without
    /// a per-site `.collect::<Vec<Sexp>>()` coercion.
    ///
    /// Frontier inspiration: Racket's `syntax-parse`
    /// `(~datum keyword) name:id spec ...` pattern binds the NAME slot
    /// through the `name:id` capture binder and consumers reference it
    /// downstream; the constructor peer on the same surface is
    /// `syntax-e` composed with `datum->syntax` wrapping a
    /// `(list #'keyword name-id spec-list ...)` triple. `Sexp::
    /// named_call` is the unstructured-Rust peer — a section-for-
    /// retraction constructor on the outer algebra that mirrors the
    /// `~datum keyword name:id spec ...` pattern's NAME capture on the
    /// construct side. Tree-sitter's `query`-matched named captures
    /// have the same shape on the tree side: the query pattern
    /// binds a NAME capture, the constructor peer (`ts_node_new`
    /// composed with `ts_node_field_set`) embeds a fresh NAME child at
    /// the corresponding field slot. The typed structural rejection
    /// chain the substrate's named-form gate emits
    /// ([`crate::error::LispError::NamedFormMissingName`],
    /// [`crate::error::LispError::NamedFormNonSymbolName`]) is
    /// preserved by construction — the constructor cannot emit a
    /// value the gate rejects, symmetric with the `~datum` /
    /// `name:id` reader-side rejection that fires BEFORE any
    /// downstream binding sees the drifted shape.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 1 — typed entry; the
    /// (head string, NAME string, spec args sequence, [`Self::call`]
    /// call-form constructor) quadruple binds at ONE typed-algebra
    /// method on the outer [`Sexp`] algebra, closing the named-call-
    /// form (construct, project) algebra dual pair with
    /// [`Self::as_named_call_to`] / [`Self::as_named_call_to_any`] on
    /// the projection side and [`crate::compile::split_name_slot`] on
    /// the gate side. THEORY.md §II.1 invariant 2 — free middle;
    /// every consumer that has a head + NAME + spec args and wants to
    /// build a named-call-shaped [`Sexp`] routes through the SAME
    /// typed method, so a regression that drifts one consumer's
    /// construction from the others (e.g. a copy-edit that emits
    /// `Sexp::keyword(name)` for the NAME position, which the
    /// named-form gate would reject with `NamedFormNonSymbolName`)
    /// cannot reach the substrate's runtime. THEORY.md §V.1 —
    /// knowable platform; the named-call-form typed-construct becomes
    /// a TYPE projection on the substrate's outer [`Sexp`] algebra
    /// sitting next to the typed-project family [`Self::
    /// as_named_call_to`] / [`Self::as_named_call_to_any`] +
    /// [`crate::ast::iter_named_calls_to`] /
    /// [`crate::ast::iter_named_calls_to_any`] rather than a per-site
    /// inline composition. THEORY.md §VI.1 — generation over
    /// composition; the named-call-form pair emerges from ONE typed-
    /// algebra composition through [`Self::call`] composed with
    /// [`Self::symbol`] rather than from per-consumer per-callsite
    /// literals; a future named-form shape extension (e.g. a
    /// dotted-NAME form, or a typed-NAME form where the NAME slot
    /// carries a compile-time-decoded typed witness) lands as ONE
    /// peer constructor on this algebra alongside the call-form,
    /// residual, quote-family, and atomic-payload construct
    /// families.
    #[must_use]
    pub fn named_call<H, N, I>(head: H, name: N, spec_args: I) -> Self
    where
        H: Into<String>,
        N: Into<String>,
        I: IntoIterator<Item = Sexp>,
    {
        Self::call(head, std::iter::once(Self::symbol(name)).chain(spec_args))
    }

    /// Decompose a call form into its argument tail IFF the head matches the
    /// supplied `keyword` — `Some(args)` iff this is a non-empty list whose
    /// first element is a symbol equal to `keyword`, where `args` is the
    /// remaining elements (`&self[1..]`, possibly empty). `None` for every
    /// shape `as_call` rejects AND for every call whose head is present but
    /// differs from `keyword`.
    ///
    /// This is the *keyword-typed call decomposition* — the natural
    /// extension of [`Sexp::as_call`] for the "is this a call to ONE
    /// specific operator?" question every typed-domain dispatch site asks
    /// after macroexpansion. [`compile_typed`](crate::compile::compile_typed)
    /// and [`compile_named_from_forms`](crate::compile::compile_named_from_forms)
    /// both opened the same two-step chain inline —
    /// `if let Some((head, args)) = form.as_call() { if head == T::KEYWORD { … } }`
    /// — at every form they walked; the chain IS this projection. Naming
    /// it lifts "is this form a call to T?" from a two-step inline pattern
    /// to ONE structural query on the `Sexp` algebra. A regression that
    /// drifts one consumer's comparison from `==` to `!= `, or that
    /// compares against a different label than `T::KEYWORD` (e.g.
    /// substring-grepping the rendered head), becomes structurally
    /// impossible: there is exactly one implementation both dispatchers
    /// route through.
    ///
    /// Soft face, like the rest of the `as_*` family: it answers "is this
    /// a call to `keyword`, and what are its arguments?" and yields `None`
    /// for everything that isn't (skip / fall through), with no
    /// diagnostic. The strict gate sibling is
    /// `TataraDomain::compile_from_sexp`, which distinguishes the
    /// not-a-list / empty-list / non-symbol-head / wrong-keyword
    /// sub-modes to reject loudly. The two are the dispatch
    /// (`as_call_to`) and the gate (`compile_from_sexp`) faces of the
    /// same projection; keeping both lets a site choose "skip silently"
    /// or "reject loudly" without re-deriving the head.
    ///
    /// Structural identity binding it to its siblings:
    ///   * `as_call_to(keyword) == as_call().and_then(|(h, args)| (h == keyword).then_some(args))`
    ///   * `as_call_to(keyword).is_some() == (head_symbol() == Some(keyword))`
    ///
    /// The returned `&[Sexp]` borrows from the list's tail verbatim — no
    /// copy, no allocation, same lifetime as [`Sexp::as_call`]'s tail.
    ///
    /// Slice-side sibling: [`iter_calls_to`] lifts this per-form projection
    /// onto a `&[Sexp]`, yielding the args slices of every matching form in
    /// source order — the substrate's typed-keyword filter over a batch of
    /// forms, structurally bound to this per-form projection via the
    /// closed-form composition
    /// `iter_calls_to(forms, k) == forms.iter().filter_map(|f| f.as_call_to(k))`.
    pub fn as_call_to(&self, keyword: &str) -> Option<&[Sexp]> {
        let (head, args) = self.as_call()?;
        (head == keyword).then_some(args)
    }

    /// Decompose a call form whose head decodes through a caller-supplied
    /// classifier — `Some((decoded, args))` iff this is a non-empty list
    /// whose first element is a symbol AND `decode(head)` returns
    /// `Some(decoded)`, where `args` is the remaining elements
    /// (`&self[1..]`, possibly empty). `None` for every shape
    /// [`Sexp::as_call`] rejects AND for every call whose head is present
    /// but `decode` rejects.
    ///
    /// This is the *typed-decoded call decomposition* — the closure-typed
    /// extension of [`Sexp::as_call_to`] for the "is this a call whose head
    /// belongs to a CLOSED SET (or a LIVE REGISTRY) that decodes to a typed
    /// witness?" question. Where [`Sexp::as_call_to`] filters by ONE
    /// constant keyword, `as_call_to_any` filters AND TYPES by a caller-
    /// supplied projection — every dispatch site that asks "is this form
    /// an invocation of any of N operators, decoded as a typed enum or
    /// resolved against a runtime table?" binds to ONE structural query
    /// on the `Sexp` algebra. Two consumers route through it:
    ///
    ///   * The macro-expander's `macro_def_from` — closed-set classifier:
    ///     `as_call_to_any(MacroDefHead::from_keyword)` decides which of
    ///     `{defmacro, defpoint-template, defcheck}` a top-level form
    ///     invokes, decoded to the typed `MacroDefHead` enum. Pre-lift the
    ///     site opened the same three-step chain inline — `let Some(list)
    ///     = form.as_list()…; let Some(head) = form.head_symbol()…; let
    ///     Some(decoded) = MacroDefHead::from_keyword(head)…`.
    ///   * The macro-expander's `Expander::expand` — live-registry
    ///     classifier: `as_call_to_any(|h| self.macros.get(h))` decides
    ///     which of the registered macros (a `HashMap<String, MacroDef>`
    ///     populated by `expand_program`'s `defmacro` recognition) a form
    ///     invokes, decoded to `&MacroDef`. Pre-lift the site opened the
    ///     same `as_list() + as_call() + self.macros.get(head)` chain
    ///     inline — `as_list()` for the children-walk fallthrough,
    ///     `as_call()` for the (head, args) pair (which itself re-derives
    ///     `as_list()` internally), and `self.macros.get(head)` for the
    ///     registry lookup.
    ///
    /// Naming the projection lifts "is this form a call to any of N
    /// operators, decoded to T?" from the three-step inline pattern to
    /// ONE structural query — closed-set enum classifier OR live-registry
    /// HashMap classifier, the family primitive is uniform under both.
    ///
    /// Soft face, like the rest of the `as_*` family: it answers "is this
    /// a call whose head decodes through `F`, and what are its arguments?"
    /// and yields `None` for everything that isn't (skip / fall through),
    /// with no diagnostic. The strict gate sibling stays
    /// `TataraDomain::compile_from_sexp` — that distinguishes the
    /// not-a-list / empty-list / non-symbol-head / wrong-keyword sub-modes
    /// to reject loudly for a single-keyword consumer. The two are the
    /// closed-set-decoded dispatch (`as_call_to_any`) and the
    /// single-keyword gate (`compile_from_sexp`) faces of the typed-domain
    /// recognition problem; keeping both lets a site choose "skip
    /// silently if the head isn't ours" or "reject loudly if the head
    /// isn't the exact keyword" without re-deriving the head.
    ///
    /// Structural identity binding it to its siblings:
    ///   * `as_call_to_any(decode) == as_call().and_then(|(h, args)| decode(h).map(|d| (d, args)))`
    ///   * `as_call_to(k) == as_call_to_any(|h| (h == k).then_some(())).map(|(_, a)| a)` (modulo the discarded `()`)
    ///   * `as_call_to_any(decode).is_some() == as_call().map_or(false, |(h, _)| decode(h).is_some())`
    ///
    /// The returned `&[Sexp]` borrows from the list's tail verbatim — no
    /// copy, no allocation, same lifetime as [`Sexp::as_call`]'s tail.
    /// `T` is owned because `decode` is `FnOnce(&str) -> Option<T>` and a
    /// `&'_ str` borrow into the head symbol would not outlive the helper
    /// boundary; consumers projecting to a typed `Copy` enum (e.g.
    /// `MacroDefHead`) get the value directly, consumers projecting to a
    /// borrowed `&'static str` (a closed-set head) project to
    /// `&'static str` and inherit the static lifetime through the
    /// classifier.
    ///
    /// Slice-side sibling: [`iter_calls_to_any`] lifts this per-form
    /// projection onto a `&[Sexp]`, yielding the `(decoded, &[Sexp])`
    /// pair of every matching form in source order — the substrate's
    /// typed-decoded filter over a batch of forms, structurally bound
    /// to this per-form projection via the closed-form composition
    /// `iter_calls_to_any(forms, decode) == forms.iter().filter_map(|f|
    /// f.as_call_to_any(&mut decode))`. The slice-side primitive
    /// promotes the closure constraint from [`FnOnce`] (per-form, one
    /// call per invocation) to [`FnMut`] (slice-side, one call per
    /// element) so a decoder that captures mutable state (a counter, a
    /// registry cache) maintains state across the batch walk.
    pub fn as_call_to_any<F, T>(&self, decode: F) -> Option<(T, &[Sexp])>
    where
        F: FnOnce(&str) -> Option<T>,
    {
        let (head, args) = self.as_call()?;
        decode(head).map(|d| (d, args))
    }

    /// Decompose a named call form (a `(<keyword> NAME :k v …)` shape) whose
    /// head decodes through a caller-supplied classifier — `Some(Ok((decoded,
    /// name, spec_args)))` iff this is a non-empty list whose first element
    /// is a symbol AND `decode(head)` returns `Some((decoded, kw))` AND the
    /// remaining elements split cleanly into a NAME slot (symbol or string
    /// at position 1) and a spec args tail (position 2..), `Some(Err(…))` iff
    /// the head decodes but the NAME slot is missing
    /// ([`LispError::NamedFormMissingName`]) or non-symbol-or-string
    /// ([`LispError::NamedFormNonSymbolName`]), `None` for every shape
    /// [`Sexp::as_call_to_any`] rejects AND for every call whose head is
    /// present but `decode` returns `None` for.
    ///
    /// This is the *per-form named-classifier projection* — the per-form
    /// peer of [`iter_named_calls_to_any`] on the slice algebra and of
    /// [`crate::macro_expand::Expander::expand_and_collect_named_calls_to_any`]
    /// on the expander surface. Closes the (per-form × classifier × named)
    /// corner of the soft-dispatch cube the substrate's per-form algebra
    /// (`as_call_to{,_any}`) and slice algebra (`iter_calls_to{,_any}`,
    /// `iter_named_calls_to{,_any}`) collectively shape — pre-lift the cube
    /// at the per-form × named corner was "(composed inline at each named
    /// consumer)" (the documented gap the cube table inside
    /// [`iter_named_calls_to_any`] called out), post-lift the per-form ×
    /// named row binds to ONE primitive every per-form named consumer
    /// composes through:
    ///
    /// |                | bare-kwargs                  | named NAME-then-kwargs               |
    /// |----------------|------------------------------|--------------------------------------|
    /// | per-form       | [`Sexp::as_call_to_any`]     | `as_named_call_to_any` (this)        |
    /// | slice          | [`iter_calls_to_any`]        | [`iter_named_calls_to_any`]          |
    /// | expander       | `expand_and_collect_calls_to_any` | `expand_and_collect_named_calls_to_any` |
    ///
    /// The slice-side [`iter_named_calls_to_any`] now routes through THIS
    /// per-form primitive via the SAME `forms.iter().filter_map(_)`
    /// skeleton [`iter_calls_to_any`] uses to route through
    /// [`Sexp::as_call_to_any`], so a regression that drifts ONE row's
    /// instrumentation, span-aware borrow walker, or fused-iterator
    /// invariant from the bare row to the named row (or vice versa) is
    /// structurally impossible.
    ///
    /// Composes [`Sexp::as_call_to_any`] with
    /// [`crate::compile::split_name_slot`]: the classifier filter precedes
    /// the named gate, mirroring how `split_name_slot` is composed AFTER
    /// the classifier-decoded args tail is already in hand inside
    /// [`iter_named_calls_to_any`]. Decoder signature `FnOnce(&str) ->
    /// Option<(T, &'static str)>` pairs the typed witness `T` with the
    /// canonical static keyword threaded through the
    /// `NamedFormMissingName.keyword` / `NamedFormNonSymbolName.keyword`
    /// slots of the named-form gate — the `&'static` constraint pins the
    /// same compile-time discipline [`crate::compile::split_name_slot`]'s
    /// `keyword: &'static str` parameter pins at the slice-side boundary,
    /// AND that the slice-side decoder signature pins on the slice
    /// algebra.
    ///
    /// Three-arm result shape — `Option<Result<…>>` — preserves both the
    /// classifier filter face (`None` for "not our head, skip silently",
    /// matching the per-form soft-projection posture of every other `as_*`
    /// method on `Sexp`) AND the named gate face (`Err` for "matched head
    /// but malformed NAME", surfacing the typed structural-rejection
    /// variants `LispError::NamedFormMissingName` /
    /// `LispError::NamedFormNonSymbolName` the slice-side and expander-
    /// surface consumers already short-circuit on). A consumer that wants
    /// "fold over every per-form result, short-circuiting on the first
    /// malformed NAME" composes `.transpose()` (yielding
    /// `Result<Option<…>>`) and `?`-routes the outer `Result`; a consumer
    /// that wants "skip every non-matching form AND every malformed
    /// matched form" composes `.and_then(|res| res.ok())` (yielding
    /// `Option<(T, &str, &[Sexp])>`); a consumer that wants the raw
    /// three-arm shape pattern-matches directly.
    ///
    /// Two plausible future consumer shapes the per-form named-classifier
    /// projection admits with no boilerplate:
    ///   * **LSP hover tooltip** — an authoring tool that surfaces a
    ///     tooltip on the symbol under the cursor wants to ask "is THIS
    ///     form (the one I just resolved to under the cursor) a named
    ///     call to any registered domain, decoded to a typed kind, with
    ///     the borrowed NAME slot extracted for the tooltip body?". Pre-
    ///     lift the tool would re-derive `form.as_call_to_any(decode)
    ///     .and_then(|((kind, kw), args)| split_name_slot(args,
    ///     kw).ok().map(|(name, rest)| (kind, name, rest)))` inline;
    ///     post-lift the tool binds to ONE primitive.
    ///   * **REPL single-form dispatcher** — a `:dispatch <classifier>
    ///     <form>` command that walks a single form through the
    ///     registry classifier, reporting the typed kind AND the NAME
    ///     slot (for "you said `(defmonitor my-monitor …)`, I see
    ///     `Monitor` named `my-monitor` with 3 spec args"). Pre-lift
    ///     the REPL would re-derive the same inline composition; post-
    ///     lift the REPL binds to ONE primitive, sibling shape to how
    ///     [`Sexp::as_call_to_any`] backs the slice-side dispatcher
    ///     [`iter_calls_to_any`].
    ///
    /// Structural identity binding it to its siblings:
    ///   * `as_named_call_to_any(decode) == as_call_to_any(decode).map(|((d, kw), args)| split_name_slot(args, kw).map(|(name, rest)| (d, name, rest)))`
    ///   * `as_named_call_to(k) == as_named_call_to_any(|h| (h == k).then_some(((), k))).map(|res| res.map(|(_, name, rest)| (name, rest)))`
    ///   * `as_named_call_to_any(decode).is_none() == as_call_to_any(decode).is_none()` (the classifier filter face is identical to the bare-kwargs sibling's)
    ///
    /// The returned `&str` NAME slot and `&[Sexp]` spec args tail borrow
    /// from `&self` verbatim — no copy, no allocation, same lifetime as
    /// [`Sexp::as_call_to_any`]'s tail AND [`crate::compile::split_name_slot`]'s
    /// pair. `T` is owned because the underlying [`Sexp::as_call_to_any`]
    /// classifier is `FnOnce(&str) -> Option<(T, &'static str)>` and `T`
    /// must outlive the helper boundary; consumers projecting to a typed
    /// `Copy` enum (e.g. a closed-set `Kind`) get the value directly,
    /// consumers projecting to a borrowed `&'static str` (a closed-set
    /// head sourced from `ClosedSet::ALL.label()`) project to `&'static
    /// str` and inherit the static lifetime through the classifier.
    ///
    /// Soft face on the classifier filter, strict face on the named gate:
    /// "is this a named call whose head decodes through `F`, and what
    /// are its NAME and spec args?" yielding `None` for "not our head"
    /// (skip / fall through, no diagnostic) AND `Some(Err(…))` for "our
    /// head but malformed NAME" (reject loudly, structural variant). The
    /// soft-classifier-then-strict-named composition matches the
    /// slice-side `iter_named_calls_to_any` yielded `Result` shape (with
    /// non-matching forms skipped by the iterator filter) and the
    /// expander-surface `expand_and_collect_named_calls_to_any` collect
    /// shape (with `Result::collect` short-circuiting on the first
    /// malformed NAME) — every layer of the cube preserves both faces.
    ///
    /// Theory anchor: THEORY.md §VI.1 — generation over composition; the
    /// per-form × classifier × named cell of the soft-dispatch cube is a
    /// CONSEQUENCE of [`Sexp::as_call_to_any`] + [`crate::compile::split_name_slot`],
    /// named on the substrate's `Sexp` algebra rather than re-derived
    /// inline at every per-form named consumer site. THEORY.md §V.1 —
    /// knowable platform; the per-form named-classifier projection
    /// becomes a NAMED primitive on the `Sexp` algebra, discoverable by
    /// any future authoring tool (LSP, REPL, `tatara-check`) that holds
    /// a single form in isolation. THEORY.md §II.1 invariant 2 — free
    /// middle; the slice-side sibling [`iter_named_calls_to_any`] now
    /// routes through this per-form primitive via the same
    /// `forms.iter().filter_map(_)` skeleton the bare-kwargs row uses
    /// to route through [`Sexp::as_call_to_any`], so the bare and named
    /// rows share ONE filter-and-fuse implementation skeleton on the
    /// `Sexp`/`&[Sexp]` algebras.
    ///
    /// Frontier inspiration: MLIR's `mlir::dyn_cast<NamedOpInterface>(op)`
    /// — the typed downcast from a polymorphic IR node onto a NAMED-op
    /// interface that exposes both the typed witness AND the
    /// symbol-name accessor is the MLIR idiom; `as_named_call_to_any` is
    /// the unstructured-Rust peer on the substrate's `Sexp` algebra,
    /// with `Option<Result<(T, &str, &[Sexp])>>` standing in for MLIR's
    /// typed-downcast-then-name-accessor pair, and the `Result` face
    /// carrying the typed structural rejection MLIR encodes via verifier
    /// diagnostics. Racket's `syntax-parse` `~or* ((~datum defX) name:id
    /// arg ...) ((~datum defY) name:id arg ...)` on a single syntax
    /// object — typed named-form decomposition with `name:id` capture
    /// binding is the Racket idiom; this method is the per-form
    /// Rust-typed peer with the typed structural rejection
    /// (`NamedFormMissingName` / `NamedFormNonSymbolName`) preserved
    /// across the boundary.
    pub fn as_named_call_to_any<F, T>(
        &self,
        decode: F,
    ) -> Option<crate::error::Result<(T, &str, &[Sexp])>>
    where
        F: FnOnce(&str) -> Option<(T, &'static str)>,
    {
        self.as_call_to_any(decode).map(|((decoded, kw), args)| {
            let (name, spec_args) = crate::compile::split_name_slot(args, kw)?;
            Ok((decoded, name, spec_args))
        })
    }

    /// Decompose a named call form whose head matches a constant
    /// `keyword` — `Some(Ok((name, spec_args)))` iff this is a non-empty
    /// list whose first element is the symbol `keyword` AND the remaining
    /// elements split cleanly into a NAME slot and a spec args tail,
    /// `Some(Err(…))` iff the head matches but the NAME slot is missing
    /// or non-symbol-or-string, `None` for every shape
    /// [`Sexp::as_call_to`] rejects.
    ///
    /// Constant-keyword sibling of [`Sexp::as_named_call_to_any`] and
    /// per-form sibling of [`iter_named_calls_to`] on the slice algebra.
    /// Routes through the typed-decoded sibling with a constant-classifier
    /// decoder (`|h| (h == keyword).then_some(((), keyword))`) — the same
    /// constant-classifier composition [`Sexp::as_call_to`] uses to route
    /// through [`Sexp::as_call_to_any`] on the bare-kwargs axis, and that
    /// [`iter_named_calls_to`] uses to route through
    /// [`iter_named_calls_to_any`] on the slice algebra. The discarded
    /// `()` typed witness (`then_some(((), keyword))`) is consumed by the
    /// wrapper projection so the consumer's per-form mapper sees only the
    /// `(name, spec_args)` borrowed pair, matching the bare projection
    /// signature on the named axis.
    ///
    /// `keyword: &'static str` threads verbatim through the
    /// `NamedFormMissingName.keyword` / `NamedFormNonSymbolName.keyword`
    /// slots of the named-form gate — same `&'static` discipline
    /// [`crate::compile::split_name_slot`] pins at its boundary, AND that
    /// [`iter_named_calls_to`] pins on the slice algebra. Consumers that
    /// want a runtime keyword whose lifetime is shorter use
    /// [`Sexp::as_named_call_to_any`] directly with a constant-classifier
    /// decoder that converts post-resolution.
    ///
    /// Structural identity binding it to its siblings:
    ///   * `as_named_call_to(k) == as_named_call_to_any(|h| (h == k).then_some(((), k))).map(|res| res.map(|(_, name, rest)| (name, rest)))`
    ///   * `as_named_call_to(k).is_none() == as_call_to(k).is_none()`
    ///   * `iter_named_calls_to(forms, k) == forms.iter().filter_map(|f| f.as_named_call_to(k))`
    ///
    /// Theory anchor: see [`Sexp::as_named_call_to_any`] — the constant-
    /// keyword sibling shares the same lift posture, threading the
    /// `&'static str` keyword constraint through the named-form gate's
    /// canonical-keyword slot rather than admitting an arbitrary runtime
    /// keyword.
    pub fn as_named_call_to(
        &self,
        keyword: &'static str,
    ) -> Option<crate::error::Result<(&str, &[Sexp])>> {
        self.as_named_call_to_any(move |h| (h == keyword).then_some(((), keyword)))
            .map(|res| res.map(|(_, name, rest)| (name, rest)))
    }

    /// Decompose an unquote-family form into its typed marker and inner
    /// expression — `Some((UnquoteForm::Unquote, inner))` iff this is `,x`
    /// (a [`Sexp::Unquote`] wrapper), `Some((UnquoteForm::Splice, inner))`
    /// iff this is `,@x` (a [`Sexp::UnquoteSplice`] wrapper), `None` for
    /// every other shape (Quote, Quasiquote, Nil, Atom, List).
    ///
    /// This is the *unquote-family projection* — the typed-marker peer of
    /// [`Sexp::as_call`] for the macro-template substitution surface. Where
    /// [`Sexp::as_call`] decomposes `(op args …)` into a `(head, args)`
    /// pair, `as_unquote` decomposes `,x` / `,@x` into a `(form, inner)`
    /// pair where `form: UnquoteForm` is the closed-set typed marker
    /// (`Unquote` for `,`, `Splice` for `,@`) and `inner: &Sexp` is the
    /// borrowed body. The pairing of `Sexp::Unquote ↔ UnquoteForm::Unquote`
    /// and `Sexp::UnquoteSplice ↔ UnquoteForm::Splice` is the structural
    /// invariant the macro-expander's substitution path keys every
    /// rejection on — naming the projection lifts the pair from
    /// per-callsite discipline (two `Sexp::Unquote(inner)` arms paired
    /// with two `UnquoteForm::Unquote` literals at distinct sites, two
    /// `Sexp::UnquoteSplice(inner)` arms paired with two
    /// `UnquoteForm::Splice` literals at distinct sites) into ONE typed
    /// projection both expansion strategies route through.
    ///
    /// Three consumers in [`macro_expand`](crate::macro_expand) route
    /// through this primitive:
    ///   * `compile_node` (bytecode-template compile path) — `,x` becomes
    ///     `TemplateOp::Subst(idx)`, `,@x` becomes `TemplateOp::Splice(idx)`;
    ///     both arms share the gate-1+gate-2 composition
    ///     `resolve_unquote_in_params(inner, params, form)?` keyed on the
    ///     typed `form` projection.
    ///   * `substitute` top-level (substitute fallback path) — `,x` resolves
    ///     to its bound value, `,@x` rejects with
    ///     `LispError::SpliceOutsideList` (a splice form with no containing
    ///     list to flatten into).
    ///   * `substitute` list-inner (substitute fallback path's per-item
    ///     walk) — `,@x` items splice their bound list/nil/scalar value
    ///     into the assembled list builder via
    ///     [`crate::macro_expand::splice_value_into`]; non-splice items
    ///     recurse into `substitute`.
    ///
    /// Pre-lift each site opened the same per-variant match arms —
    /// `Sexp::Unquote(inner) => … UnquoteForm::Unquote …` and
    /// `Sexp::UnquoteSplice(inner) => … UnquoteForm::Splice …` —
    /// independently. The (Sexp variant, UnquoteForm variant) pairing was
    /// load-bearing across distinct sites yet only enforced by callsite
    /// discipline. Post-lift the pair binds at ONE projection function the
    /// type system threads through `(UnquoteForm, &Sexp)`: a regression
    /// that drifts ONE site's pairing (e.g. a future emitter that matches
    /// `Sexp::Unquote(_)` but threads `UnquoteForm::Splice` into
    /// `unquote_target_symbol` — type-checks but renders a misleading
    /// diagnostic) becomes structurally impossible.
    ///
    /// Soft face, like the rest of the `as_*` family on `Sexp`: it answers
    /// "is this form an unquote-family marker, and what does it wrap?" and
    /// yields `None` for everything that isn't (skip / fall through), with
    /// no diagnostic. The strict siblings —
    /// [`crate::macro_expand::splice_value_into`] for the bound-list
    /// coercion, `non_symbol_unquote_target` /
    /// `splice_outside_list` for the per-failure-mode rejections — keep
    /// their loud-reject posture; this projection is the dispatch face the
    /// soft pre-rejection walk binds to.
    ///
    /// Structural identity binding it to the unquote-family variants:
    ///   * `as_unquote() == Some((UnquoteForm::Unquote, inner))` iff `self == Sexp::Unquote(inner)`
    ///   * `as_unquote() == Some((UnquoteForm::Splice, inner))`  iff `self == Sexp::UnquoteSplice(inner)`
    ///   * `as_unquote().is_some() == matches!(self, Sexp::Unquote(_) | Sexp::UnquoteSplice(_))`
    ///
    /// The returned `&Sexp` borrows the inner box's body verbatim — no
    /// clone, no allocation — same lifetime as `&self`. The closed-set
    /// guarantee on [`UnquoteForm`] (exactly `Unquote ⊎ Splice`) is
    /// threaded through this projection's return tuple, so consumers that
    /// pattern-match on `form: UnquoteForm` get rustc-enforced
    /// exhaustiveness — a future `Sexp` variant must extend `UnquoteForm`
    /// AND this match arm together (or stay outside the unquote family
    /// and project to `None`), eliminating the silent two-site
    /// extension-drift this lift was already designed to forbid.
    ///
    /// Theory anchor: THEORY.md §VI.1 — generation over composition; the
    /// `(Sexp::Unquote, UnquoteForm::Unquote)` and
    /// `(Sexp::UnquoteSplice, UnquoteForm::Splice)` pairings appear ≥3
    /// times across `compile_node` (2 arms) + `substitute` (top-level +
    /// list-inner) — past the PRIME-DIRECTIVE trigger once the structural
    /// shape is named. THEORY.md §V.1 — knowable platform; the
    /// unquote-family projection becomes a NAMED primitive on the
    /// substrate's `Sexp` algebra rather than per-site `Sexp::Unquote(_)
    /// | Sexp::UnquoteSplice(_)` inline matches paired with per-site
    /// `UnquoteForm::Unquote` / `UnquoteForm::Splice` literals.
    /// THEORY.md §II.1 invariant 1 — typed entry; the macro-template
    /// substitution surface's typed-marker projection IS the rust-level
    /// typed-entry gate's structural component, lifted from per-site
    /// duplication onto ONE rust method the substrate's diagnostic
    /// promotions hang off of. THEORY.md §II.1 invariant 2 — free middle;
    /// both expansion strategies (bytecode `compile_node` and substitute
    /// fallback `substitute`) route through the SAME projection, so a
    /// regression that drifts ONE strategy's (Sexp variant, UnquoteForm
    /// variant) pairing from the other cannot reach the substrate's
    /// runtime — the type system binds both strategies to the
    /// projection's single emission shape.
    ///
    /// Frontier inspiration: Racket's `syntax-parse` `~or* (~unquote stx)
    /// (~unquote-splice stx)` pattern — every macro-template pattern over
    /// `,id` / `,@id` binds to ONE typed decomposition that surfaces the
    /// marker identity alongside the inner expression; the substrate's
    /// `as_unquote` is the Rust-typed peer of that pattern, lifted onto
    /// the `Sexp` algebra with [`UnquoteForm`] standing in for Racket's
    /// pattern-class identity. MLIR's typed-IR projection
    /// `mlir::dyn_cast<UnquoteFamilyOp>(op)` — the typed downcast from a
    /// polymorphic IR node onto a closed-set op family is the MLIR idiom;
    /// `as_unquote` is the unstructured-projection peer on the substrate's
    /// `Sexp` algebra, with `Option<(UnquoteForm, &Sexp)>` standing in for
    /// MLIR's typed downcast result.
    pub fn as_unquote(&self) -> Option<(UnquoteForm, &Sexp)> {
        let (qf, inner) = self.as_quote_form()?;
        qf.as_unquote_form().map(|uf| (uf, inner))
    }

    /// Soft projection onto the closed-set [`UnquoteForm`] template-
    /// substitution carving marker — the 2-of-12 carving of the
    /// [`SexpShape`](crate::error::SexpShape) algebra covering the two
    /// homoiconic template-substitution wrappers ([`Self::Unquote`] and
    /// [`Self::UnquoteSplice`]), which is itself a 2-of-4 subset of the
    /// quote-family carving ([`QuoteForm`]). Returns
    /// `Some(UnquoteForm::Unquote)` iff this is `,x` (a [`Self::Unquote`]
    /// wrapper), `Some(UnquoteForm::Splice)` iff this is `,@x` (a
    /// [`Self::UnquoteSplice`] wrapper), `None` for every other outer
    /// shape ([`Self::Nil`], every [`Self::Atom`] variant, [`Self::List`],
    /// and the two non-substitution quote-family wrappers [`Self::Quote`]
    /// and [`Self::Quasiquote`]).
    ///
    /// Direct value-level peer of the shape-level projection
    /// [`SexpShape::as_unquote_form`](crate::error::SexpShape::as_unquote_form)
    /// — the pair `(Sexp::as_unquote_form, SexpShape::as_unquote_form)`
    /// binds the (Sexp value, UnquoteForm carving marker) pairing at ONE
    /// typed method on each algebra, closing the unquote-subset cell of
    /// the (Sexp value → carving marker) matrix. Marker-only sibling of
    /// [`Self::as_unquote`] (which returns
    /// `Option<(UnquoteForm, &Sexp)>` — marker + wrapped inner) and
    /// direct 2-of-4 subset peer of [`Self::as_quote_form`] (which
    /// covers the 4-of-12 quote-family carving with `Option<(QuoteForm,
    /// &Sexp)>`). Post-lift the substrate's value-level marker-only
    /// carving-marker matrix closes ONE more cell: the atomic axis via
    /// [`Self::as_atom_kind`] (6-of-12), the residual axis via
    /// [`Self::as_structural_kind`] (2-of-12), the quote-family axis via
    /// `Self::as_quote_form().map(|(qf, _)| qf)` (4-of-12, marker + inner
    /// available via the pre-existing method), and now the unquote-
    /// subset axis via `Self::as_unquote_form` (2-of-12, marker only) —
    /// symmetric with the shape-level marker-only projection family on
    /// [`SexpShape`](crate::error::SexpShape).
    ///
    /// Composition laws (three-way agreement — bindings): for every
    /// `s: &Sexp`,
    /// `s.as_unquote_form() == s.as_unquote().map(|(uf, _)| uf) ==
    ///  s.shape().as_unquote_form() ==
    ///  s.as_quote_form().and_then(|(qf, _)| qf.as_unquote_form())`.
    /// Pre-lift the unquote-subset carving marker at the value level
    /// was reachable only via one of these three-step compositions —
    /// either through the parent [`Self::as_unquote`] projection
    /// (discarding the inner), through the shape algebra
    /// (`shape().as_unquote_form()`), or through the parent quote-family
    /// projection composed with the 2-of-4 subset gate
    /// [`QuoteForm::as_unquote_form`]. Post-lift the projection lands at
    /// ONE typed method on the value algebra, and all three compositions
    /// are pinned as agreement laws (see
    /// `sexp_as_unquote_form_agrees_with_as_unquote_map_marker_for_every_variant`,
    /// `sexp_as_unquote_form_agrees_with_shape_as_unquote_form_for_every_variant`,
    /// and
    /// `sexp_as_unquote_form_agrees_with_as_quote_form_and_quote_form_as_unquote_form_for_every_variant`
    /// in this module). A regression that drifts any of the four
    /// projections from the others surfaces immediately.
    ///
    /// Symmetric with [`Self::as_atom_kind`] and [`Self::as_structural_kind`]
    /// on the marker-only shape (returns just the closed-set marker, no
    /// inner-payload borrow) — where [`Self::as_quote_form`] and
    /// [`Self::as_unquote`] surface both the marker AND the wrapped
    /// inner `&Sexp` (because the four quote-family arms and the two
    /// substitution arms structurally carry a boxed inner value),
    /// `as_unquote_form` returns a marker-only projection: consumers that
    /// need the wrapped inner reach the marker-plus-inner sibling
    /// [`Self::as_unquote`], while consumers that only need the closed-
    /// set carving-marker identity (typed-pattern matchers, diagnostic
    /// filters, coverage sweeps, LSP/REPL structural-navigation gates)
    /// reach this projection and never allocate the tuple.
    ///
    /// Composes cleanly with [`UnquoteForm::marker`] to project the value-
    /// level substitution carving membership onto its canonical marker
    /// string (`,` / `,@`):
    /// `s.as_unquote_form().map(UnquoteForm::marker)` — the marker-string
    /// witness for the substitution subset, sibling to
    /// `s.as_atom_kind().map(AtomKind::label)` on the atomic axis, both
    /// routing through the closed-set marker enum's canonical-vocabulary
    /// projection at ONE canonical site (`UnquoteForm::marker` —
    /// itself composed through `QuoteForm::prefix`).
    ///
    /// Structural identity (pinned as a truth-table by
    /// `sexp_as_unquote_form_projects_each_variant_to_canonical_unquote_form`
    /// and `sexp_as_unquote_form_rejects_non_unquote_subset_outer_shapes`):
    ///   * `as_unquote_form() == Some(UnquoteForm::Unquote)`  iff `matches!(self, Sexp::Unquote(_))`
    ///   * `as_unquote_form() == Some(UnquoteForm::Splice)`   iff `matches!(self, Sexp::UnquoteSplice(_))`
    ///   * `as_unquote_form() == None`                        iff `!matches!(self, Sexp::Unquote(_) | Sexp::UnquoteSplice(_))`
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the substitution-
    /// subset carving marker at the value level becomes a NAMED
    /// primitive on the substrate's `Sexp` algebra rather than a per-
    /// site composition through either [`Self::as_unquote`] (discarding
    /// its `&Sexp` inner) or [`Self::shape`] (walking through the full
    /// 12-variant `SexpShape` closed set to arrive at the 2-of-12
    /// carving marker) or the parent [`Self::as_quote_form`] combined
    /// with [`QuoteForm::as_unquote_form`] (the 2-of-4 subset gate).
    /// THEORY.md §II.1 invariant 2 — free middle; every consumer that
    /// wants the substitution-subset carving identity without needing
    /// the wrapped inner (a future `tatara-check` predicate
    /// `(check-value-projects-to-unquote-subset …)` that filters
    /// diagnostics keyed on the substitution-subset cohort; a future LSP
    /// structural-navigation filter that keys on the substitution-subset
    /// carving membership at the value level; a future
    /// `TypedRewriter<TemplateOp>` sweep that walks `Sexp` values whose
    /// substitution-arm identity is `Some(UnquoteForm::_)` regardless of
    /// inner payload identity; a future REPL pretty-printer that chooses
    /// rendering paths keyed on the value-level substitution carving
    /// marker without needing the inner payload) binds to ONE typed
    /// method on the value algebra. THEORY.md §VI.1 — generation over
    /// composition; the (Sexp variant, UnquoteForm variant) pairing
    /// binds at ONE inherent method on the algebra rather than at three
    /// parallel compositions (`as_unquote().map(…)`, `shape()
    /// .as_unquote_form()`, `as_quote_form().and_then(|(qf, _)|
    /// qf.as_unquote_form())`), so a regression that drifts ONE
    /// composition's pairing from the others cannot reach the substrate's
    /// runtime — the type system binds all three compositions to the
    /// projection's single emission shape.
    ///
    /// Frontier inspiration: MLIR's `mlir::dyn_cast<UnquoteFamilyOp>(op)
    /// .map(|op| op.marker())` — every typed rewriter that only needs
    /// the op-family identity (without the op's operands) binds to the
    /// typed-downcast projection composed with an operand-discarding
    /// marker extract; `Sexp::as_unquote_form` is the marker-only peer
    /// on the substrate's `Sexp` algebra, with `Option<UnquoteForm>`
    /// standing in for MLIR's `Optional<OperationName>` marker-only
    /// downcast result. Racket's `syntax-parse` `~or* (~unquote _)
    /// (~unquote-splice _)` — every syntax-class pattern that keys on
    /// the substitution-subset marker identity without binding the
    /// inner form; `Sexp::as_unquote_form` is the Rust-typed peer that
    /// surfaces the marker identity through a single primitive on the
    /// syntax algebra.
    #[must_use]
    pub fn as_unquote_form(&self) -> Option<UnquoteForm> {
        self.as_unquote().map(|(uf, _)| uf)
    }

    /// Decompose a quote-family form into its typed marker and inner
    /// expression — `Some((QuoteForm::Quote, inner))` iff this is `'x`
    /// (a [`Sexp::Quote`] wrapper), `Some((QuoteForm::Quasiquote, inner))`
    /// iff this is `` `x `` (a [`Sexp::Quasiquote`] wrapper),
    /// `Some((QuoteForm::Unquote, inner))` iff this is `,x` (a
    /// [`Sexp::Unquote`] wrapper), `Some((QuoteForm::UnquoteSplice, inner))`
    /// iff this is `,@x` (a [`Sexp::UnquoteSplice`] wrapper), `None` for
    /// every other shape (Nil, Atom, List).
    ///
    /// This is the *quote-family projection* — the typed-marker peer of
    /// [`Sexp::as_unquote`] generalized across all four homoiconic
    /// prefix-wrappers. Where [`Sexp::as_unquote`] keys the macro-template
    /// SUBSTITUTION surface on the closed pair `{Unquote, Splice}` (the
    /// two prefixes whose template-time semantic is substitution),
    /// `as_quote_form` keys the WIRE-SHAPE surfaces (Display rendering,
    /// Hash discrimination, canonical-form interop) on the closed superset
    /// `{Quote, Quasiquote, Unquote, UnquoteSplice}` — all four prefixes
    /// the reader can tokenize and the writer must round-trip. The
    /// `Sexp::as_unquote` projection now derives structurally from
    /// `as_quote_form`'s output via [`QuoteForm::as_unquote_form`] — the
    /// 2-of-4 subset gate — so the two projections share a SINGLE
    /// implementation site on the `Sexp` algebra and the
    /// (Sexp variant, QuoteForm variant) pairing binds at ONE rust
    /// function regardless of whether the consumer wants the substitution
    /// subset or the wire-shape superset.
    ///
    /// Three consumers in this file route through this primitive:
    ///   * `Hash for Sexp` — the four `Quote`/`Quasiquote`/`Unquote`/
    ///     `UnquoteSplice` arms (pre-lift each carrying its own
    ///     `<discr>.hash(h); inner.hash(h)` body) collapse to ONE arm
    ///     that routes through `as_quote_form` and reads the
    ///     discriminator via [`QuoteForm::hash_discriminator`].
    ///   * `Display for Sexp` — the four `write!(f, "<prefix>{inner}")`
    ///     arms (pre-lift each carrying its own literal prefix string)
    ///     collapse to ONE arm that routes through `as_quote_form` and
    ///     reads the prefix via [`QuoteForm::prefix`].
    ///   * [`Sexp::as_unquote`] — derives `Option<(UnquoteForm, &Sexp)>`
    ///     by composing `as_quote_form` with [`QuoteForm::as_unquote_form`]
    ///     (the 2-of-4 subset projection), so the macro-template
    ///     substitution surface inherits the (Sexp variant, marker)
    ///     pairing through this projection's typed dispatch rather than
    ///     re-deriving its own arm-based match.
    ///
    /// The closed-set guarantee on [`QuoteForm`] (exactly
    /// `Quote ⊎ Quasiquote ⊎ Unquote ⊎ UnquoteSplice`) is threaded through
    /// this projection's return tuple, so consumers that pattern-match on
    /// `form: QuoteForm` get rustc-enforced exhaustiveness — a future
    /// `Sexp` wrapper variant must extend `QuoteForm` AND this match arm
    /// together (or stay outside the quote family and project to `None`),
    /// eliminating the silent multi-site extension-drift this lift was
    /// designed to forbid.
    ///
    /// Soft face, like the rest of the `as_*` family on `Sexp`: it
    /// answers "is this form a quote-family marker, and what does it
    /// wrap?" and yields `None` for everything that isn't (skip / fall
    /// through), with no diagnostic.
    ///
    /// Structural identity binding it to the quote-family variants and
    /// its `as_unquote` subset sibling:
    ///   * `as_quote_form() == Some((QuoteForm::Quote, inner))`         iff `self == Sexp::Quote(inner)`
    ///   * `as_quote_form() == Some((QuoteForm::Quasiquote, inner))`    iff `self == Sexp::Quasiquote(inner)`
    ///   * `as_quote_form() == Some((QuoteForm::Unquote, inner))`       iff `self == Sexp::Unquote(inner)`
    ///   * `as_quote_form() == Some((QuoteForm::UnquoteSplice, inner))` iff `self == Sexp::UnquoteSplice(inner)`
    ///   * `as_quote_form().is_some() == matches!(self, Sexp::Quote(_) | Sexp::Quasiquote(_) | Sexp::Unquote(_) | Sexp::UnquoteSplice(_))`
    ///   * `as_unquote() == as_quote_form().and_then(|(qf, inner)| qf.as_unquote_form().map(|uf| (uf, inner)))`
    ///
    /// The returned `&Sexp` borrows the inner box's body verbatim — no
    /// clone, no allocation — same lifetime as `&self` and same posture
    /// as [`Sexp::as_unquote`]'s tail.
    ///
    /// Theory anchor: THEORY.md §VI.1 — generation over composition; the
    /// quote-family (Sexp variant, prefix string, hash discriminator)
    /// triple appeared inline at three sites (`Hash for Sexp`,
    /// `Display for Sexp`, `as_unquote`) — well past the ≥2 PRIME-DIRECTIVE
    /// trigger once the structural shape is named. THEORY.md §V.1 —
    /// knowable platform; the quote-family typed-marker projection becomes
    /// a NAMED primitive on the substrate's `Sexp` algebra rather than
    /// per-site inline matches paired with per-site discriminator literals
    /// and prefix literals. THEORY.md §II.1 invariant 1 — typed entry; the
    /// reader's prefix-to-variant dispatch ([`crate::reader::read_quoted`])
    /// AND the Display impl's variant-to-prefix dispatch are dual
    /// typed-entry / typed-exit gates over the same closed set; the
    /// `QuoteForm` algebra threads BOTH gates through ONE typed enum so a
    /// regression that drifts one side's prefix from the other (e.g. the
    /// reader gains a fifth prefix but the Display impl doesn't) is no
    /// longer a silent two-site divergence — rustc binds both sides to
    /// the same closed-set enum. THEORY.md §II.1 invariant 2 — free
    /// middle; the three consumers (Hash, Display, `as_unquote`) route
    /// through the SAME projection, so a regression that drifts ONE
    /// consumer's (Sexp variant, marker) pairing from the others cannot
    /// reach the substrate's runtime.
    ///
    /// Frontier inspiration: Racket's `syntax-parse` `~or* (~quote stx)
    /// (~quasiquote stx) (~unquote stx) (~unquote-splice stx)` pattern —
    /// every macro-template pattern over `'`/`` ` ``/`,`/`,@` binds to
    /// ONE typed decomposition that surfaces the marker identity
    /// alongside the inner expression; the substrate's `as_quote_form` is
    /// the Rust-typed peer of that pattern, lifted onto the `Sexp`
    /// algebra with `QuoteForm` standing in for Racket's pattern-class
    /// identity at the homoiconic prefix surface. MLIR's typed-IR
    /// projection `mlir::dyn_cast<QuoteFamilyOp>(op)` — the typed downcast
    /// from a polymorphic IR node onto a closed-set op family is the MLIR
    /// idiom; `as_quote_form` is the unstructured-projection peer on the
    /// substrate's `Sexp` algebra, with `Option<(QuoteForm, &Sexp)>`
    /// standing in for MLIR's typed downcast result.
    pub fn as_quote_form(&self) -> Option<(QuoteForm, &Sexp)> {
        match self {
            Self::Quote(inner) => Some((QuoteForm::Quote, inner)),
            Self::Quasiquote(inner) => Some((QuoteForm::Quasiquote, inner)),
            Self::Unquote(inner) => Some((QuoteForm::Unquote, inner)),
            Self::UnquoteSplice(inner) => Some((QuoteForm::UnquoteSplice, inner)),
            _ => None,
        }
    }

    /// Soft projection onto the closed-set [`QuoteForm`] quote-family
    /// carving marker — the 4-of-12 carving of the [`SexpShape`] algebra
    /// covering the four homoiconic prefix-wrappers ([`Self::Quote`],
    /// [`Self::Quasiquote`], [`Self::Unquote`], [`Self::UnquoteSplice`]).
    /// Returns `Some(QuoteForm::Quote)` iff this is `'x` (a
    /// [`Self::Quote`] wrapper), `Some(QuoteForm::Quasiquote)` iff this
    /// is `` `x `` (a [`Self::Quasiquote`] wrapper),
    /// `Some(QuoteForm::Unquote)` iff this is `,x` (a [`Self::Unquote`]
    /// wrapper), `Some(QuoteForm::UnquoteSplice)` iff this is `,@x` (a
    /// [`Self::UnquoteSplice`] wrapper), `None` for every other outer
    /// shape ([`Self::Nil`], every [`Self::Atom`] variant, [`Self::List`]).
    ///
    /// Direct value-level peer of the shape-level projection
    /// [`SexpShape::as_quote_form`](crate::error::SexpShape::as_quote_form)
    /// — the pair `(Sexp::as_quote_form_marker, SexpShape::as_quote_form)`
    /// binds the (Sexp value, QuoteForm carving marker) pairing at ONE
    /// typed method on each algebra, closing the quote-family cell of
    /// the (Sexp value → carving marker) matrix at the marker-only
    /// value-level projection surface. Marker-only sibling of
    /// [`Self::as_quote_form`] (which returns `Option<(QuoteForm, &Sexp)>`
    /// — marker + wrapped inner). Post-lift the substrate's value-level
    /// marker-only carving-marker matrix closes its FINAL cell: the
    /// atomic axis via [`Self::as_atom_kind`] (6-of-12), the residual
    /// axis via [`Self::as_structural_kind`] (2-of-12), the unquote-
    /// subset axis via [`Self::as_unquote_form`] (2-of-12), and NOW the
    /// quote-family axis via `Self::as_quote_form_marker` (4-of-12) —
    /// symmetric with the shape-level marker-only projection family on
    /// [`SexpShape`](crate::error::SexpShape).
    ///
    /// Composition laws (two-way agreement — bindings): for every
    /// `s: &Sexp`,
    /// `s.as_quote_form_marker() == s.as_quote_form().map(|(qf, _)| qf)
    ///  == s.shape().as_quote_form()`. Pre-lift the quote-family carving
    /// marker at the value level was reachable only via one of these
    /// two-step compositions — either through the parent
    /// [`Self::as_quote_form`] projection (discarding the wrapped inner
    /// via `.map(|(qf, _)| qf)`) or through the shape algebra
    /// (`s.shape().as_quote_form()`, walking the full 12-variant
    /// [`SexpShape`](crate::error::SexpShape) closed set to arrive at
    /// the 4-of-12 carving marker). Post-lift the projection lands at
    /// ONE typed method on the value algebra, and both compositions
    /// are pinned as agreement laws (see
    /// `sexp_as_quote_form_marker_agrees_with_as_quote_form_map_marker_for_every_variant`
    /// and
    /// `sexp_as_quote_form_marker_agrees_with_shape_as_quote_form_for_every_variant`
    /// in this module).
    ///
    /// Superset-gate contract with [`Self::as_unquote_form`]: for every
    /// `s: &Sexp`, `s.as_unquote_form().is_some()` implies
    /// `s.as_quote_form_marker().is_some()` (the 2-of-12 substitution
    /// subset is a proper subset of the 4-of-12 quote family). The two
    /// non-substitution quote-family wrappers ([`Self::Quote`] and
    /// [`Self::Quasiquote`]) satisfy `as_quote_form_marker().is_some()`
    /// AND `as_unquote_form().is_none()` — the value-level image of the
    /// 2-of-4 subset gate [`QuoteForm::as_unquote_form`]. Pinned by
    /// `sexp_as_quote_form_marker_extends_as_unquote_form_to_full_quote_family`.
    ///
    /// Structural identity binding it to the quote-family variants:
    ///   * `as_quote_form_marker() == Some(QuoteForm::Quote)`         iff `matches!(self, Sexp::Quote(_))`
    ///   * `as_quote_form_marker() == Some(QuoteForm::Quasiquote)`    iff `matches!(self, Sexp::Quasiquote(_))`
    ///   * `as_quote_form_marker() == Some(QuoteForm::Unquote)`       iff `matches!(self, Sexp::Unquote(_))`
    ///   * `as_quote_form_marker() == Some(QuoteForm::UnquoteSplice)` iff `matches!(self, Sexp::UnquoteSplice(_))`
    ///   * `as_quote_form_marker() == None`                           iff `!matches!(self, Sexp::Quote(_) | Sexp::Quasiquote(_) | Sexp::Unquote(_) | Sexp::UnquoteSplice(_))`
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the quote-
    /// family carving marker at the value level becomes a NAMED
    /// primitive on the substrate's `Sexp` algebra rather than a per-
    /// site two-step composition through either [`Self::as_quote_form`]
    /// (discarding its `&Sexp` inner) or [`Self::shape`] (walking through
    /// the full 12-variant [`SexpShape`](crate::error::SexpShape) closed
    /// set to arrive at the 4-of-12 carving marker). THEORY.md §II.1
    /// invariant 2 — free middle; every consumer that wants the quote-
    /// family carving identity without needing the wrapped inner (a
    /// future `tatara-check` predicate `(check-value-projects-to-quote-
    /// family …)` that filters diagnostics keyed on the quote-family
    /// cohort; a future LSP structural-navigation filter that keys on
    /// the quote-family carving membership at the value level; a
    /// future `TypedRewriter<QuoteFamilyOp>` sweep that walks `Sexp`
    /// values whose quote-family arm identity is `Some(QuoteForm::_)`
    /// regardless of inner payload identity; a future REPL pretty-
    /// printer that chooses rendering paths keyed on the value-level
    /// quote-family carving marker without needing the inner payload)
    /// routes through ONE typed method rather than reaching into one of
    /// the two composition sites, and both compositions are pinned as
    /// agreement laws so a regression that drifts ONE composition's
    /// pairing from the other cannot reach the substrate's runtime.
    /// THEORY.md §VI.1 — generation over composition; the (Sexp variant,
    /// QuoteForm variant) pairing binds at ONE inherent method on the
    /// algebra rather than at two parallel compositions, so a future
    /// extension (e.g. a fifth `Sexp` quote-family wrapper) lands at
    /// ONE match arm in the parent `as_quote_form` projection and
    /// inherits through this method's structural composition.
    ///
    /// Frontier inspiration: MLIR's `mlir::dyn_cast<QuoteFamilyOp>(op)
    /// .map(|op| op.marker())` — every typed rewriter that only needs
    /// the op-family identity (without the op's operands) binds to the
    /// typed-downcast projection composed with an operand-discarding
    /// marker extract; `Sexp::as_quote_form_marker` is the marker-only
    /// peer on the substrate's `Sexp` algebra, with
    /// `Option<QuoteForm>` standing in for MLIR's
    /// `Optional<OperationName>` marker-only downcast result. Racket's
    /// `syntax-parse` `~or* (~quote _) (~quasiquote _) (~unquote _)
    /// (~unquote-splice _)` — every syntax-class pattern that keys on
    /// the quote-family marker identity without binding the inner form;
    /// `Sexp::as_quote_form_marker` is the Rust-typed peer that
    /// surfaces the marker identity through a single primitive on the
    /// syntax algebra.
    #[must_use]
    pub fn as_quote_form_marker(&self) -> Option<QuoteForm> {
        self.as_quote_form().map(|(qf, _)| qf)
    }

    /// Quote-family projection, asserted-total face of [`Sexp::as_quote_form`].
    /// Returns `(QuoteForm, &Sexp)` verbatim — same borrowed-inner posture,
    /// same closed-set marker — but panics with [`QUOTE_FAMILY_PROJECTION_INVARIANT`]
    /// instead of yielding `None` for non-quote-family variants. Use AFTER
    /// an outer pattern match has narrowed the discriminant union to the
    /// quote family (`Sexp::Quote(_) | Sexp::Quasiquote(_) | Sexp::Unquote(_) |
    /// Sexp::UnquoteSplice(_)`); the panic message states the invariant the
    /// caller's outer pattern already proves.
    ///
    /// Pre-lift the five production-site quote-family-arm consumers —
    /// `Hash for Sexp::hash_discriminator`, `Display for Sexp::prefix`,
    /// `domain::sexp_shape`, `domain::sexp_to_json`, `interop::iac_forge_tag` —
    /// each carried a verbatim copy of the 4-arm wildcard pattern AND a
    /// verbatim copy of the inline
    /// `.as_quote_form().expect("matched quote-family variant must project
    /// to Some via as_quote_form")` re-projection. The `(pattern, expect
    /// message)` pair appeared bit-for-bit at FIVE sites. Post-lift the
    /// expect message lives at ONE named const and the projection-with-
    /// assertion lives at ONE primitive on the `Sexp` algebra; the five
    /// callsites collapse to ONE typed query each. A future quote-family
    /// extension that drifts ONE site's panic text from the others becomes
    /// structurally impossible (one const, one method); a future site that
    /// needs the same "outer-narrowed, total projection" shape lands on
    /// this primitive directly without re-deriving the expect literal.
    ///
    /// `#[track_caller]` ensures a panic surfaces the consumer's source
    /// position, not this projection's — so the diagnostic stays
    /// load-bearing under the lift.
    ///
    /// Sibling posture to the `expect_*` family of typed-projection
    /// asserted-total faces across the substrate's closed-set algebras
    /// (`Option::expect`, `Result::expect`) — the assertion is the same
    /// shape, the message is named on the algebra it asserts about.
    ///
    /// # Panics
    ///
    /// Panics with [`QUOTE_FAMILY_PROJECTION_INVARIANT`] if `self` is not
    /// a quote-family variant. The outer pattern match at every caller
    /// site is the proof of the invariant; the panic is the static
    /// fall-through for a regression that drifts that proof.
    ///
    /// Theory anchor: THEORY.md §VI.1 — generation over composition; the
    /// (4-arm wildcard pattern, expect re-projection) pair appeared bit-
    /// for-bit at five production sites — well past the ≥2 PRIME-DIRECTIVE
    /// trigger. THEORY.md §V.1 — knowable platform; the panic message and
    /// the projection-with-assertion are now ONE named primitive on the
    /// substrate's `Sexp` algebra, structurally binding the invariant
    /// across every consumer that asserts an outer narrowing.
    #[must_use]
    #[track_caller]
    pub fn expect_quote_form(&self) -> (QuoteForm, &Sexp) {
        self.as_quote_form()
            .expect(QUOTE_FAMILY_PROJECTION_INVARIANT)
    }

    /// Stable, per-outer-variant byte discriminator for the substrate's
    /// [`Hash for Sexp`] cache-key projection — `0` for [`Self::Nil`],
    /// `1` for [`Self::Atom`], `2` for [`Self::List`], `3` for
    /// [`Self::Quote`], `4` for [`Self::Quasiquote`], `5` for
    /// [`Self::Unquote`], `6` for [`Self::UnquoteSplice`]. Composes
    /// through [`Self::shape`] into
    /// [`crate::error::SexpShape::hash_discriminator`], which in turn
    /// composes through the three closed-set sub-carvings' discriminator
    /// methods: [`crate::error::StructuralKind::hash_discriminator`] for
    /// the two structural-residual arms `{0, 2}`,
    /// [`crate::error::QuoteForm::hash_discriminator`] for the four
    /// quote-family arms `{3..=6}`, and the outer atomic marker byte
    /// `1u8` for the six atomic-payload arms (whose inner
    /// [`crate::ast::AtomKind::hash_discriminator`] `{0..=5}` partition
    /// nests inside [`Hash for Atom`] rather than surfacing here). The
    /// outer-`Sexp` cache-key algebra now closes at FIVE typed layers
    /// (outer `Sexp` → [`crate::error::SexpShape`] → three sub-carvings)
    /// with rustc-enforced consistency across each.
    ///
    /// 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)` — changing a discriminator silently
    /// invalidates every cached expansion across the substrate.
    ///
    /// The seven outer-variant arms partition `{0, 1, 2, 3, 4, 5, 6}`
    /// injectively — closed-set-typed intra-Sexp injectivity that
    /// composes through the intermediate
    /// [`crate::error::SexpShape::hash_discriminator`] shape-level
    /// projection (12 arms → 7 bytes; the six atomic-shape arms
    /// collapse to the outer Atom marker byte `1u8`; the two
    /// structural-residual arms surface `{0, 2}`; the four quote-family
    /// arms surface `{3..=6}`). Together the four sub-algebras (this
    /// outer method + shape + three sub-carvings) jointly cover the
    /// entire outer-Sexp discriminator space through ONE typed method
    /// per algebra layer. A future eighth `Sexp` variant (e.g. a
    /// hypothetical `Vector` for `#(...)` reader syntax, `Map` for
    /// `{...}`, or `Char` for `#\x`) picks a fresh cache-key byte
    /// outside `{0..=6}` (e.g. `7u8`), extends the closed-set
    /// [`crate::error::SexpShape`] enum + its
    /// `hash_discriminator` (plus either [`crate::error::StructuralKind`]
    /// or a fresh sub-algebra) in lockstep — rustc binds the
    /// consistency through exhaustiveness over each closed enum.
    ///
    /// Pre-lift this outer method dispatched over the seven `Sexp`
    /// variants directly and routed the three structural + four
    /// quote-family arms into the two sub-carvings' discriminator
    /// methods with the Atom arm inline at `1u8` — the intermediate
    /// [`crate::error::SexpShape`] shape-level projection did not
    /// exist, so a consumer with a typed [`crate::error::SexpShape`]
    /// identity in hand had to re-embed into a `Sexp` value to reach
    /// the outer cache-key byte. Post-lift the outer method routes
    /// through [`Self::shape`] into
    /// [`crate::error::SexpShape::hash_discriminator`]; the shape-level
    /// projection is the missing algebra layer between the outer `Sexp`
    /// and the three sub-carvings, and consumers with a typed shape
    /// identity now reach the outer cache-key byte at ONE typed method
    /// per algebra layer without a re-embed.
    ///
    /// `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::as_atom`], [`Self::as_list`],
    /// [`Self::as_quote_form`]) don't already serve. Same posture as
    /// [`crate::error::SexpShape::hash_discriminator`],
    /// [`crate::ast::AtomKind::hash_discriminator`],
    /// [`crate::error::QuoteForm::hash_discriminator`], and
    /// [`crate::error::StructuralKind::hash_discriminator`].
    #[must_use]
    pub(crate) fn hash_discriminator(&self) -> u8 {
        self.shape().hash_discriminator()
    }

    /// Cross-crate canonical iac-forge tag for the outer [`Sexp`] value —
    /// the OUTER-VALUE peer of the shape-level [`crate::error::SexpShape
    /// ::iac_forge_tag`] one algebra layer down. `Some(&'static str)` for
    /// the four homoiconic prefix-wrapper arms — `Self::Quote →
    /// Some("quote")`, `Self::Quasiquote → Some("quasiquote")`,
    /// `Self::Unquote → Some("unquote")`, `Self::UnquoteSplice →
    /// Some("unquote-splicing")` — and `None` for the outer atomic-payload
    /// arm ([`Self::Atom`]) AND the two structural-residual arms
    /// ([`Self::Nil`], [`Self::List`]). The 4-of-7 partial projection on
    /// the outer-`Sexp` algebra surfaces
    /// [`crate::ast::QuoteForm::iac_forge_tag`]'s cross-crate canonical-
    /// form tag surface at the outermost value-carrier algebra level,
    /// composed through the pre-existing [`Self::shape`] projection and
    /// [`crate::error::SexpShape::iac_forge_tag`]'s shape-level partial
    /// projection.
    ///
    /// Composition law: `sexp.iac_forge_tag() ==
    /// sexp.shape().iac_forge_tag()` for every `sexp: &Sexp` — the outer-
    /// `Sexp` cross-crate canonical-form tag surface routes through
    /// [`Self::shape`] into the shape-level partial projection, which in
    /// turn composes through [`crate::error::SexpShape::as_quote_form`]
    /// with [`crate::ast::QuoteForm::iac_forge_tag`]'s canonical 4-of-4
    /// closed-set tag projection. Post-lift the outer-`Sexp` cross-crate
    /// canonical-form tag surface closes at FOUR typed layers: outer
    /// [`Self::iac_forge_tag`] (7-arm outer dispatch on the outer
    /// [`Sexp`] algebra, this method) → shape-level
    /// [`crate::error::SexpShape::iac_forge_tag`] (12-arm shape-level
    /// dispatch on the [`crate::error::SexpShape`] algebra) →
    /// quote-family carving [`crate::error::SexpShape::as_quote_form`]
    /// (4-of-12 quote-family sub-carving) → sub-carving tag
    /// [`crate::ast::QuoteForm::iac_forge_tag`] (4-arm quote-family
    /// sub-carving's canonical-form tag projection).
    ///
    /// Pre-lift a consumer with a typed [`Sexp`] value in hand (a
    /// generation-side canonical-form emitter, a downstream iac-forge
    /// attestation site, an LSP / REPL / audit-trail metric keyed on the
    /// observed outer value) wanting the cross-crate iac-forge canonical
    /// tag string had to spell the two-step composition
    /// `sexp.shape().iac_forge_tag()` at every callsite, or route through
    /// [`Self::as_quote_form_marker`] composed with
    /// [`crate::ast::QuoteForm::iac_forge_tag`] via `map` as the
    /// `crate::interop` (removed) `From<&Sexp> for iac_forge::SExpr` impl does
    /// for its four quote-family arms via [`Self::expect_quote_form`]
    /// composed with [`crate::ast::QuoteForm::iac_forge_tag`]. Post-lift
    /// the outer-`Sexp` canonical-form tag projection binds at ONE
    /// typed-algebra method on the outer value-carrier — the SEVENTH
    /// consumer of the outer-`Sexp` projection surface (sibling of
    /// [`Self::shape`], [`Self::type_name`],
    /// [`Self::hash_discriminator`], [`Self::as_atom`], [`Self::as_list`],
    /// [`Self::as_quote_form`], [`Self::as_quote_form_marker`],
    /// [`Self::as_unquote`], [`Self::as_unquote_form`]), matching the
    /// same shape-composition posture [`Self::hash_discriminator`] takes
    /// through the outer → shape one-step delegation.
    ///
    /// The `Option<&'static str>` return shape mirrors
    /// [`crate::error::SexpShape::iac_forge_tag`]'s partial-projection
    /// shape one algebra level down — the outer-`Sexp` seven-arm closed
    /// set's projection PARTIALIZES on the three non-quote-family shapes
    /// (`Nil`, `Atom`, `List`) exactly as the shape-level twelve-arm
    /// closed set's projection PARTIALIZES on the eight non-quote-family
    /// shapes. The kernel's outer cardinality (three: `Nil` / `Atom` /
    /// `List`) matches the shape-level kernel's cardinality (eight)
    /// through [`Self::shape`]'s six-atomic-arms → outer `Atom` collapse
    /// — the outer three-arm kernel `{Nil, Atom, List}` corresponds to
    /// the shape-level eight-arm kernel `{Nil, Symbol, Keyword, String,
    /// Int, Float, Bool, List}` under the outer → shape projection.
    ///
    /// 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,
    /// [`crate::error::SexpShape::iac_forge_tag`] on the shape-level
    /// projection, and [`crate::error::UnquoteForm::iac_forge_tag`] on
    /// the template-substitution subset project their respective closed
    /// sets. A future eighth [`Sexp`] variant (e.g. a hypothetical
    /// `Vector` for `#(...)` reader syntax, `Map` for `{...}`, `Char` for
    /// `#\x`) extends [`crate::error::SexpShape`] (adding a `None`-arm
    /// non-quote-family shape) — this method picks up the new arm's
    /// `None` mechanically through the shape composition, with rustc's
    /// exhaustiveness binding the extension end-to-end at
    /// [`crate::error::SexpShape::as_quote_form`]'s closed match.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the (outer
    /// `Sexp` variant, canonical iac-forge tag) pairing becomes a TYPE
    /// projection on the outermost value-carrier algebra rather than an
    /// inline `.shape().iac_forge_tag()` 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
    /// `Sexp` ↔ `SexpShape` ↔ `QuoteForm` ↔ tag string chain is rustc-
    /// enforced end-to-end. THEORY.md §II.1 invariant 2 — free middle;
    /// the (outer value, canonical iac-forge tag) pairing now binds at
    /// ONE site on the outer-`Sexp` algebra, composing through the pre-
    /// existing shape-level partial projection rather than duplicating
    /// the four-arm match here. THEORY.md §VI.1 — generation over
    /// composition; the outer-`Sexp` cross-crate canonical-form tag
    /// surface closes at FOUR typed layers (outer → shape → carving →
    /// sub-carving-tag), each keyed on the SAME canonical-form tag
    /// projection carried at the closed-set sub-carving level.
    ///
    /// Frontier inspiration: MLIR's `mlir::Operation::getName()` typed
    /// projection composed with `mlir::OperationName::getStringRef()` —
    /// narrowing an operation-carrier value through its typed op-name
    /// identity yields the canonical cross-boundary string identity in
    /// ONE typed composition. [`Self::iac_forge_tag`] is the Rust-typed
    /// peer where the "project to shape" step ([`Self::shape`]) composes
    /// with the "read the shape's canonical tag" step
    /// ([`crate::error::SexpShape::iac_forge_tag`]) into ONE outer-value
    /// projection.
    #[must_use]
    pub fn iac_forge_tag(&self) -> Option<&'static str> {
        self.shape().iac_forge_tag()
    }

    /// Canonical reader-punctuation prefix for the outer [`Sexp`] value —
    /// the OUTER-VALUE peer of the shape-level
    /// [`crate::error::SexpShape::prefix`] one algebra layer down.
    /// `Some(&'static str)` for the four homoiconic prefix-wrapper arms —
    /// `Self::Quote → Some("'")`, `Self::Quasiquote → Some("`")`,
    /// `Self::Unquote → Some(",")`, `Self::UnquoteSplice → Some(",@")` —
    /// and `None` for the outer atomic-payload arm ([`Self::Atom`]) AND
    /// the two structural-residual arms ([`Self::Nil`], [`Self::List`]).
    /// The 4-of-7 partial projection on the outer-`Sexp` algebra surfaces
    /// [`crate::ast::QuoteForm::prefix`]'s reader-punctuation surface at
    /// the outermost value-carrier algebra level, composed through the
    /// pre-existing [`Self::shape`] projection and
    /// [`crate::error::SexpShape::prefix`]'s shape-level partial
    /// projection.
    ///
    /// Composition law: `sexp.prefix() == sexp.shape().prefix()` for
    /// every `sexp: &Sexp` — the outer-`Sexp` reader-punctuation surface
    /// routes through [`Self::shape`] into the shape-level partial
    /// projection, which in turn composes through
    /// [`crate::error::SexpShape::as_quote_form`] with
    /// [`crate::ast::QuoteForm::prefix`]'s canonical 4-of-4 closed-set
    /// prefix projection. Post-lift the outer-`Sexp` reader-punctuation
    /// surface closes at FOUR typed layers: outer [`Self::prefix`]
    /// (7-arm outer dispatch on the outer [`Sexp`] algebra, this method)
    /// → shape-level [`crate::error::SexpShape::prefix`] (12-arm shape-
    /// level dispatch on the [`crate::error::SexpShape`] algebra) →
    /// quote-family carving [`crate::error::SexpShape::as_quote_form`]
    /// (4-of-12 quote-family sub-carving) → sub-carving prefix
    /// [`crate::ast::QuoteForm::prefix`] (4-arm quote-family sub-
    /// carving's canonical reader-punctuation projection).
    ///
    /// Pre-lift a consumer with a typed [`Sexp`] value in hand (an
    /// [`fmt::Display for Sexp`] impl that renders the four quote-family
    /// arms as `<prefix><inner>`, an LSP hover / REPL completion that
    /// echoes the source-punctuation prefix of a wrapper value, an
    /// audit-trail metric keyed on the observed outer value) wanting
    /// the canonical reader-punctuation prefix string had to spell the
    /// two-step composition `sexp.shape().prefix()` at every callsite,
    /// or route through [`Self::as_quote_form_marker`] composed with
    /// [`crate::ast::QuoteForm::prefix`] via `map` as the
    /// [`fmt::Display for Sexp`] impl does for its four quote-family
    /// arms via [`Self::expect_quote_form`] composed with
    /// [`crate::ast::QuoteForm::prefix`]. Post-lift the outer-`Sexp`
    /// reader-punctuation projection binds at ONE typed-algebra method
    /// on the outer value-carrier — the natural next rung on the
    /// trajectory mirroring the [`Self::iac_forge_tag`] →
    /// [`crate::error::SexpShape::iac_forge_tag`] ladder one vocabulary
    /// axis over, matching the same shape-composition posture
    /// [`Self::hash_discriminator`] and [`Self::iac_forge_tag`] take
    /// through the outer → shape one-step delegation.
    ///
    /// The `Option<&'static str>` return shape mirrors
    /// [`crate::error::SexpShape::prefix`]'s partial-projection shape one
    /// algebra level down — the outer-`Sexp` seven-arm closed set's
    /// projection PARTIALIZES on the three non-quote-family shapes
    /// (`Nil`, `Atom`, `List`) exactly as the shape-level twelve-arm
    /// closed set's projection PARTIALIZES on the eight non-quote-family
    /// shapes. The kernel's outer cardinality (three: `Nil` / `Atom` /
    /// `List`) matches the shape-level kernel's cardinality (eight)
    /// through [`Self::shape`]'s six-atomic-arms → outer `Atom` collapse
    /// — the outer three-arm kernel `{Nil, Atom, List}` corresponds to
    /// the shape-level eight-arm kernel `{Nil, Symbol, Keyword, String,
    /// Int, Float, Bool, List}` under the outer → shape projection.
    ///
    /// The reader-punctuation vocabulary this method projects (`"'"` /
    /// `` "`" `` / `","` / `",@"`) is INTENTIONALLY DISJOINT from the
    /// two sibling `&'static str` outer-value 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::type_name`] — operator-facing diagnostic label
    ///   (`"nil"` / `"atom"` / `"list"` / `"quote"` / `"quasiquote"` /
    ///   `"unquote"` / `"unquote-splice"`) on the outer 7-arm surface,
    ///   [`crate::error::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 outer-value
    /// closed-set projections key the SAME seven-arm outer 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 / [`fmt::Display for Sexp`] consumer projects through this
    /// method into the canonical prefix character without an allocation,
    /// parallel to how [`crate::ast::QuoteForm::prefix`] on the sub-
    /// carving, [`crate::error::SexpShape::prefix`] on the shape-level
    /// projection, [`Self::iac_forge_tag`] on the cross-crate canonical-
    /// form axis, and [`crate::error::UnquoteForm::marker`] on the
    /// template-marker axis project their respective closed sets. A
    /// future eighth [`Sexp`] variant (e.g. a hypothetical `Vector` for
    /// `#(...)` reader syntax, `Map` for `{...}`, `Char` for `#\x`)
    /// extends [`crate::error::SexpShape`] (adding a `None`-arm non-
    /// quote-family shape) — this method picks up the new arm's `None`
    /// mechanically through the shape composition, with rustc's
    /// exhaustiveness binding the extension end-to-end at
    /// [`crate::error::SexpShape::as_quote_form`]'s closed match.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the (outer
    /// `Sexp` variant, reader-punctuation prefix) pairing becomes a
    /// TYPE projection on the outermost value-carrier algebra rather
    /// than an inline `.shape().prefix()` 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 `Sexp` ↔ `SexpShape` ↔ `QuoteForm` ↔ prefix character
    /// chain is rustc-enforced end-to-end. THEORY.md §II.1 invariant 2
    /// — free middle; the (outer value, reader-punctuation prefix)
    /// pairing now binds at ONE site on the outer-`Sexp` algebra,
    /// composing through the pre-existing shape-level partial
    /// projection rather than duplicating the four-arm match here.
    /// THEORY.md §VI.1 — generation over composition; the outer-`Sexp`
    /// reader-punctuation surface closes at FOUR typed layers (outer
    /// → shape → carving → sub-carving-prefix), each keyed on the SAME
    /// reader-punctuation projection carried at the closed-set sub-
    /// carving level.
    ///
    /// Frontier inspiration: MLIR's `mlir::Operation::getName()` typed
    /// projection composed with `mlir::OperationName::getStringRef()`
    /// — narrowing an operation-carrier value through its typed op-name
    /// identity yields the canonical cross-boundary string identity in
    /// ONE typed composition. [`Self::prefix`] is the Rust-typed peer
    /// where the "project to shape" step ([`Self::shape`]) composes
    /// with the "read the shape's canonical reader-punctuation" step
    /// ([`crate::error::SexpShape::prefix`]) into ONE outer-value
    /// projection — sibling of [`Self::iac_forge_tag`] one vocabulary
    /// axis over on the cross-crate canonical-form surface.
    #[must_use]
    pub fn prefix(&self) -> Option<&'static str> {
        self.shape().prefix()
    }

    /// Total structural node count of the outer [`Sexp`] value — one
    /// node per outer-algebra arm plus the recursive node count of
    /// each child. [`Self::Nil`] and [`Self::Atom`] contribute one
    /// node apiece (the outer arm itself); [`Self::List`] contributes
    /// one node for the outer arm plus the summed node count of each
    /// child element; the four homoiconic wrapper arms
    /// ([`Self::Quote`], [`Self::Quasiquote`], [`Self::Unquote`],
    /// [`Self::UnquoteSplice`]) each contribute one node for the
    /// outer arm plus the node count of the wrapped inner form. The
    /// projection is a structural size on the AST — every closed-set
    /// arm counts as one, so the count is well-defined on ANY
    /// [`Sexp`] value regardless of how it was constructed.
    ///
    /// Load-bearing arithmetic identities:
    ///   * `Sexp::Nil.node_count() == 1`
    ///   * `Sexp::Atom(_).node_count() == 1`
    ///   * `Sexp::list(items).node_count() == 1 + sum(item.node_count())`
    ///   * `Sexp::quote(inner).node_count() == 1 + inner.node_count()`
    ///   * (peer identity for each other quote-family arm)
    ///
    /// The identities compose: `node_count` is monotone in tree
    /// growth (a strictly-larger tree — one containing more arms —
    /// has a strictly-larger count), so a resource ceiling keyed on
    /// `node_count` bounds the total AST arm-count reachable at that
    /// ceiling. A future [`Self::UnquoteSplice`] wrapper appearing
    /// inside a list contributes one node for the wrapper AND one
    /// node for the outer list arm plus the node count of the
    /// wrapper's inner form — the identity holds compositionally
    /// through the wrapper's `Box<Sexp>` payload.
    ///
    /// Consumers so far: [`crate::macro_expand::Expander`]'s
    /// `max_expansion_size` ceiling — the RESOURCE-axis peer of the
    /// `max_expansion_depth` (recursion length) and
    /// `max_cache_entries` (memoization width) ceilings — projects
    /// the freshly-applied macro expansion through `node_count` to
    /// decide whether the result crosses the "expansion bomb"
    /// threshold on the OUTPUT-SIZE axis. A `#[derive(TataraDomain)]`
    /// consumer that wants to reject "this macro produced a giant
    /// blob" at the expander boundary now inherits the projection
    /// mechanically through the ceiling; no per-consumer walker
    /// discipline required.
    ///
    /// The `usize` return shape is the natural resource-count
    /// carrier — sibling to `HashMap::len` (the cache-width ceiling
    /// consumes) and to the `usize` depth counter (the recursion
    /// ceiling consumes) — so all three ceilings compose against a
    /// single arithmetic type without cross-cast overhead.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the
    /// structural size of a value on the outer [`Sexp`] algebra
    /// becomes a first-class TYPED projection rather than a
    /// per-consumer hand-rolled walker. THEORY.md §VI.1 — generation
    /// over composition; a future ceiling on a subtree count (e.g.
    /// "reject any expansion whose LIST arms exceed N") emerges
    /// naturally as a peer projection on the same closed-set
    /// algebra, not as a separate walker.
    #[must_use]
    pub fn node_count(&self) -> usize {
        match self {
            Self::Nil | Self::Atom(_) => 1,
            Self::List(items) => 1 + items.iter().map(Self::node_count).sum::<usize>(),
            Self::Quote(inner)
            | Self::Quasiquote(inner)
            | Self::Unquote(inner)
            | Self::UnquoteSplice(inner) => 1 + inner.node_count(),
        }
    }
}

/// Static panic message for [`Sexp::expect_quote_form`]'s asserted-total
/// face of the quote-family projection. Pre-lift this literal appeared
/// inline at five `.expect(...)` callsites (`Hash for Sexp`,
/// `Display for Sexp`, `domain::sexp_shape`, `domain::sexp_to_json`,
/// `interop::iac_forge_tag`); post-lift it lives at ONE named const so a
/// regression that drifts the diagnostic at one site silently from the
/// others becomes structurally impossible. Sibling to the per-projection
/// asserted-total faces across the substrate's typed algebras — the
/// message names the invariant the outer pattern proves, not the
/// substring grep'able by tests.
pub const QUOTE_FAMILY_PROJECTION_INVARIANT: &str =
    "matched quote-family variant must project to Some via as_quote_form";

/// Closed-set typed identifier for the four homoiconic prefix-wrappers in
/// the substrate's `Sexp` algebra — `'x` ([`Sexp::Quote`]), `` `x ``
/// ([`Sexp::Quasiquote`]), `,x` ([`Sexp::Unquote`]), `,@x`
/// ([`Sexp::UnquoteSplice`]) — paired with the projections each consumer
/// surface needs ([`Self::prefix`] for [`crate::ast::Sexp`]'s `Display`
/// impl AND the reader's prefix dispatch dual, [`Self::hash_discriminator`]
/// for [`crate::ast::Sexp`]'s `Hash` impl, [`Self::as_unquote_form`] for
/// the 2-of-4 subset gate the template-substitution surface keys on).
///
/// Mirror at the homoiconic-prefix-wrapper boundary of the prior-run
/// `UnquoteForm` (template-marker subset, 2 variants),
/// `CompilerSpecIoStage` (disk-persistence surface),
/// `TemplateInvariantKind` (bytecode-runtime surface), `MacroDefHead`
/// (macro-definition-head closed set), and `KwargPath` (kwargs-path-shape
/// surface) closed-set lifts: those enums key their respective rejection
/// or projection variants on a typed identity carried inside the variant's
/// data shape; this enum keys the FOUR distinct quote-family rendering /
/// hashing / template-substitution sites on a typed marker identity.
/// Adding a fifth homoiconic prefix-wrapper (e.g., a hypothetical `,~`
/// reverse-unquote) requires extending this enum, which rustc-enforces
/// matching at every projection site (`prefix`, `hash_discriminator`,
/// `as_unquote_form`, plus `Sexp::as_quote_form`'s match arm) — the closed
/// set becomes a TYPE rather than four `&'static str` / `u8` literals that
/// could drift independently across `Sexp::Display`'s prefix arm and
/// `Sexp::Hash`'s discriminator arm and the reader's prefix dispatch.
///
/// Subset-gate relationship to [`UnquoteForm`]: the template-substitution
/// surface's [`Sexp::as_unquote`] is now `as_quote_form().and_then(|(qf,
/// inner)| qf.as_unquote_form().map(|uf| (uf, inner)))` — the 2-of-4
/// projection lives at ONE site on this algebra ([`Self::as_unquote_form`])
/// rather than being re-derived at every consumer that wants only the
/// `{Unquote, UnquoteSplice}` subset. A future enum variant that joins
/// the template-substitution subset (e.g. a typed `defalias`-projected
/// fifth marker) extends [`UnquoteForm`] AND
/// [`Self::as_unquote_form`]'s arm together, with rustc binding the
/// extension through the projection's `Option` return type.
///
/// Theory anchor: THEORY.md §II.1 invariant 1 — typed entry; the
/// homoiconic-prefix-wrapper dispatch (the reader's prefix-to-variant
/// gate AND the Display impl's variant-to-prefix dual) IS the rust-level
/// typed-entry / typed-exit gate, and naming its closed-set identity
/// lifts the gate from per-site literal-pair discipline to ONE typed
/// enum the substrate's diagnostic promotions hang off of.
/// THEORY.md §V.1 — knowable platform; the closed set of homoiconic
/// prefix-wrappers becomes a TYPE rather than four `&'static str` / `u8`
/// literals scattered across Hash / Display / interop / sexp_shape — a
/// typo in any one site is no longer a runtime drift but a compile error
/// against the typed projection. THEORY.md §VI.1 — generation over
/// composition; the typed enum lands the structural-completeness floor
/// for the quote-family surface, parallel to how `UnquoteForm` lands it
/// for the template-marker subset and `MacroDefHead` for the
/// macro-definition-head surface.
#[derive(Debug, Clone, Copy, PartialEq, Eq, tatara_closed_set::DeriveClosedSet)]
#[closed_set(via = "prefix", display, generate_unknown = "quote form")]
pub enum QuoteForm {
    /// `'x` — literal-quote prefix. The `'` marker; the inner expression
    /// is NOT subject to macro substitution. Projects to NO
    /// `UnquoteForm` (the template-substitution surface ignores quote).
    Quote,
    /// `` `x `` — quasi-quote prefix. The `` ` `` marker; the inner
    /// expression is the template body inside which `,` and `,@` mark
    /// substitution points. Projects to NO `UnquoteForm` (a quasi-quote
    /// is the substitution SCOPE, not a substitution itself).
    Quasiquote,
    /// `,x` — single-value substitution. The `,` marker; the inner
    /// symbol is substituted with its bound value at template
    /// expansion. Projects to `UnquoteForm::Unquote` for the
    /// template-substitution surface.
    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. Projects to
    /// `UnquoteForm::Splice` for the template-substitution surface.
    UnquoteSplice,
}

impl QuoteForm {
    /// The closed set of four homoiconic prefix-wrappers — single
    /// source of truth that drives every per-variant projection
    /// ([`Self::prefix`] / [`fmt::Display`], [`Self::hash_discriminator`],
    /// [`Self::as_unquote_form`], [`Self::iac_forge_tag`],
    /// [`Self::sexp_shape`], [`Self::wrap`], and the [`Self::FromStr`]
    /// decode sweep keyed on [`Self::prefix`]).
    ///
    /// Adding a hypothetical fifth homoiconic prefix-wrapper (e.g.
    /// a `,~` reverse-unquote, a `,?` conditional-unquote, or a
    /// `#'` Common-Lisp function-quote literal) lands at one
    /// [`Self::ALL`] entry plus one arm per projection — exhaustively
    /// checked by the compiler (the `[Self; 4]` 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
    /// [`crate::error::SexpShape::ALL`] (the twelve reachable outer
    /// shapes — superset of this enum's four via [`Self::sexp_shape`]),
    /// [`AtomKind::ALL`] (the six atomic-payload kinds — peer axis
    /// on the same algebra, also a 6-of-12 carving of `SexpShape`),
    /// [`crate::error::UnquoteForm::ALL`] (the two template-substitution
    /// markers — proper 2-of-4 subset of THIS enum via
    /// [`Self::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 homoiconic prefix
    /// (every `'`/`` ` ``/`,`/`,@` substring an authoring tool would
    /// surface in a completion list keys on this set's projection
    /// through [`Self::prefix`]); `tatara-check` coverage assertions
    /// over which quote-family wrappers reach a `Sexp::Display` /
    /// `Hash for Sexp` / `as_unquote_form` consumer arm at all — the
    /// typed sweep replaces a per-callsite vocabulary of four
    /// `&'static str` / `u8` literals; any future audit-trail metric
    /// jointly labeled by [`Self::prefix`] (e.g.
    /// `tatara_lisp_quote_family_total{prefix="'"}`) — the metric
    /// label set IS [`Self::ALL`] mapped through [`Self::prefix`];
    /// any future structural rewriter (typed analogue of MLIR's
    /// `op.walk<QuoteFormOp>()`) that wants to sweep over every
    /// quote-family wrapper in a typed sequence.
    pub const ALL: [Self; 4] = [
        Self::Quote,
        Self::Quasiquote,
        Self::Unquote,
        Self::UnquoteSplice,
    ];

    /// Canonical `&'static str` reader-prefix of [`Self::Quote`] —
    /// `"'"`. The ONE canonical bytes-payload on the closed-set
    /// [`QuoteForm`] algebra shared by [`Self::prefix`]'s [`Self::Quote`]
    /// arm AND the [`crate::ast::Sexp`] `Display` arm the arm feeds.
    ///
    /// Sibling posture to the closed set of per-role `pub const`
    /// bytes on the substrate's other closed-set outer algebras:
    /// [`crate::error::MacroDefHead::DEFMACRO_KEYWORD`] /
    /// [`crate::error::MacroDefHead::DEFPOINT_TEMPLATE_KEYWORD`] /
    /// [`crate::error::MacroDefHead::DEFCHECK_KEYWORD`] (per-role
    /// head-keyword algebra on the CL macro-definition surface),
    /// [`crate::ast::Atom::TRUE_LITERAL`] /
    /// [`crate::ast::Atom::FALSE_LITERAL`] (per-role Scheme-bool
    /// spelling algebra on the atomic-payload surface),
    /// [`crate::macro_expand::MacroParams::REST_MARKER`] /
    /// [`crate::macro_expand::MacroParams::OPTIONAL_MARKER`] (per-role
    /// CL lambda-list-keyword algebra on the macro-param surface).
    ///
    /// The `char`-level peer of THIS `&'static str` constant is
    /// [`Self::QUOTE_LEAD`] — the first (and only) char of this
    /// prefix. The structural round-trip law between the two is
    /// `Self::QUOTE_PREFIX.chars().next() == Some(Self::QUOTE_LEAD)`
    /// AND `Self::QUOTE_PREFIX.len() ==
    /// Self::QUOTE_LEAD.len_utf8()` — the ONE `char` byte
    /// composes the ONE `&'static str` prefix. Pinned by
    /// `quote_form_per_role_prefixes_route_through_matching_lead_char_for_single_char_prefixes`.
    ///
    /// A regression that inlines the `"'"` literal at
    /// [`Self::prefix`]'s [`Self::Quote`] arm and drifts the constant
    /// silently (e.g. an ELisp-compat port of the quote prefix to
    /// `#'`, a hypothetical Racket-compat swap to a distinct byte)
    /// fails at the algebra's `prefix()` path-uniformity pin
    /// (`quote_form_prefix_routes_through_typed_per_role_constants`)
    /// rather than at silent reader-family drift where the
    /// [`Sexp::Display`] round-trip breaks.
    pub const QUOTE_PREFIX: &'static str = "'";

    /// Canonical `&'static str` reader-prefix of [`Self::Quasiquote`]
    /// — `` "`" ``. Sibling of [`Self::QUOTE_PREFIX`] on the closed-set
    /// per-role quote-family prefix-bytes axis; see
    /// [`Self::QUOTE_PREFIX`] for the algebra-level round-trip +
    /// disjointness contracts every sibling shares. The `char`-level
    /// peer is [`Self::QUASIQUOTE_LEAD`].
    pub const QUASIQUOTE_PREFIX: &'static str = "`";

    /// Canonical `&'static str` reader-prefix of [`Self::Unquote`] —
    /// `","`. Sibling of [`Self::QUOTE_PREFIX`] on the closed-set
    /// per-role quote-family prefix-bytes axis; see
    /// [`Self::QUOTE_PREFIX`] for the algebra-level round-trip +
    /// disjointness contracts every sibling shares. The `char`-level
    /// peer is [`Self::UNQUOTE_LEAD`] (shared with
    /// [`Self::UNQUOTE_SPLICE_PREFIX`]'s lead byte — see the
    /// [`Self::UNQUOTE_LEAD`] docstring for the shared-lead-char
    /// discipline the two prefixes disambiguate on).
    pub const UNQUOTE_PREFIX: &'static str = ",";

    /// Canonical `&'static str` reader-prefix of [`Self::UnquoteSplice`]
    /// — `",@"`. The ONLY two-char prefix on the closed set; every
    /// other [`Self::PREFIXES`] entry is a single `char` rendered as
    /// `&'static str`. Sibling of [`Self::QUOTE_PREFIX`] on the closed-
    /// set per-role quote-family prefix-bytes axis.
    ///
    /// Structural composition law: `Self::UNQUOTE_SPLICE_PREFIX ==
    /// format!("{}{}", Self::UNQUOTE_LEAD, Self::SPLICE_DISCRIMINATOR)`
    /// — the two-char prefix decomposes cleanly into the ONE shared
    /// lead byte [`Self::UNQUOTE_LEAD`] + the ONE splice-promotion
    /// discriminator [`Self::SPLICE_DISCRIMINATOR`], both `char`-level
    /// constants on this algebra. Pinned by
    /// `quote_form_unquote_splice_prefix_constant_composes_from_unquote_lead_and_splice_discriminator`
    /// (byte-level composition through the per-role `pub const`) as a
    /// section-for-retraction peer of the pre-existing
    /// `quote_form_unquote_splice_prefix_composes_from_unquote_lead_and_splice_discriminator`
    /// pin (byte-level composition through the [`Self::prefix`]
    /// method).
    pub const UNQUOTE_SPLICE_PREFIX: &'static str = ",@";

    /// The closed-set forced-arity ALL array over the quote-family
    /// reader-prefix `&'static str` bytes in canonical declaration
    /// order matching [`Self::ALL`] element-wise. Sibling posture to
    /// [`crate::error::MacroDefHead::KEYWORDS`] (`[&'static str; 3]`
    /// on the CL macro-definition head algebra),
    /// [`crate::ast::Atom::BOOL_LITERALS`] (`[&'static str; 2]` on the
    /// Scheme-bool spelling algebra), and
    /// [`crate::macro_expand::MacroParams::LAMBDA_LIST_KEYWORDS`]
    /// (`[&'static str; 2]` on the CL lambda-list-keyword algebra) —
    /// every closed-set outer projection on the substrate now pins
    /// its canonical bytes at ONE `pub const` per role plus an ALL
    /// array for family-wide consumers.
    ///
    /// Adding a hypothetical fifth homoiconic prefix (a `,~`
    /// reverse-unquote, a `,?` conditional-unquote, a `#'` Common-
    /// Lisp function-quote) extends [`Self::ALL`] AND
    /// [`Self::PREFIXES`] AND [`Self::prefix`]'s arm AND one new
    /// per-role `pub const` in lockstep — rustc's forced-arity check
    /// on `[&'static str; N]` fails compilation if either ALL array
    /// grows without the other.
    ///
    /// Future consumers that compose against [`Self::PREFIXES`]:
    /// - LSP / REPL completion for the operator-facing rendered
    ///   homoiconic prefix bar — the completion set IS
    ///   [`Self::PREFIXES`] rather than four hand-enumerated
    ///   `&'static str` literals per completion provider.
    /// - `tatara-check` coverage assertions that sweep workspace
    ///   `.lisp` files for every canonical quote-family prefix — the
    ///   typed sweep replaces per-consumer inline enumeration of the
    ///   four literals.
    /// - Any future audit-trail metric jointly labeled by
    ///   [`Self::prefix`] (e.g.
    ///   `tatara_lisp_quote_family_total{prefix="'"}`) — the metric
    ///   label set IS [`Self::PREFIXES`] mapped through
    ///   [`Self::prefix`].
    pub const PREFIXES: [&'static str; 4] = [
        Self::QUOTE_PREFIX,
        Self::QUASIQUOTE_PREFIX,
        Self::UNQUOTE_PREFIX,
        Self::UNQUOTE_SPLICE_PREFIX,
    ];

    /// Canonical `&'static str` prefix that paired with the variant
    /// renders the homoiconic form — [`Self::QUOTE_PREFIX`] for
    /// [`Self::Quote`], [`Self::QUASIQUOTE_PREFIX`] for
    /// [`Self::Quasiquote`], [`Self::UNQUOTE_PREFIX`] for
    /// [`Self::Unquote`], [`Self::UNQUOTE_SPLICE_PREFIX`] for
    /// [`Self::UnquoteSplice`]. Threaded through
    /// [`crate::ast::Sexp`]'s `Display` impl so the per-variant prefix
    /// rendering lives at ONE site on this algebra rather than four
    /// inline literal strings across the Display arms.
    ///
    /// Post-lift the four arms route through the per-role `pub const`
    /// bytes on the closed-set [`QuoteForm`] algebra rather than
    /// inline `&'static str` literals — so a rename of ONE canonical
    /// prefix bytes (an ELisp-compat port of `Quote` to `"#'"`, a
    /// hypothetical Racket-compat swap of `Quasiquote`, a Common-Lisp-
    /// standard rename of `UnquoteSplice` to `",."`) lands as ONE
    /// edit to the matching `pub const` — every downstream consumer
    /// that binds to the algebra ([`crate::ast::Sexp`]'s `Display`
    /// impl, the reader's tokenizer round-trip law, the future
    /// canonical-form taggers) inherits the rename mechanically.
    ///
    /// Structural dual of the reader's [`crate::reader::read_quoted`]
    /// dispatch: the reader maps prefix-tokens to `Sexp::{Quote,
    /// Quasiquote, Unquote, UnquoteSplice}` constructors; this method
    /// maps the typed `QuoteForm` marker back to its canonical prefix
    /// string. Adding a fifth prefix extends both sides — the reader's
    /// tokenizer + dispatch AND this method — with rustc enforcing
    /// the pair through the closed-set enum. Round-trip:
    /// `read(format!("{}{inner}", qf.prefix()))` produces the
    /// `Sexp::*` variant matching `qf`, by construction.
    ///
    /// The `&'static str` lifetime is load-bearing: it lets every
    /// consumer (Display arm, future format strings, future interop
    /// canonical-form taggers) project through this method without
    /// an allocation, parallel to how [`UnquoteForm::marker`]
    /// projects its 2-of-4 subset surface.
    #[must_use]
    pub fn prefix(self) -> &'static str {
        match self {
            Self::Quote => Self::QUOTE_PREFIX,
            Self::Quasiquote => Self::QUASIQUOTE_PREFIX,
            Self::Unquote => Self::UNQUOTE_PREFIX,
            Self::UnquoteSplice => Self::UNQUOTE_SPLICE_PREFIX,
        }
    }

    /// Canonical `'` LEAD `char` of [`Self::Quote`]'s [`Self::prefix`]
    /// (`"'"`) — the ONE canonical `char` on the [`QuoteForm`] algebra the
    /// substrate's Quote-family single-quote lead-byte disjointness
    /// contract binds to.
    ///
    /// Sibling posture to the closed set of `pub const` reader-punctuation
    /// canonical `char` bytes on the substrate:
    /// [`Self::SPLICE_DISCRIMINATOR`] (`'@'`),
    /// [`crate::ast::Atom::STR_DELIMITER`] (`'"'`),
    /// [`crate::ast::Atom::STR_ESCAPE_LEAD`] (`'\\'`),
    /// [`crate::ast::Atom::KEYWORD_MARKER_LEAD`] (`':'`),
    /// [`crate::ast::Atom::BOOL_LITERAL_LEAD`] (`'#'`),
    /// [`crate::ast::Sexp::LIST_OPEN`] (`'('`),
    /// [`crate::ast::Sexp::LIST_CLOSE`] (`')'`),
    /// [`crate::ast::Sexp::COMMENT_LEAD`] (`';'`),
    /// [`crate::ast::Sexp::COMMENT_TERM`] (`'\n'`) — every canonical per-
    /// role byte the reader's tokenizer specialises on is a `pub const`
    /// on its owning closed-set algebra. This constant closes the Quote-
    /// family single-quote lead byte at the SAME algebra as the
    /// [`Self::lead_char`] projection (whose [`Self::Quote`] arm returns
    /// this byte) AND the [`Self::from_lead_char`] inverse (whose match
    /// arm decodes this byte back to [`Self::Quote`]).
    ///
    /// Structural round-trip contract:
    /// `Self::from_lead_char(Self::QUOTE_LEAD) == Some(Self::Quote)`
    /// AND `Self::Quote.lead_char() == Self::QUOTE_LEAD` — pinned by
    /// `quote_form_lead_constants_round_trip_through_lead_char_projections`.
    /// A regression that drifts EITHER the constant OR the paired
    /// projection surfaces at the pin rather than at a silent tokenizer
    /// drift where `'foo` classifies as a bare atom instead of
    /// [`crate::ast::Sexp::Quote`].
    ///
    /// Disjointness contract: `QUOTE_LEAD`'s byte MUST differ from
    /// [`Self::QUASIQUOTE_LEAD`], [`Self::UNQUOTE_LEAD`],
    /// [`Self::SPLICE_DISCRIMINATOR`],
    /// [`crate::ast::Atom::STR_DELIMITER`],
    /// [`crate::ast::Atom::STR_ESCAPE_LEAD`],
    /// [`crate::ast::Atom::KEYWORD_MARKER_LEAD`],
    /// [`crate::ast::Atom::BOOL_LITERAL_LEAD`],
    /// [`crate::ast::Sexp::LIST_OPEN`], [`crate::ast::Sexp::LIST_CLOSE`],
    /// [`crate::ast::Sexp::COMMENT_LEAD`], and
    /// [`crate::ast::Sexp::COMMENT_TERM`] — every other closed-set outer-
    /// marker byte the reader's tokenizer specialises on. A collision
    /// would silently break the reader's outer dispatch. Pinned by
    /// `quote_form_lead_constants_distinct_from_every_other_algebra_marker_char`.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 2 — free middle; the
    /// (Quote-family single-quote lead byte, canonical `'\''`) pairing
    /// binds at ONE constant on the closed-set [`QuoteForm`] algebra
    /// regardless of which paired projection reaches in. THEORY.md §V.1
    /// — knowable platform; the canonical Quote-family lead byte becomes
    /// a TYPE-level constant on the substrate algebra rather than an
    /// inline `'\''` char literal at [`Self::lead_char`]'s [`Self::Quote`]
    /// arm AND at [`Self::from_lead_char`]'s decode arm.
    pub const QUOTE_LEAD: char = '\'';

    /// Canonical `` ` `` LEAD `char` of [`Self::Quasiquote`]'s
    /// [`Self::prefix`] (`` "`" ``) — sibling of [`Self::QUOTE_LEAD`] on
    /// the closed-set quote-family lead-byte axis. See
    /// [`Self::QUOTE_LEAD`] for the algebra-level round-trip +
    /// disjointness contracts every sibling shares. Bound by
    /// [`Self::lead_char`]'s [`Self::Quasiquote`] arm AND
    /// [`Self::from_lead_char`]'s decode arm.
    pub const QUASIQUOTE_LEAD: char = '`';

    /// Canonical `,` LEAD `char` SHARED by [`Self::Unquote`]'s
    /// [`Self::prefix`] (`","`) AND [`Self::UnquoteSplice`]'s
    /// [`Self::prefix`] (`",@"`) — the splice's two-char prefix opens
    /// with this byte and disambiguates on the peek-then-consume
    /// [`Self::SPLICE_DISCRIMINATOR`] second char inside
    /// [`crate::reader::tokenize`]. Sibling of [`Self::QUOTE_LEAD`] on
    /// the closed-set quote-family lead-byte axis; see
    /// [`Self::QUOTE_LEAD`] for the algebra-level round-trip +
    /// disjointness contracts every sibling shares. Bound by
    /// [`Self::lead_char`]'s `Self::Unquote | Self::UnquoteSplice` merged
    /// arm AND [`Self::from_lead_char`]'s decode arm.
    ///
    /// Composition identity with [`Self::SPLICE_DISCRIMINATOR`]:
    /// `format!("{}{}", Self::UNQUOTE_LEAD, Self::SPLICE_DISCRIMINATOR)
    /// == Self::UnquoteSplice.prefix()` — the two byte-level constants
    /// on the closed-set [`QuoteForm`] algebra compose the ONLY two-char
    /// [`Self::prefix`] in the closed set. Pinned by
    /// `quote_form_unquote_splice_prefix_composes_from_unquote_lead_and_splice_discriminator`.
    /// A regression that renames EITHER constant without touching the
    /// paired [`Self::UnquoteSplice`]'s [`Self::prefix`] arm surfaces
    /// here rather than as a silent `,@` reader drift.
    pub const UNQUOTE_LEAD: char = ',';

    /// The closed-set forced-arity ALL array over the quote-family
    /// DISTINCT reader-lead-byte `char`s in canonical declaration
    /// order matching [`Self::ALL`]'s three-of-four distinct-lead-
    /// byte projection through [`Self::lead_char`] — [`Self::QUOTE_LEAD`]
    /// (`'\''` — the [`Self::Quote`] lead byte), [`Self::QUASIQUOTE_LEAD`]
    /// (`` '`' `` — the [`Self::Quasiquote`] lead byte),
    /// [`Self::UNQUOTE_LEAD`] (`','` — the SHARED lead byte of BOTH
    /// [`Self::Unquote`] AND [`Self::UnquoteSplice`], with the splice
    /// promotion living at the reader's peek-then-consume
    /// [`Self::SPLICE_DISCRIMINATOR`] second-char arm rather than at a
    /// distinct lead byte).
    ///
    /// The `[char; 3]` cardinality (vs the peer [`Self::PREFIXES`]
    /// `[&'static str; 4]`) IS the structural axis distinguishing the
    /// DISTINCT-lead-byte sub-vocabulary from the PER-VARIANT-prefix
    /// sub-vocabulary — three-of-four distinct-lead-byte collapse is
    /// definitional (only [`Self::UnquoteSplice`]'s two-char `,@`
    /// prefix shares its lead byte with a sibling variant; every other
    /// variant owns its lead byte outright). The shape asymmetry
    /// between the two ALL arrays encodes the shared-lead-byte
    /// collapse identity on the closed-set [`QuoteForm`] algebra at
    /// the type-system level: a consumer that reaches for
    /// [`Self::LEADS`] reads the distinct-lead-byte cardinality
    /// directly off the array's forced arity rather than through a
    /// per-consumer `HashSet`-then-count over [`Self::PREFIXES`]'s
    /// first chars.
    ///
    /// Sibling posture to [`Self::PREFIXES`] (`[&'static str; 4]` on
    /// the per-variant reader-prefix axis) AND [`Self::IAC_FORGE_TAGS`]
    /// (`[&'static str; 4]` on the per-variant canonical-form tag
    /// axis) — those two ALL arrays close the per-variant axes of the
    /// outer-tokenizer `QuoteForm` closed set; this ALL array closes
    /// the peer DISTINCT-lead-byte axis at the SHAPE-ASYMMETRIC
    /// `[char; N]` cardinality. Also sibling-shape to
    /// [`crate::ast::Sexp::LIST_DELIMITERS`] (`[char; 2]` on the outer-
    /// structural paired-delimiter axis), [`Atom::SELF_ESCAPE_TABLE`]
    /// (`[char; 2]` on the inner-Str-payload self-escape axis), and
    /// [`Atom::BOOL_LITERALS`] (`[&'static str; 2]` on the Scheme-bool
    /// spelling axis) — every closed-set outer projection on the
    /// substrate now pins its canonical bytes at ONE `pub const` per
    /// role plus an ALL array for family-wide consumers.
    ///
    /// Adding a hypothetical fifth homoiconic prefix with a DISTINCT
    /// lead byte (a `~` reverse-unquote, a `?` conditional-unquote, a
    /// `#` reader-macro-lead) extends [`Self::ALL`] AND
    /// [`Self::PREFIXES`] AND [`Self::LEADS`] AND [`Self::lead_char`]'s
    /// arm AND [`Self::from_lead_char`]'s arm AND one new per-role
    /// `pub const` in lockstep — rustc's forced-arity check on
    /// `[char; N]` fails compilation if the LEADS array grows without
    /// the paired algebra constant, and the paired PREFIXES /
    /// IAC_FORGE_TAGS arrays extend by ONE row each in lockstep. A
    /// fifth prefix that SHARES its lead byte with an existing variant
    /// (like the splice's `,@` sharing with unquote's `,`) leaves
    /// [`Self::LEADS`]'s cardinality unchanged — the DISTINCT-lead-
    /// byte set is invariant under such an extension, closing the
    /// splice-family promotion pattern at the ALL-array level.
    ///
    /// Future consumers that compose against [`Self::LEADS`]:
    /// - LSP / REPL completion for the operator-facing reader-entry
    ///   lead-byte set — the completion set IS [`Self::LEADS`] rather
    ///   than three hand-enumerated `char` literals per completion
    ///   provider.
    /// - The reader's outer tokenizer pre-match check that gates the
    ///   quote-family dispatch — the check IS
    ///   `Self::LEADS.contains(&ch)` rather than three inline
    ///   `ch == Self::QUOTE_LEAD || ch == Self::QUASIQUOTE_LEAD ||
    ///   ch == Self::UNQUOTE_LEAD` disjuncts, and the sweep binds
    ///   through the ALL array's forced arity.
    /// - A hypothetical `tatara_lisp_quote_family_lead_total{lead="'"}`
    ///   metric surface — the label-set generator sweeps
    ///   [`Self::LEADS`] verbatim rather than re-typing the three
    ///   distinct-lead bytes inline at each recorder.
    /// - Any future syntax-highlighter / structural editor that needs
    ///   the reader-entry lead-byte set for classification — the
    ///   editor's per-char classifier binds through [`Self::LEADS`]
    ///   rather than three parallel `char`-literal patterns.
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the three
    /// distinct quote-family reader-lead bytes now bind at ONE typed
    /// `[char; 3]` array on the closed-set [`QuoteForm`] algebra
    /// rather than as three inline algebra-constant enumerations at
    /// every consumer that iterates the distinct-lead-byte sub-
    /// vocabulary. THEORY.md §V.1 — knowable platform; the distinct-
    /// lead-byte sub-vocabulary becomes load-bearing typed data on
    /// the closed-set outer [`QuoteForm`] algebra. THEORY.md §VI.1 —
    /// generation over composition; the shared-lead-byte collapse
    /// identity (four variants → three distinct lead bytes)
    /// composes at ONE typed ALL array whose shape-asymmetric
    /// cardinality (3 vs [`Self::PREFIXES`]'s 4) IS the collapse
    /// invariant carried at the type-system level.
    pub const LEADS: [char; 3] = [Self::QUOTE_LEAD, Self::QUASIQUOTE_LEAD, Self::UNQUOTE_LEAD];

    /// Canonical FIRST-char of [`Self::prefix`] — [`Self::QUOTE_LEAD`]
    /// for [`Self::Quote`], [`Self::QUASIQUOTE_LEAD`] for
    /// [`Self::Quasiquote`], [`Self::UNQUOTE_LEAD`] for BOTH
    /// [`Self::Unquote`] AND [`Self::UnquoteSplice`] (the splice's two-
    /// char `,@` prefix shares its lead byte with bare unquote and
    /// disambiguates on the peek-then-consume `@` second char inside
    /// [`crate::reader::tokenize`]).
    /// The three-of-four collapse onto three distinct lead chars is
    /// structurally fixed — 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.
    ///
    /// Structural dual of [`Self::from_lead_char`]: this method projects
    /// the closed-set marker to its canonical reader-punctuation lead
    /// char; the sibling projects the lead char back to the DEFAULT
    /// marker on that char (`,` → [`Self::Unquote`], with the splice
    /// promotion living at the reader's peek arm rather than at
    /// [`Self::from_lead_char`]'s decode). Every variant round-trips
    /// through the composition `Self::from_lead_char(qf.lead_char())`,
    /// with the `{Unquote, UnquoteSplice}` two-of-four collapsing onto
    /// `Some(Unquote)` per the shared-lead-char structural identity.
    ///
    /// The `const` qualifier is load-bearing: [`crate::reader::tokenize`]
    /// binds its outer-match quote-family dispatch to this projection
    /// via a pre-match `Self::from_lead_char` check, and future consumer
    /// sites (e.g. `const` array literals of every reader-recognized
    /// lead byte the tokenizer could dispatch on, LSP completion
    /// generators that pre-materialize the lead-char set) route through
    /// this projection at compile time. Sibling posture to
    /// [`crate::ast::Atom::STR_DELIMITER`] one axis over on the same
    /// closed-set-lead-char algebra — that constant is the ONE `char`
    /// the `Token::Str` open/close/self-escape/bare-atom-terminator
    /// FOUR sites in the reader pair with; this method is the ONE
    /// projection the `Token::Quoted(QuoteForm)` outer-dispatch AND
    /// the same bare-atom-terminator disjunct pair with across FOUR
    /// per-variant lead chars.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 1 — typed entry; the
    /// reader's per-char quote-family dispatch IS the typed-entry gate,
    /// and lifting its (char, `QuoteForm`) pairing to ONE projection
    /// method plus one inverse (see [`Self::from_lead_char`]) closes
    /// the tokenizer's outer-arm entry surface onto the closed-set
    /// algebra rather than four inline `char` literals scattered across
    /// three tokenizer arms (`'\''` / `` '`' `` / `','` outer-match arms)
    /// AND three bare-atom-terminator disjuncts (`ch == '\''` / `ch ==
    /// '`'` / `ch == ','`). THEORY.md §V.1 — knowable platform; the
    /// closed set of quote-family lead chars becomes a TYPE (the
    /// enum's arms projected through this method) rather than four
    /// literal `char` values scattered across the reader's outer
    /// dispatch AND its bare-atom terminator. THEORY.md §VI.1 —
    /// generation over composition; a fifth homoiconic prefix
    /// (hypothetical `,~` reverse-unquote, `#'` function-quote,
    /// `#[…]` vector-quote) extends [`Self`] AND this method AND
    /// [`Self::from_lead_char`] AND the tokenizer's pre-match check
    /// in lockstep, with rustc binding the extension through
    /// exhaustiveness over the closed enum.
    #[must_use]
    pub const fn lead_char(self) -> char {
        match self {
            Self::Quote => Self::QUOTE_LEAD,
            Self::Quasiquote => Self::QUASIQUOTE_LEAD,
            Self::Unquote | Self::UnquoteSplice => Self::UNQUOTE_LEAD,
        }
    }

    /// Inverse of [`Self::lead_char`] on the three-of-four distinct
    /// lead chars — `'\''` decodes to `Some(Self::Quote)`, `` '`' ``
    /// decodes to `Some(Self::Quasiquote)`, `','` decodes to
    /// `Some(Self::Unquote)` (the DEFAULT variant on the shared `,`
    /// lead char; the two-char `,@` splice promotion lives at
    /// [`crate::reader::tokenize`]'s peek-then-consume `@` disambiguator
    /// rather than at this decode). Every other `char` yields `None` —
    /// the closed-set guarantee on [`Self`] AND on the tokenizer's
    /// outer-arm set (whitespace, `(`, `)`, [`crate::ast::Atom::STR_DELIMITER`],
    /// `;`, bare atom) ensures the four typed markers partition the
    /// three distinct lead chars injectively against every other
    /// tokenizer-recognized entry char.
    ///
    /// ONE consumer entrypoint the reader's `tokenize` binds against:
    /// the outer-match quote-family dispatch was pre-lift a hand-rolled
    /// three-arm cascade (`'\''` / `` '`' `` / `','`) with per-arm
    /// `Token::Quoted(QuoteForm::*)` construction and a fourth
    /// `Token::Quoted(QuoteForm::UnquoteSplice)` arm buried inside the
    /// `','`-arm's peek branch; post-lift the tokenizer pre-checks
    /// `Self::from_lead_char(c)` before the outer match, promotes the
    /// returned `Self::Unquote` to `Self::UnquoteSplice` on second-char
    /// `@`, and emits ONE `Token::Quoted(final_qf)` — the (lead char,
    /// [`Self`] marker) pairing binds at ONE site on the closed-set
    /// algebra rather than at three inline `char` literals across
    /// three outer-match arms. The bare-atom terminator disjunct at
    /// the reader's `Token::Atom` accumulator loop routes through
    /// `Self::from_lead_char(ch).is_some()` so the three
    /// quote-family-lead disjuncts (`ch == '\''` / `ch == '`'` /
    /// `ch == ','`) collapse to ONE gate — a regression that drifts
    /// one bare-atom-terminator disjunct from the outer-dispatch's
    /// quote-family arm becomes structurally impossible because
    /// there is exactly ONE decode both sites consume.
    ///
    /// The two-of-four collapse onto `Some(Self::Unquote)` for the
    /// `,` lead char is INTENTIONAL: `Self::UnquoteSplice` has NO
    /// distinct lead char; the tokenizer must see two consecutive
    /// chars (`,` then `@`) to promote the decoded `Self::Unquote`
    /// to `Self::UnquoteSplice`. Placing the promotion at the
    /// reader's peek arm rather than at this decode keeps the
    /// (char → marker) projection at the closed-set algebra's
    /// character-boundary surface (one char in, one variant out)
    /// and the (two-char sequence → splice) promotion at the
    /// tokenizer's streaming surface (peek and consume the second
    /// char). This split parallels the reader's split of `Token::Str`
    /// into open-delimiter dispatch ([`crate::ast::Atom::STR_DELIMITER`])
    /// AND inner-payload accumulation — the closed-set char algebra
    /// decodes the entry char; the streaming reader handles multi-
    /// char follow-through.
    ///
    /// Sibling to [`crate::ast::Atom::from_lexeme`] one axis over on
    /// the same typed-entry family — that method decodes a bare-atom
    /// lexeme into a typed [`crate::ast::Atom`] variant; this method
    /// decodes a single lead char into a typed [`Self`] variant. Both
    /// map the reader's per-char / per-lexeme classification surface
    /// onto the substrate's closed-set algebra so the reader's outer
    /// dispatch binds through ONE typed decode rather than through
    /// scattered per-arm `char` / `&str` literal patterns.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 1 — typed entry; the
    /// reader's per-char quote-family classification IS the typed-entry
    /// gate. THEORY.md §V.1 — knowable platform; the reader's outer
    /// dispatch AND the bare-atom terminator each route through ONE
    /// typed decode against the closed-set algebra rather than through
    /// three (or four) parallel `char`-literal patterns that could
    /// drift independently — a regression that renames one lead char
    /// without updating the sibling site fails at rustc / test time
    /// rather than as a silent tokenizer drift.
    #[must_use]
    pub const fn from_lead_char(c: char) -> Option<Self> {
        match c {
            Self::QUOTE_LEAD => Some(Self::Quote),
            Self::QUASIQUOTE_LEAD => Some(Self::Quasiquote),
            Self::UNQUOTE_LEAD => Some(Self::Unquote),
            _ => None,
        }
    }

    /// Canonical SECOND char of [`Self::UnquoteSplice`]'s two-char `,@`
    /// [`Self::prefix`] — the ONE `'@'` byte the reader's peek-then-
    /// consume splice-promotion arm inside [`crate::reader::tokenize`]
    /// disambiguates on. Sibling posture to [`crate::ast::Atom::STR_DELIMITER`]
    /// (one-char Str-payload delimiter shared across four `"`-round-
    /// trip sites) AND to [`crate::ast::Sexp::COMMENT_LEAD`] (one-char
    /// line-comment lead shared across two `;`-boundary sites) — those
    /// two constants project a single byte onto their respective closed-
    /// set algebras (`Atom` and outer-`Sexp`); this constant projects
    /// the single byte that composes the `,` [`Self::Unquote`]
    /// [`Self::lead_char`] into the two-char [`Self::UnquoteSplice`]
    /// [`Self::prefix`] onto the same closed-set [`Self`] algebra.
    ///
    /// The `,@` splice is the ONLY multi-char [`Self::prefix`] in the
    /// closed set — [`Self::Quote`] / [`Self::Quasiquote`] / [`Self::Unquote`]
    /// each render as a single [`Self::lead_char`] byte; only
    /// [`Self::UnquoteSplice`] appends this discriminator. The
    /// composition [`Self::Unquote::prefix()`] + `SPLICE_DISCRIMINATOR`
    /// == [`Self::UnquoteSplice::prefix()`] IS the structural identity
    /// the reader's peek arm depends on — pinned by
    /// `quote_form_unquote_splice_prefix_composes_from_unquote_prefix_and_splice_discriminator`.
    /// A future hypothetical fifth homoiconic prefix with its own two-
    /// char extension (e.g. `,~` reverse-unquote via a `~` discriminator,
    /// `#'` function-quote via a `'` discriminator) extends [`Self`]
    /// AND a per-variant promotion peer (extending
    /// [`Self::promote_via_next_char`]) in lockstep — rustc binds the
    /// extension through exhaustiveness over the closed enum.
    ///
    /// The `const` qualifier is load-bearing: [`Self::promote_via_next_char`]'s
    /// body binds through this constant in a `const fn` context so the
    /// reader's peek arm consumes the promotion table at compile time.
    /// Sibling posture to [`crate::ast::Atom::STR_DELIMITER`],
    /// [`crate::ast::Atom::KEYWORD_MARKER`], [`crate::ast::Sexp::LIST_OPEN`],
    /// [`crate::ast::Sexp::LIST_CLOSE`], [`crate::ast::Sexp::COMMENT_LEAD`] —
    /// every canonical reader-punctuation constant on the substrate is a
    /// `pub const` on its owning closed-set algebra.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 1 — typed entry; the
    /// reader's two-char splice-promotion gate IS the typed-entry gate
    /// on the `,@` boundary, and lifting the `@` discriminator to ONE
    /// canonical byte on the closed-set algebra closes the gate's
    /// entry-char identity onto the algebra rather than at an inline
    /// `char` literal at the reader's peek arm. THEORY.md §V.1 —
    /// knowable platform; the splice-promotion discriminator becomes a
    /// TYPED byte on the substrate algebra rather than an inline `'@'`
    /// scattered across the reader — a regression that renames the byte
    /// without updating the sibling promotion peer fails at rustc /
    /// test time rather than as a silent tokenizer drift where `,@xs`
    /// forms silently degrade to `,` + `@xs` two-token sequences.
    pub const SPLICE_DISCRIMINATOR: char = '@';

    /// Closed-set forced-arity ALL array over the canonical promotion
    /// triples on the substrate's quote-family algebra —
    /// `(head_variant, next_char_discriminator, promoted_variant)` for
    /// every `(head, next)` pair whose [`Self::promote_via_next_char`]
    /// projection yields `Some(promoted)`. Post-lift the promotion
    /// algebra's canonical triples bind at ONE typed
    /// `[(Self, char, Self); N]` array on the closed-set [`QuoteForm`]
    /// algebra rather than at zero-primitive-plus-inline-arm-literals
    /// inside [`Self::promote_via_next_char`]'s match body.
    ///
    /// The substrate's current promotion algebra is the singleton
    /// `[(Self::Unquote, Self::SPLICE_DISCRIMINATOR, Self::UnquoteSplice)]`
    /// — the ONLY (variant, next-char) → longer-variant mapping the
    /// reader's peek-then-consume `@` promotion arm depends on. Its
    /// forced-arity `1` is INTENTIONAL and load-bearing: [`Self::UnquoteSplice`]
    /// is the ONLY variant with a two-char [`Self::prefix`], so the
    /// promotion table has exactly ONE `Some` arm and every other
    /// pairing rejects — the closed set of promotions is the singleton
    /// `{(Unquote, '@') → UnquoteSplice}` on the `Self × char →
    /// Option<Self>` product. Pinned bit-for-bit by
    /// `quote_form_promotions_has_expected_cardinality` (forced-arity)
    /// AND `quote_form_promotions_pin_legacy_splice_promotion_triple`
    /// (identity of the singleton entry). A future fifth homoiconic
    /// prefix with its own two-char extension (a hypothetical `,~`
    /// reverse-unquote via a `~` discriminator, a `#'` function-quote
    /// via a `'` discriminator, a `,?` conditional-unquote via a `?`
    /// discriminator) extends [`Self::ALL`] AND appends ONE new
    /// promotion triple to [`Self::PROMOTIONS`] AND extends
    /// [`Self::promote_via_next_char`]'s match body in lockstep —
    /// rustc's forced-arity check on the `[(Self, char, Self); N]`
    /// array fails compilation if the array's cardinality grows
    /// without a matching arm on the projection method.
    ///
    /// Sibling posture to the closed-set forced-arity ALL arrays across
    /// the substrate's [`QuoteForm`] algebra — [`Self::ALL`]
    /// (`[Self; 4]` — the closed set of variants),
    /// [`Self::PREFIXES`] (`[&'static str; 4]` — the reader-prefix
    /// `&'static str` axis), [`Self::LABELS`] (`[&'static str; 4]` —
    /// the diagnostic-label `&'static str` axis),
    /// [`Self::IAC_FORGE_TAGS`] (`[&'static str; 4]` — the iac-forge
    /// canonical-form tag `&'static str` axis),
    /// [`Self::LEADS`] (`[char; 3]` — the reader-lead `char` axis with
    /// shape-asymmetric cardinality reflecting the shared-lead-byte
    /// collapse of the `,` prefix across [`Self::Unquote`] AND
    /// [`Self::UnquoteSplice`]), and [`Self::HASH_DISCRIMINATORS`]
    /// (`[u8; 4]` — the outer-Sexp cache-key byte axis). This lift adds
    /// the SEVENTH per-family axis on the algebra — the (head, disc,
    /// promoted) triple axis on the closed-set promotion product.
    /// Each of the seven axes now pins its per-role canonical data at
    /// ONE `pub const` per role PLUS an ALL array for family-wide
    /// consumers, across the same closed set of four variants (or
    /// three-of-four for the shape-asymmetric [`Self::LEADS`] axis's
    /// shared-lead-char collapse, or one-of-four for the promotion-
    /// asymmetric [`Self::PROMOTIONS`] axis's single-arm collapse).
    ///
    /// Composition identity (pinned by
    /// `quote_form_promotions_align_with_promote_via_next_char_for_every_entry`):
    /// for every `(head, disc, promoted)` in [`Self::PROMOTIONS`],
    /// `head.promote_via_next_char(disc) == Some(promoted)`. The
    /// projection's Some-arm binds through [`Self::PROMOTIONS`]`[i].2`
    /// (the promoted-variant column of the ONE promotion triple) — a
    /// regression that drifts the triple's promoted-variant column
    /// silently redirects every reader `,@` sequence to a phantom
    /// variant AND fails the alignment pin at rustc / test time
    /// rather than at silent tokenizer drift where every `,@xs` form
    /// tokenizes to the wrong closed-set marker.
    ///
    /// Rejection contract (pinned by
    /// `quote_form_promotions_close_promote_via_next_char_against_every_non_promotion_pair`):
    /// for every `(head, next)` pair NOT in [`Self::PROMOTIONS`]'s
    /// projection to `(Self × char)`, `head.promote_via_next_char(next)
    /// == None`. Sweeps the [`Self::ALL`] × (rejection-char sweep)
    /// product against the promotion set's complement — a regression
    /// that widened the promotion algebra (e.g. phantom-promoted
    /// [`Self::Quote`] on `'@'` after a copy-paste drift on the match
    /// arm) surfaces at test time rather than at silent tokenizer
    /// drift where bare `'@xs` forms silently degrade to a phantom
    /// [`Self::UnquoteSplice`]-shaped sequence.
    ///
    /// Composition law (rendered-prefix identity, pinned by
    /// `quote_form_promotions_compose_prefix_from_source_prefix_and_discriminator_for_every_entry`):
    /// for every `(head, disc, promoted)` in [`Self::PROMOTIONS`],
    /// `format!("{}{}", head.prefix(), disc) == promoted.prefix()`.
    /// The (head prefix + discriminator) source-text composition
    /// agrees byte-for-byte with the promoted variant's rendered
    /// prefix — the reader's peek-then-consume arm's rendered
    /// prefix identity closes the read↔write duality across the
    /// promotion algebra. Sibling to the pre-existing
    /// `quote_form_promote_via_next_char_composes_prefix_from_source_prefix_and_next_char`
    /// which pins the same law through the projection method rather
    /// than through the triple's data directly — this pin closes the
    /// law at the constant, that pin closes it at the projection.
    ///
    /// `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 public projections
    /// ([`Self::promote_via_next_char`], [`Self::prefix`],
    /// [`Self::from_lead_char`]) don't already serve — same visibility
    /// rationale as [`Self::HASH_DISCRIMINATORS`] on the sibling
    /// cache-key axis.
    ///
    /// The `#[allow(dead_code)]` posture matches
    /// [`Self::HASH_DISCRIMINATORS`] / [`AtomKind::HASH_DISCRIMINATORS`]:
    /// the substrate's current [`Self::promote_via_next_char`] body
    /// dispatches through ONE match arm bound to the ONE promotion
    /// triple's promoted-variant column ([`Self::PROMOTIONS`]`[0].2`),
    /// with the head-pattern + discriminator-pattern arm literals
    /// preserved for the const-fn match's pattern surface (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 promotion algebra (a future
    /// `tatara-check` predicate `(check-promotion-algebra-injective …)`
    /// that verifies each `(head, disc)` pair projects to a unique
    /// promoted variant, a future LSP structural-navigation filter
    /// that keys on the promotion algebra's cardinality, a future
    /// `TypedRewriter<PromotionOp>` sweep zipping ALL / PREFIXES /
    /// LABELS / IAC_FORGE_TAGS / HASH_DISCRIMINATORS / PROMOTIONS in
    /// lockstep for a family-wide render) 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`] +
    /// [`AtomKind::HASH_DISCRIMINATORS`] +
    /// [`crate::error::StructuralKind::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 promotion
    /// algebra's canonical triples to ONE typed `[(Self, char, Self);
    /// N]` primitive on the closed-set algebra closes the gate's
    /// two-char entry surface onto the algebra rather than at inline
    /// arm literals scattered across the const-fn match body.
    /// THEORY.md §III — the typescape; the singleton promotion triple
    /// binds at ONE typed `pub const` on the closed-set [`QuoteForm`]
    /// algebra rather than at zero-primitive-plus-inline-arm-literals
    /// at [`Self::promote_via_next_char`]'s match arm. 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 §VI.1 — generation over composition; the family-wide
    /// contract sweeps (alignment with
    /// [`Self::promote_via_next_char`], pairwise disjointness across
    /// the head-discriminator product, rendered-prefix composition
    /// identity) 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 a per-op-family
    /// `[(source_pattern, matcher, rewritten_op)]` static rewrite
    /// table at the closed-set boundary — the (source, matcher,
    /// target) triple axis becomes typed data on the IR algebra
    /// rather than dispatch tables scattered across per-pattern
    /// callsites. Translated through the substrate's [`QuoteForm`]
    /// closed-set marker, the reader's promotion rewrite table
    /// becomes ONE typed `[(head_variant, next_char, promoted_variant);
    /// N]` array on the algebra. Where MLIR's registry carries the
    /// rewrite table dynamically on the pattern applicator's runtime
    /// state, this substrate carries it statically as `pub const` on
    /// the closed-set marker — the pattern-matching evaluation lands
    /// at rustc-time through const-fn match arm binding to
    /// [`Self::PROMOTIONS`]`[i].2` rather than at runtime through a
    /// dynamic registry lookup.
    #[allow(dead_code)]
    pub(crate) const PROMOTIONS: [(Self, char, Self); 1] = [(
        Self::Unquote,
        Self::SPLICE_DISCRIMINATOR,
        Self::UnquoteSplice,
    )];

    /// Promotion table on the closed-set quote-family algebra —
    /// `Some(Self::UnquoteSplice)` iff `self == Self::Unquote &&
    /// next == Self::SPLICE_DISCRIMINATOR`, else `None`. Encodes the
    /// substrate's ONE (variant, next-char) → longer-variant mapping —
    /// `,` [`Self::Unquote`] followed by `@` [`Self::SPLICE_DISCRIMINATOR`]
    /// promotes to `,@` [`Self::UnquoteSplice`]. Every other pairing
    /// (including [`Self::Quote`] / [`Self::Quasiquote`] / [`Self::UnquoteSplice`]
    /// on ANY next-char, AND [`Self::Unquote`] on any non-discriminator
    /// next-char) yields `None` — the closed set of promotions is the
    /// singleton `{(Unquote, '@') → UnquoteSplice}` on the `Self × char
    /// → Option<Self>` product.
    ///
    /// Structural sibling of [`Self::from_lead_char`] one axis over on
    /// the same typed-entry family: [`Self::from_lead_char`] decodes
    /// ONE lead char to its DEFAULT variant on that char; this method
    /// decodes ONE (default variant, second char) pair to its PROMOTED
    /// variant. Together the two methods close the reader's outer
    /// quote-family entry surface onto the algebra: the tokenizer
    /// consumes ONE lead char through [`Self::from_lead_char`], then
    /// OPTIONALLY consumes one second char through this method — the
    /// (lead char, second char) → typed marker projection binds at TWO
    /// typed decodes rather than at inline `char`-literal patterns
    /// scattered across the outer-match dispatch arm.
    ///
    /// ONE consumer entrypoint the reader's `tokenize` binds against:
    /// the peek-then-consume `@` promotion inside the outer-match
    /// quote-family dispatch was pre-lift a hand-rolled inline check
    /// `matches!(qf_head, QuoteForm::Unquote) &&
    /// chars.peek().map(|&(_, c)| c) == Some('@')` paired with a
    /// per-branch `QuoteForm::UnquoteSplice` construction. The pairing
    /// was load-bearing yet only enforced by callsite discipline at a
    /// SEVENTH consumer site (alongside `Hash`, `Display`, `sexp_shape`,
    /// `wrap`, `iac_forge_tag`, `as_unquote_form`) the prior closed-set
    /// `QuoteForm` lifts did not reach. Post-lift the reader's peek
    /// arm routes through this method, so the (Unquote, '@') →
    /// UnquoteSplice promotion binds at ONE site on the typed algebra.
    /// A regression that drifts the promotion table (e.g. re-inlines
    /// `matches!(qf_head, QuoteForm::Quote)` at the peek arm and
    /// silently promotes bare `'` to a phantom variant) becomes a
    /// typed compile error against the `Option<Self>` return type.
    ///
    /// The single-promotion collapse (only `(Unquote, '@')` triggers)
    /// is INTENTIONAL: [`Self::UnquoteSplice`] is the ONLY variant with
    /// a two-char [`Self::prefix`], so the promotion table has exactly
    /// ONE `Some` arm and every other pairing rejects. Placing the
    /// promotion at the closed-set algebra rather than at the reader's
    /// peek arm keeps the streaming reader's two-char peek-then-consume
    /// shape at ONE site (the reader) while the (variant × second
    /// char) → promoted variant projection lives on the substrate
    /// algebra — parallel to the split that [`Self::from_lead_char`]
    /// closes for the one-char entry surface. This split parallels the
    /// reader's split of `Token::Str` into open-delimiter dispatch
    /// ([`crate::ast::Atom::STR_DELIMITER`]) AND inner-payload
    /// accumulation — the closed-set char algebra decodes the entry
    /// chars; the streaming reader handles the peek-and-consume
    /// follow-through.
    ///
    /// Composition identity: for every `qf: QuoteForm` and every
    /// `c: char`, if `qf.promote_via_next_char(c) == Some(promoted)`
    /// then `format!("{}{}", qf.prefix(), c) == promoted.prefix()`.
    /// Pinned by
    /// `quote_form_promote_via_next_char_composes_prefix_from_source_prefix_and_next_char`
    /// across the singleton promotion arm — the pin asserts the
    /// (variant, next char) → promoted-variant projection agrees with
    /// the reader's rendered [`Self::prefix`] composition, so a
    /// regression that drifts one side of the identity (a promotion
    /// arm rerouted through the wrong variant, or a prefix renamed
    /// without updating the promotion table) surfaces immediately.
    ///
    /// 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. THEORY.md §V.1 — knowable
    /// platform; the (variant, next char) → promoted variant table
    /// becomes a TYPE projection on the substrate algebra rather than
    /// at an inline `matches!(qf, Unquote) && c == '@'` pattern
    /// scattered at the reader's peek arm. THEORY.md §VI.1 —
    /// generation over composition; a fifth homoiconic prefix with its
    /// own two-char extension extends [`Self`] AND this method's match
    /// arm in lockstep — rustc binds the extension through
    /// exhaustiveness over the closed enum, and the `Option<Self>`
    /// return shape leaves the promotion table structurally open for
    /// future variants to append their own `Some` arms without
    /// touching the existing arms' semantics.
    ///
    /// Frontier inspiration: Racket's `read-syntax` two-char
    /// discriminator table (`(quote-abbrev-mapping char) → syntax`)
    /// that maps `(#\' → 'quote)`, `(#\` → 'quasiquote)`, `(#\, →
    /// 'unquote)`, `(#\, #\@) → 'unquote-splicing)` on the reader's
    /// typed abbreviation surface. Translated through the substrate's
    /// [`QuoteForm`] outer-marker algebra, the `(#\, #\@) → 'unquote-
    /// splicing)` two-char arm becomes ONE typed `(Self::Unquote, '@')
    /// → Some(Self::UnquoteSplice)` promotion on the closed-set
    /// algebra with rustc binding the promotion identity through
    /// exhaustiveness. Where Racket carries the promotion table
    /// dynamically on the reader's abbreviation-mapping parameter,
    /// this substrate carries it statically as `pub const fn` on the
    /// closed-set marker.
    #[must_use]
    pub const fn promote_via_next_char(self, next: char) -> Option<Self> {
        // The Some-arm's promoted-variant column routes through
        // `Self::PROMOTIONS[0].2` — the ONE promotion triple on the
        // closed-set algebra — so a regression that drifts the
        // promoted-variant column of the singleton triple silently
        // redirects every reader `,@` sequence to a phantom variant AND
        // fails the alignment pin
        // `quote_form_promotions_align_with_promote_via_next_char_for_every_entry`
        // at rustc / test time rather than at silent tokenizer drift.
        // The head-pattern (`Self::Unquote`) + discriminator-pattern
        // (`Self::SPLICE_DISCRIMINATOR`) arm literals stay inline
        // because patterns cannot be array-indexing expressions in the
        // current const-fn grammar; the alignment pin catches head /
        // discriminator column drift by construction.
        match (self, next) {
            (Self::Unquote, Self::SPLICE_DISCRIMINATOR) => Some(Self::PROMOTIONS[0].2),
            _ => None,
        }
    }

    /// Canonical `u8` cache-key byte for [`Self::Quote`]'s
    /// [`Self::hash_discriminator`] arm — `3`. ONE canonical byte on
    /// the closed-set [`QuoteForm`] algebra shared by
    /// [`Self::hash_discriminator`]'s [`Self::Quote`] arm AND every
    /// downstream consumer (the [`Hash for Sexp`](crate::ast::Sexp)
    /// cache-key body, the expansion cache
    /// (`crate::macro_expand::Expander::cache`) that keys on that hash).
    ///
    /// Sibling posture to the closed set of per-role `pub(crate) const`
    /// / `pub const` bytes on the substrate's other closed-set outer
    /// algebras: [`Self::QUOTE_PREFIX`] / [`Self::QUASIQUOTE_PREFIX`]
    /// / [`Self::UNQUOTE_PREFIX`] / [`Self::UNQUOTE_SPLICE_PREFIX`]
    /// (per-role reader-prefix `&'static str` algebra on the SAME
    /// [`QuoteForm`] closed set — commit a08e61f),
    /// [`Self::QUOTE_LABEL`] / [`Self::QUASIQUOTE_LABEL`] /
    /// [`Self::UNQUOTE_LABEL`] / [`Self::UNQUOTE_SPLICE_LABEL`] (per-
    /// role diagnostic-label `&'static str` algebra on the SAME closed
    /// set — commit 70be157), [`Self::QUOTE_IAC_FORGE_TAG`] /
    /// [`Self::QUASIQUOTE_IAC_FORGE_TAG`] / [`Self::UNQUOTE_IAC_FORGE_TAG`]
    /// / [`Self::UNQUOTE_SPLICE_IAC_FORGE_TAG`] (per-role iac-forge
    /// canonical-form tag `&'static str` algebra on the SAME closed set
    /// — commit bdd624b). This constant closes the FOURTH per-role
    /// axis on [`QuoteForm`] — the `u8` cache-key axis paired with the
    /// three pre-existing `&'static str` axes.
    ///
    /// The FOUR canonical bytes `{3, 4, 5, 6}` partition the outer-
    /// [`crate::ast::Sexp`] `Hash` body's quote-family arm-set against
    /// the reserved bytes the non-quote-family arms use (`0u8` for
    /// [`crate::error::StructuralKind::Nil`] via
    /// [`crate::error::StructuralKind::hash_discriminator`], `1u8` for
    /// [`crate::ast::Sexp::Atom`]'s outer-carve marker via the
    /// pre-existing inline `1u8` at [`Hash for Sexp`](crate::ast::Sexp)'s
    /// atom arm, `2u8` for [`crate::error::StructuralKind::List`] via
    /// [`crate::error::StructuralKind::hash_discriminator`]) — the
    /// three carvings of the outer-[`crate::ast::Sexp`] cache-key
    /// space jointly cover the `{0, 1, 2, 3, 4, 5, 6}` byte-set with
    /// no gaps AND no overlaps.
    ///
    /// A regression that inlines the `3` literal at
    /// [`Self::hash_discriminator`]'s [`Self::Quote`] arm and drifts
    /// the constant silently (e.g. a re-numbering that collides with
    /// the reserved `2u8` for [`crate::error::StructuralKind::List`],
    /// silently mis-hashing every cached expansion across the substrate)
    /// fails at the algebra's `hash_discriminator()` path-uniformity
    /// pin
    /// (`quote_form_hash_discriminator_routes_through_typed_per_role_constants`)
    /// rather than at silent cache-key drift where
    /// `crate::macro_expand::Expander::cache` mis-collides live
    /// expansions.
    ///
    /// `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::as_quote_form`],
    /// [`Self::prefix`], [`Self::as_unquote_form`]) don't already
    /// serve — same visibility rationale as [`Self::hash_discriminator`]
    /// itself.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 5 — composition
    /// preserves proofs; the alias-chain composition law
    /// `QuoteForm::HASH_DISCRIMINATORS[i] ==
    /// QuoteForm::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 four canonical
    /// cache-key bytes bind at ONE `pub(crate) const` per role on the
    /// typed algebra rather than as inline `u8` literals in the
    /// `hash_discriminator` match arms.
    pub(crate) const QUOTE_HASH_DISCRIMINATOR: u8 = 3;

    /// Canonical `u8` cache-key byte for [`Self::Quasiquote`]'s
    /// [`Self::hash_discriminator`] arm — `4`. Sibling of
    /// [`Self::QUOTE_HASH_DISCRIMINATOR`] on the closed-set per-role
    /// quote-family cache-key-byte axis; see
    /// [`Self::QUOTE_HASH_DISCRIMINATOR`] for the algebra-level round-
    /// trip + disjointness contracts every sibling shares.
    pub(crate) const QUASIQUOTE_HASH_DISCRIMINATOR: u8 = 4;

    /// Canonical `u8` cache-key byte for [`Self::Unquote`]'s
    /// [`Self::hash_discriminator`] arm — `5`. Sibling of
    /// [`Self::QUOTE_HASH_DISCRIMINATOR`] on the closed-set per-role
    /// quote-family cache-key-byte axis. Byte-for-byte distinct from
    /// [`Self::UNQUOTE_SPLICE_HASH_DISCRIMINATOR`] — the two template-
    /// substitution arms partition `{5, 6}` on the outer-Sexp cache-
    /// key space.
    pub(crate) const UNQUOTE_HASH_DISCRIMINATOR: u8 = 5;

    /// Canonical `u8` cache-key byte for [`Self::UnquoteSplice`]'s
    /// [`Self::hash_discriminator`] arm — `6`. Sibling of
    /// [`Self::QUOTE_HASH_DISCRIMINATOR`] on the closed-set per-role
    /// quote-family cache-key-byte axis. The HIGHEST byte on the
    /// closed set — a future fifth quote-family variant would extend
    /// the partition to `{3, 4, 5, 6, 7}` and land the new
    /// discriminator at `7u8`.
    pub(crate) const UNQUOTE_SPLICE_HASH_DISCRIMINATOR: u8 = 6;

    /// Closed-set forced-arity ALL array over the canonical cache-key
    /// `u8` bytes, in declaration order matching [`Self::ALL`] element-
    /// wise (pinned by `quote_form_hash_discriminators_align_with_all_by_index`).
    /// Sibling posture to [`Self::PREFIXES`] (`[&'static str; 4]` —
    /// the reader-prefix `&'static str` axis on the SAME closed set),
    /// [`Self::LABELS`] (`[&'static str; 4]` — the diagnostic-label
    /// `&'static str` axis), [`Self::IAC_FORGE_TAGS`] (`[&'static str;
    /// 4]` — the iac-forge canonical-form tag `&'static str` axis) —
    /// every closed-set outer projection on the substrate's
    /// [`QuoteForm`] algebra now pins its per-role canonical bytes at
    /// ONE `pub(crate) const` / `pub const` per role PLUS an ALL array
    /// for family-wide consumers, across ALL FOUR production
    /// vocabularies the closed set carries (reader prefix, diagnostic
    /// label, iac-forge canonical-form tag, outer-Sexp cache-key byte).
    ///
    /// Pre-lift the four cache-key bytes had NO per-role primitive on
    /// this closed-set algebra — a consumer with a [`QuoteForm`]
    /// variant in hand at compile time reaching for the canonical byte
    /// had to spell `QuoteForm::Unquote.hash_discriminator()` (runtime
    /// dispatch through the match arm) OR reach across into the inline
    /// `5u8` at the pre-lift match arm's [`Self::Unquote`] branch and
    /// re-derive the (variant, byte) pairing at the call site.
    /// Post-lift the FOUR canonical bytes bind at ONE `pub(crate) const`
    /// per role on the typed [`QuoteForm`] 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 that asserts every quote-family
    /// arm's discriminator disjoint from the reserved
    /// [`crate::ast::Sexp::Atom`] byte, a Sekiban audit-trail metric
    /// jointly labeled by the cache-key partition, a future
    /// `TypedRewriter<QuoteFormOp>` sweep zipping ALL / PREFIXES /
    /// LABELS / IAC_FORGE_TAGS / HASH_DISCRIMINATORS in lockstep for a
    /// family-wide (variant, four-vocabulary quadruple) render) reads
    /// through the typed constants without re-deriving the four-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
    /// `quote_form_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 AND mis-
    /// collides with the reserved bytes the non-quote-family arms use,
    /// fails-loudly at the alias test rather than at a silent
    /// [`crate::macro_expand::Expander::cache`] mis-hash. Adding a
    /// hypothetical fifth homoiconic prefix (a `,~` reverse-unquote, a
    /// `,?` conditional-unquote) 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).
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the four
    /// canonical cache-key bytes bind at ONE typed `[u8; 4]` array on
    /// the closed-set [`QuoteForm`] algebra rather than at zero-
    /// primitive-plus-four-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 `intent_hash` composition axis for
    /// every quote-family arm — binding the four 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
    /// four 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 is deliberate: 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 quote-family byte-set upfront, a future `tatara-check`
    /// predicate `(check-cache-key-partition-disjoint …)` that
    /// verifies the `{3, 4, 5, 6}` partition against the reserved
    /// `{0, 1, 2}` bytes structurally, a future
    /// `TypedRewriter<QuoteFormOp>` sweep zipping ALL / PREFIXES /
    /// LABELS / IAC_FORGE_TAGS / HASH_DISCRIMINATORS in lockstep for a
    /// family-wide (variant, four-vocabulary quadruple) render) bind
    /// to ONE `[u8; 4]` primitive rather than re-deriving the array
    /// inline per callsite. Matches the preemptive-primitive posture
    /// the prior-run [`crate::error::UnquoteForm::hash_discriminator`]
    /// lift carried before its downstream consumers materialized.
    #[allow(dead_code)]
    pub(crate) const HASH_DISCRIMINATORS: [u8; 4] = [
        Self::QUOTE_HASH_DISCRIMINATOR,
        Self::QUASIQUOTE_HASH_DISCRIMINATOR,
        Self::UNQUOTE_HASH_DISCRIMINATOR,
        Self::UNQUOTE_SPLICE_HASH_DISCRIMINATOR,
    ];

    /// Stable, per-variant byte discriminator that paired with the
    /// recursive inner hash builds the substrate's `Hash for Sexp`
    /// projection — `3` for [`Self::Quote`], `4` for
    /// [`Self::Quasiquote`], `5` for [`Self::Unquote`], `6` for
    /// [`Self::UnquoteSplice`]. The byte values are load-bearing
    /// because the expansion cache (`Expander::cache`) keys on the
    /// hash of `(macro_name, args)` — changing a discriminator silently
    /// invalidates every cached expansion AND mis-collides with the
    /// reserved bytes the non-quote-family Hash arms use (`0` for
    /// `Nil`, `1` for `Atom`, `2` for `List`). The closed set ensures
    /// the four arms partition `{3, 4, 5, 6}` injectively against the
    /// reserved bytes — a future quote-family extension must extend
    /// this method AND the non-quote-family arms in lockstep, with
    /// rustc binding the consistency through exhaustiveness over the
    /// closed enum.
    ///
    /// Post-lift the four arms route through the per-role
    /// `pub(crate) const` bytes on the closed-set [`QuoteForm`]
    /// algebra ([`Self::QUOTE_HASH_DISCRIMINATOR`],
    /// [`Self::QUASIQUOTE_HASH_DISCRIMINATOR`],
    /// [`Self::UNQUOTE_HASH_DISCRIMINATOR`],
    /// [`Self::UNQUOTE_SPLICE_HASH_DISCRIMINATOR`]) rather than
    /// inline `u8` literals — so a re-numbering that would silently
    /// invalidate every cached expansion lands as ONE edit to the
    /// matching `pub(crate) const` rather than at four scattered
    /// arm-literals. Every downstream consumer that binds to the
    /// algebra ([`Hash for Sexp`](crate::ast::Sexp)'s outer sweep,
    /// the [`crate::macro_expand::Expander::cache`] cache-key
    /// composition, the future coverage-tool sweeps) inherits the
    /// rename mechanically.
    ///
    /// `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 (`Sexp::as_quote_form`, `Self::prefix`,
    /// `Self::as_unquote_form`) don't already serve.
    #[must_use]
    pub(crate) fn hash_discriminator(self) -> u8 {
        match self {
            Self::Quote => Self::QUOTE_HASH_DISCRIMINATOR,
            Self::Quasiquote => Self::QUASIQUOTE_HASH_DISCRIMINATOR,
            Self::Unquote => Self::UNQUOTE_HASH_DISCRIMINATOR,
            Self::UnquoteSplice => Self::UNQUOTE_SPLICE_HASH_DISCRIMINATOR,
        }
    }

    /// Project the 4-of-4 quote-family marker into the 2-of-4
    /// template-substitution subset — `Some(UnquoteForm::Unquote)` for
    /// [`Self::Unquote`], `Some(UnquoteForm::Splice)` for
    /// [`Self::UnquoteSplice`], `None` for [`Self::Quote`] /
    /// [`Self::Quasiquote`] (the literal-quote and quasi-quote
    /// prefixes are wrappers, NOT substitution points). ONE projection
    /// on this algebra the [`crate::ast::Sexp::as_unquote`] derivation
    /// routes through — the (Sexp variant, UnquoteForm marker) pairing
    /// now binds at the typed [`crate::ast::Sexp::as_quote_form`]
    /// projection's output composed with this method's output, instead
    /// of being re-derived per-arm inside `Sexp::as_unquote`.
    ///
    /// The closed-set guarantee on [`UnquoteForm`] (exactly
    /// `Unquote ⊎ Splice`) AND on [`Self`] (exactly
    /// `Quote ⊎ Quasiquote ⊎ Unquote ⊎ UnquoteSplice`) ensures that the
    /// 2-of-4 subset is structurally fixed: a future variant joining
    /// the template-substitution surface extends both enums AND this
    /// method's match arm together, with rustc binding the extension
    /// through the projection's `Option` return type.
    #[must_use]
    pub fn as_unquote_form(self) -> Option<UnquoteForm> {
        match self {
            Self::Unquote => Some(UnquoteForm::Unquote),
            Self::UnquoteSplice => Some(UnquoteForm::Splice),
            Self::Quote | Self::Quasiquote => None,
        }
    }

    /// Canonical `&'static str` iac-forge canonical-form tag of
    /// [`Self::Quote`] — `"quote"`. The ONE canonical bytes-payload on
    /// the closed-set [`QuoteForm`] algebra shared by [`Self::iac_forge_tag`]'s
    /// [`Self::Quote`] arm AND the `crate::interop` (removed) `From<&Sexp> for
    /// iac_forge::sexpr::SExpr` arm the projection feeds.
    ///
    /// Sibling posture to the closed set of per-role `pub const` bytes
    /// on the substrate's other closed-set outer algebras:
    /// [`Self::QUOTE_PREFIX`] / [`Self::QUASIQUOTE_PREFIX`] /
    /// [`Self::UNQUOTE_PREFIX`] / [`Self::UNQUOTE_SPLICE_PREFIX`] (per-
    /// role reader-prefix algebra on the SAME [`QuoteForm`] closed set),
    /// [`crate::error::MacroDefHead::DEFMACRO_KEYWORD`] /
    /// [`crate::error::MacroDefHead::DEFPOINT_TEMPLATE_KEYWORD`] /
    /// [`crate::error::MacroDefHead::DEFCHECK_KEYWORD`] (per-role
    /// head-keyword algebra on the CL macro-definition surface),
    /// [`Atom::TRUE_LITERAL`] / [`Atom::FALSE_LITERAL`] (per-role
    /// Scheme-bool spelling algebra on the atomic-payload surface).
    ///
    /// The (canonical iac-forge tag) axis lives ORTHOGONAL to the
    /// (canonical reader prefix) axis: `Self::QUOTE_PREFIX` (`"'"`) and
    /// `Self::QUOTE_IAC_FORGE_TAG` (`"quote"`) both project the same
    /// variant but through two distinct byte vocabularies — the reader
    /// axis for the Lisp source-code surface, the iac-forge axis for
    /// the cross-crate canonical-form surface (BLAKE3 attestation,
    /// render cache). A regression that inlines the `"quote"` literal
    /// at [`Self::iac_forge_tag`]'s [`Self::Quote`] arm and drifts the
    /// constant silently (e.g. a hypothetical rename to `"literal-quote"`
    /// on the iac-forge side while leaving the prefix `"'"` intact)
    /// fails at the algebra's `iac_forge_tag()` path-uniformity pin
    /// (`quote_form_iac_forge_tag_routes_through_typed_per_role_constants`)
    /// rather than at silent canonical-form drift where downstream
    /// BLAKE3 attestation keys silently mis-hash.
    pub const QUOTE_IAC_FORGE_TAG: &'static str = "quote";

    /// Canonical `&'static str` iac-forge canonical-form tag of
    /// [`Self::Quasiquote`] — `"quasiquote"`. Sibling of
    /// [`Self::QUOTE_IAC_FORGE_TAG`] on the closed-set per-role
    /// quote-family iac-forge tag-bytes axis; see
    /// [`Self::QUOTE_IAC_FORGE_TAG`] for the algebra-level round-trip +
    /// disjointness contracts every sibling shares.
    pub const QUASIQUOTE_IAC_FORGE_TAG: &'static str = "quasiquote";

    /// Canonical `&'static str` iac-forge canonical-form tag of
    /// [`Self::Unquote`] — `"unquote"`. Sibling of
    /// [`Self::QUOTE_IAC_FORGE_TAG`] on the closed-set per-role
    /// quote-family iac-forge tag-bytes axis.
    ///
    /// Byte-identical to the substrate's shorter diagnostic label
    /// [`crate::error::SexpShape::Unquote`]'s label projection
    /// (`SexpShape::label` returns `"unquote"` for this variant) — the
    /// two projections happen to agree on this variant's bytes but
    /// live at distinct algebraic layers (iac-forge canonical form vs
    /// substrate diagnostic surface); the divergence is load-bearing on
    /// the [`Self::UnquoteSplice`] arm (`"unquote-splicing"` vs
    /// `"unquote-splice"`) and this byte-level agreement here does not
    /// license a consolidation of the two axes. Pinned by
    /// `quote_form_iac_forge_tag_diverges_from_sexp_shape_label_for_unquote_splice`.
    pub const UNQUOTE_IAC_FORGE_TAG: &'static str = "unquote";

    /// Canonical `&'static str` iac-forge canonical-form tag of
    /// [`Self::UnquoteSplice`] — `"unquote-splicing"`. The Common-Lisp-
    /// canonical spelling: a `,@x` form encodes as `(unquote-splicing x)`
    /// rather than `(unquote-splice x)`. That tag-string choice is
    /// INTENTIONALLY DISTINCT from the substrate's shorter diagnostic
    /// label projected by [`crate::error::SexpShape::label`] (which
    /// renders `[`Self::UnquoteSplice`]` as `"unquote-splice"` — the
    /// shorter idiom appropriate for `expected …, got unquote-splice`
    /// error surfaces). The two projections key the SAME closed set on
    /// TWO distinct boundaries — pinning the divergence at the typed
    /// per-role `pub const` documents the intent structurally: a
    /// future "consolidation" PR that homogenizes them would have to
    /// touch this constant explicitly, surfacing the boundary-distinct
    /// invariant at code-review time rather than silently.
    ///
    /// Sibling of [`Self::QUOTE_IAC_FORGE_TAG`] on the closed-set
    /// per-role quote-family iac-forge tag-bytes axis. The ONLY entry
    /// on this axis whose bytes disagree with the peer-axis
    /// [`crate::error::SexpShape::label`] projection — pinned by
    /// `quote_form_iac_forge_tag_diverges_from_sexp_shape_label_for_unquote_splice`
    /// alongside the three matched-arm agreements.
    pub const UNQUOTE_SPLICE_IAC_FORGE_TAG: &'static str = "unquote-splicing";

    /// The closed-set forced-arity ALL array over the quote-family
    /// iac-forge canonical-form tag `&'static str` bytes in canonical
    /// declaration order matching [`Self::ALL`] element-wise. Sibling
    /// posture to [`Self::PREFIXES`] (`[&'static str; 4]` on the
    /// reader-prefix axis of the SAME [`QuoteForm`] closed set),
    /// [`crate::error::MacroDefHead::KEYWORDS`] (`[&'static str; 3]`
    /// on the CL macro-definition head algebra),
    /// [`Atom::BOOL_LITERALS`] (`[&'static str; 2]` on the Scheme-bool
    /// spelling algebra), and
    /// [`crate::macro_expand::MacroParams::LAMBDA_LIST_KEYWORDS`]
    /// (`[&'static str; 2]` on the CL lambda-list-keyword algebra) —
    /// every closed-set outer projection on the substrate now pins its
    /// canonical bytes at ONE `pub const` per role plus an ALL array
    /// for family-wide consumers.
    ///
    /// The (canonical iac-forge tag) axis + the (canonical reader
    /// prefix) axis together span the two production byte-vocabularies
    /// the [`QuoteForm`] closed set carries — [`Self::PREFIXES`] holds
    /// the Lisp source-code prefixes (`"'"`, `` "`" ``, `","`, `",@"`)
    /// the reader tokenizes on, [`Self::IAC_FORGE_TAGS`] holds the
    /// cross-crate canonical-form tag strings (`"quote"`,
    /// `"quasiquote"`, `"unquote"`, `"unquote-splicing"`) the
    /// iac-forge interop layer round-trips through. Adding a
    /// hypothetical fifth homoiconic prefix (a `,~` reverse-unquote, a
    /// `,?` conditional-unquote, a `#'` Common-Lisp function-quote)
    /// extends [`Self::ALL`] AND [`Self::PREFIXES`] AND
    /// [`Self::IAC_FORGE_TAGS`] AND [`Self::prefix`]'s arm AND
    /// [`Self::iac_forge_tag`]'s arm AND two new per-role `pub const`s
    /// (one on each axis) in lockstep — rustc's forced-arity check on
    /// `[&'static str; N]` fails compilation if any of the three ALL
    /// arrays grows without the others.
    ///
    /// Future consumers that compose against [`Self::IAC_FORGE_TAGS`]:
    /// - Cross-crate canonical-form completion (an authoring tool
    ///   surfacing every legal iac-forge tag in a `(<tag> <inner>)`
    ///   template — the completion set IS [`Self::IAC_FORGE_TAGS`]
    ///   rather than four hand-enumerated `&'static str` literals per
    ///   completion provider).
    /// - `tatara-check` coverage assertions that sweep workspace
    ///   attestation payloads for every canonical iac-forge tag —
    ///   the typed sweep replaces per-consumer inline enumeration of
    ///   the four literals.
    /// - Any future audit-trail metric jointly labeled by
    ///   [`Self::iac_forge_tag`] (e.g.
    ///   `tatara_lisp_iac_forge_tag_total{tag="quote"}`) — the metric
    ///   label set IS [`Self::IAC_FORGE_TAGS`] mapped through
    ///   [`Self::iac_forge_tag`].
    pub const IAC_FORGE_TAGS: [&'static str; 4] = [
        Self::QUOTE_IAC_FORGE_TAG,
        Self::QUASIQUOTE_IAC_FORGE_TAG,
        Self::UNQUOTE_IAC_FORGE_TAG,
        Self::UNQUOTE_SPLICE_IAC_FORGE_TAG,
    ];

    /// Canonical iac-forge interop tag — the symbol head the canonical
    /// 2-element-list encoding of a quote-family wrapper uses when
    /// projecting `tatara_lisp::Sexp` into `iac_forge::sexpr::SExpr`:
    /// `"quote"` for [`Self::Quote`], `"quasiquote"` for
    /// [`Self::Quasiquote`], `"unquote"` for [`Self::Unquote`],
    /// `"unquote-splicing"` for [`Self::UnquoteSplice`].
    ///
    /// The mapping is Common-Lisp-canonical: a `,@x` form encodes as
    /// `(unquote-splicing x)` rather than `(unquote-splice x)`. That
    /// tag-string choice is INTENTIONALLY DISTINCT from the substrate's
    /// shorter diagnostic label projected by
    /// [`crate::error::SexpShape::label`] (which renders
    /// `[`Self::UnquoteSplice`]` as `"unquote-splice"` — the shorter
    /// idiom appropriate for `expected …, got unquote-splice` error
    /// surfaces). The two projections key the SAME closed set on TWO
    /// distinct boundaries:
    ///
    /// * `iac_forge_tag` — cross-crate canonical form, BLAKE3 attestation
    ///   keys, render-cache shape (load-bearing for byte-identical
    ///   inter-crate compatibility with the iac-forge ecosystem).
    /// * `SexpShape::label` — operator-facing diagnostic label,
    ///   `LispError::TypeMismatch.got` rendering, REPL/LSP
    ///   shape-of-witness surface.
    ///
    /// Pre-lift the four canonical iac-forge tag strings lived inline
    /// across four arms in `crate::interop` (removed)'s
    /// `From<&Sexp> for iac_forge::sexpr::SExpr` impl, paired with the
    /// matching `Sexp::{Quote, Quasiquote, Unquote, UnquoteSplice}`
    /// patterns. The pairing was load-bearing yet only enforced by
    /// callsite discipline at a FOURTH consumer site (alongside `Hash`,
    /// `Display`, and `Sexp::as_unquote`) the prior closed-set
    /// `QuoteForm` lift did not reach (the `iac-forge` feature gate
    /// kept that site's drift risk silent in the default build). After
    /// this lift the interop arms collapse to ONE arm routing through
    /// [`crate::ast::Sexp::as_quote_form`] + this method, so the
    /// (Sexp variant, canonical tag string) pairing binds at ONE site
    /// on the substrate algebra regardless of which consumer surface
    /// (`Hash`, `Display`, `Sexp::as_unquote`, iac-forge interop)
    /// needs it.
    ///
    /// 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
    /// [`Self::prefix`], [`UnquoteForm::marker`], and
    /// [`crate::error::SexpShape::label`] project their respective
    /// closed-set surfaces. A future homoiconic prefix-wrapper (e.g.
    /// hypothetical `,~` reverse-unquote) extends [`Self`] AND this
    /// method's match arm together — rustc binds the iac-forge
    /// canonical-form surface to the algebra through exhaustiveness.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the
    /// quote-family canonical-form tag set becomes a TYPE projection
    /// on the substrate algebra rather than four `&'static str`
    /// literals scattered across the `interop` arms (parallel to how
    /// `Self::prefix` lifts the Display↔reader prefix and
    /// `Self::hash_discriminator` lifts the cache-key bytes).
    /// THEORY.md §VI.1 — generation over composition; the (Sexp
    /// variant, iac-forge tag) pairing appeared at the four
    /// `interop.rs` arms — past the ≥2 PRIME-DIRECTIVE trigger once
    /// the structural shape is named. THEORY.md §II.1 invariant 1 —
    /// typed entry; the cross-crate canonical-form projection IS the
    /// typed-exit gate at the iac-forge boundary, and naming its
    /// closed-set tag identity lifts the gate from per-site literal
    /// discipline to ONE method the iac-forge round-trip discipline
    /// binds against.
    #[must_use]
    pub fn iac_forge_tag(self) -> &'static str {
        match self {
            Self::Quote => Self::QUOTE_IAC_FORGE_TAG,
            Self::Quasiquote => Self::QUASIQUOTE_IAC_FORGE_TAG,
            Self::Unquote => Self::UNQUOTE_IAC_FORGE_TAG,
            Self::UnquoteSplice => Self::UNQUOTE_SPLICE_IAC_FORGE_TAG,
        }
    }

    /// Inverse of [`Self::iac_forge_tag`] on the four-arm canonical CL
    /// tag closed set — `"quote"` decodes to `Some(Self::Quote)`,
    /// `"quasiquote"` decodes to `Some(Self::Quasiquote)`, `"unquote"`
    /// decodes to `Some(Self::Unquote)`, `"unquote-splicing"` decodes to
    /// `Some(Self::UnquoteSplice)`. Every other `tag` (empty string,
    /// PascalCase drift, the shorter substrate diagnostic label
    /// `"unquote-splice"` — which is INTENTIONALLY distinct from the
    /// CL canonical `"unquote-splicing"` per the substrate's
    /// two-vocabulary axis pinned by
    /// `quote_form_iac_forge_tag_diverges_from_sexp_shape_label_for_unquote_splice`,
    /// every arbitrary word not in the four-arm image) yields `None`.
    ///
    /// Structural roundtrip law (pinned by
    /// `quote_form_iac_forge_tag_round_trips_through_from_iac_forge_tag`):
    /// for every `qf: QuoteForm`,
    /// `Self::from_iac_forge_tag(qf.iac_forge_tag()) == Some(qf)`.
    /// Sibling posture to [`Self::from_lead_char`]'s inverse-of-
    /// [`Self::lead_char`] contract on the reader-lead-char axis —
    /// both name the typed inverse decoder on a per-role projection
    /// axis of the same closed set, with `Option<Self>` shape mirroring
    /// the partial decode over an unbounded string codomain into the
    /// four-arm typed closed set.
    ///
    /// Load-bearing use case: cross-crate iac-forge canonical-form
    /// inbound decoding. Pre-lift a consumer parsing a canonical
    /// `(<tag> <inner>)` list from an `iac_forge::sexpr::SExpr` (a
    /// downstream deserialization codepath, an LSP quick-fix that
    /// completes an iac-forge canonical-form skeleton, a
    /// `tatara-check` predicate that reads back an attested
    /// canonical form and re-typed-witnesses its shape) would have
    /// to hand-roll `match tag { "quote" => QuoteForm::Quote,
    /// "quasiquote" => …, "unquote-splicing" => …, _ => return None
    /// }` at each callsite; post-lift the (tag, typed variant)
    /// decode binds at ONE typed method on the substrate algebra
    /// composed as a linear sweep over [`Self::ALL`] keyed on
    /// [`Self::iac_forge_tag`]. The (tag literals, decode arms)
    /// pairing lives at ONE canonical site (the four
    /// [`Self::QUOTE_IAC_FORGE_TAG`] / [`Self::QUASIQUOTE_IAC_FORGE_TAG`]
    /// / [`Self::UNQUOTE_IAC_FORGE_TAG`] /
    /// [`Self::UNQUOTE_SPLICE_IAC_FORGE_TAG`] per-role constants
    /// [`Self::iac_forge_tag`]'s outbound arms bind to) rather than
    /// at TWO — the outbound projection (existing) plus a hand-rolled
    /// inbound decoder duplicated per callsite.
    ///
    /// Boundary distinction with [`Self::from_str`] (the substrate's
    /// [`FromStr`] impl derived via `#[closed_set(via = "prefix")]`):
    /// [`Self::from_str`] decodes the reader-punctuation vocabulary
    /// (`"'"`, `` "`" ``, `","`, `",@"`); THIS method decodes the
    /// cross-crate iac-forge canonical-form vocabulary (`"quote"`,
    /// `"quasiquote"`, `"unquote"`, `"unquote-splicing"`). The two
    /// closed-set inverse decoders key the SAME four-arm outer set
    /// through TWO orthogonal byte vocabularies — pinning them at
    /// distinct methods documents the axis-orthogonality
    /// [`Self::PREFIXES`] vs [`Self::IAC_FORGE_TAGS`] carries at the
    /// per-role forced-arity ALL array level. A consumer with a
    /// reader-punctuation byte in hand routes through [`FromStr`];
    /// a consumer with an iac-forge canonical tag in hand routes
    /// through THIS method — the vocabulary axis binds at the
    /// decoder-method boundary rather than at per-consumer inline
    /// dispatch.
    ///
    /// Case-sensitive by design — matches the case-sensitive
    /// [`FromStr`] posture (which decodes reader punctuation) and
    /// every other closed-set FromStr on the substrate. Non-const
    /// because `&str` equality is not const-evaluable on stable at
    /// substrate MSRV (parallel to how [`Self::FromStr`]'s decode
    /// body is non-const while [`Self::from_lead_char`] is
    /// `const fn` because `char` equality IS const-evaluable);
    /// callers that need a decode-at-compile-time surface stay on
    /// the reader-lead-char decoder.
    ///
    /// Post-lift the (iac-forge tag, typed variant) inverse decoder
    /// closes the FIFTH inverse-projection axis on the outer-`QuoteForm`
    /// algebra alongside [`Self::from_lead_char`] (the reader-lead-char
    /// axis inverse), [`Self::FromStr`] (the reader-prefix axis
    /// inverse, derived via `#[closed_set(via = "prefix")]`),
    /// [`crate::error::SexpShape::as_quote_form`] (the outer-shape
    /// carving inverse embedding), and
    /// [`crate::error::UnquoteForm::to_quote_form`] (the
    /// substitution-subset embedding inverse). The full outer
    /// quote-family algebra now closes ALL FIVE inverse-projection
    /// axes matched with their forward-projection siblings
    /// ([`Self::lead_char`] / [`Self::prefix`] / [`Self::sexp_shape`]
    /// / [`Self::as_unquote_form`] on the forward side).
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 3 — typed exit; the
    /// inbound iac-forge canonical-form decode surface becomes a
    /// TYPE projection on the closed-set [`QuoteForm`] algebra
    /// rather than an inline match at every downstream consumer.
    /// THEORY.md §V.1 — knowable platform; the closed set of
    /// canonical CL tags becomes a decoder codomain rather than
    /// four inline `&'static str` literals scattered across future
    /// consumers that could drift independently. THEORY.md §VI.1 —
    /// generation over composition; the (tag, typed variant)
    /// pairing decodes at ONE typed method on the algebra composed
    /// from the pre-existing [`Self::ALL`] typed set and the
    /// [`Self::iac_forge_tag`] outbound projection — no new
    /// per-role primitive, the decode is a typed CONSEQUENCE of
    /// the existing family-wide primitives. Sibling posture to
    /// [`Self::from_lead_char`] which similarly composes as an
    /// inverse over [`Self::lead_char`] without introducing a new
    /// per-role primitive.
    ///
    /// Frontier inspiration: MLIR's typed-attribute
    /// `parseType(str) -> Optional<Type>` factory on the closed-set
    /// typed-attribute registry — the same inverse-decode shape on
    /// a Rust closed-set enum, where the (tag, typed variant)
    /// decode binds at ONE typed factory rather than at every
    /// downstream operation's parseAttribute callback. Racket's
    /// `(assq tag tag-alist)` typed lookup over a closed
    /// association list — the inverse decode projects through the
    /// ALL array without hand-rolling a per-tag match; `Self::ALL
    /// .iter().find(qf.iac_forge_tag() == tag)` is the Rust-typed
    /// peer on the closed-set outer-[`QuoteForm`] algebra with the
    /// ALL array standing in for Racket's typed association-list
    /// spine.
    #[must_use]
    pub fn from_iac_forge_tag(tag: &str) -> Option<Self> {
        Self::ALL
            .iter()
            .copied()
            .find(|qf| qf.iac_forge_tag() == tag)
    }

    /// Project the typed marker into its matching [`crate::error::SexpShape`]
    /// variant — `Quote → SexpShape::Quote`, `Quasiquote → SexpShape::Quasiquote`,
    /// `Unquote → SexpShape::Unquote`, `UnquoteSplice → SexpShape::UnquoteSplice`.
    /// ONE projection on the closed-set quote-family algebra the substrate's
    /// outer-shape projection ([`crate::domain::sexp_shape`]) routes through
    /// for the four quote-family arms — so the (Sexp variant, SexpShape
    /// variant) pairing binds at ONE site on the typed algebra rather than
    /// at four byte-identical inline arms in [`crate::domain::sexp_shape`].
    ///
    /// The SIXTH consumer of the closed-set [`QuoteForm`] algebra, sibling
    /// of [`Self::prefix`] (Display / reader prefix-string surface),
    /// [`Self::hash_discriminator`] (Hash cache-key bytes surface),
    /// [`Self::as_unquote_form`] (2-of-4 template-substitution subset gate),
    /// [`Self::iac_forge_tag`] (cross-crate canonical-form tag surface), and
    /// [`Self::wrap`] (reader's marker → `Sexp::*` constructor surface).
    /// Composes with [`SexpShape::label`] to yield the short diagnostic
    /// label string the substrate's `LispError::TypeMismatch.got` slot
    /// renders — the (QuoteForm variant, SexpShape variant, short label)
    /// triple binds end-to-end through the typed algebra so a regression
    /// that drifts the short label silently between the typed marker and
    /// the diagnostic surface is structurally impossible.
    ///
    /// Bidirectional dual: the inverse projection
    /// [`crate::error::SexpShape::as_quote_form`] (12→4, partial)
    /// covers the 4-of-12 carving of [`SexpShape`] this embed reaches.
    /// The pair `(QuoteForm::sexp_shape,
    /// SexpShape::as_quote_form)` forms an `Iso(QuoteForm, QuoteShape ⊂
    /// SexpShape)`: every typed marker round-trips through the embed
    /// (`QuoteForm::sexp_shape(qf).as_quote_form() == Some(qf)` for
    /// every `qf: QuoteForm`), every quote-shape pre-image recovers
    /// the typed marker. The non-quote-family shapes (`Nil`, `List`,
    /// every atomic-payload variant) form the kernel of the inverse —
    /// `as_quote_form` returns `None` for them. See
    /// [`crate::error::SexpShape::as_quote_form`]'s docstring for the
    /// composition law's other direction + disjointness with the
    /// atomic-payload sibling `SexpShape::as_atom_kind`.
    ///
    /// Canonical [`SexpShape`] embed target for the [`Self::Quote`]
    /// quote-family arm on the QuoteForm ⊂ SexpShape carving —
    /// [`SexpShape::Quote`]. Per-role peer of `Self::Quote` on the
    /// closed-set outer-shape embed axis; consumers with a `QuoteForm`
    /// 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
    /// QuoteForm ⊂ SexpShape variant pairing inline.
    ///
    /// Sibling posture to [`Self::QUOTE_LABEL`] (the per-role
    /// diagnostic label alias) and [`Self::QUOTE_HASH_DISCRIMINATOR`]
    /// (the per-role outer-Sexp cache-key byte) on the closed-set
    /// QuoteForm algebra — each closes a distinct per-role
    /// sub-vocabulary axis on the QuoteForm carving. This constant
    /// closes the FOURTH per-role axis on [`QuoteForm`] (the
    /// `SexpShape`-embed axis, paired with the pre-existing
    /// `&'static str` reader-prefix + diagnostic-label +
    /// cross-crate iac-forge-tag axes AND 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 ([`AtomKind::SYMBOL_SHAPE`] …
    /// [`AtomKind::BOOL_SHAPE`] — every one an alias of its
    /// [`SexpShape`] peer on the AtomKind ⊂ SexpShape 6-of-12
    /// carving). 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)` — first `AtomKind` (6),
    /// now `QuoteForm` (4).
    pub const QUOTE_SHAPE: SexpShape = SexpShape::Quote;

    /// Canonical [`SexpShape`] embed target for the [`Self::Quasiquote`]
    /// quote-family arm on the QuoteForm ⊂ SexpShape carving —
    /// [`SexpShape::Quasiquote`]. Per-role peer of `Self::Quasiquote`.
    /// See [`Self::QUOTE_SHAPE`] for the alias-chain shape every
    /// sibling shares.
    pub const QUASIQUOTE_SHAPE: SexpShape = SexpShape::Quasiquote;

    /// Canonical [`SexpShape`] embed target for the [`Self::Unquote`]
    /// quote-family arm on the QuoteForm ⊂ SexpShape carving —
    /// [`SexpShape::Unquote`]. Per-role peer of `Self::Unquote`.
    pub const UNQUOTE_SHAPE: SexpShape = SexpShape::Unquote;

    /// Canonical [`SexpShape`] embed target for the [`Self::UnquoteSplice`]
    /// quote-family arm on the QuoteForm ⊂ SexpShape carving —
    /// [`SexpShape::UnquoteSplice`]. Per-role peer of
    /// `Self::UnquoteSplice`.
    pub const UNQUOTE_SPLICE_SHAPE: SexpShape = SexpShape::UnquoteSplice;

    /// Closed-set forced-arity ALL array over the canonical
    /// [`SexpShape`] embed targets on the QuoteForm ⊂ SexpShape
    /// 4-of-12 carving, in declaration order matching [`Self::ALL`]
    /// element-wise (pinned by
    /// `quote_form_shapes_align_with_all_by_index`). Sibling posture
    /// to [`Self::LABELS`] (`[&'static str; 4]` — per-role diagnostic
    /// bytes), [`Self::PREFIXES`] (`[&'static str; 4]` — per-role
    /// reader-punctuation bytes), [`Self::IAC_FORGE_TAGS`] (`[&'static
    /// str; 4]` — cross-crate iac-forge canonical-form tag bytes), and
    /// [`Self::HASH_DISCRIMINATORS`] (`[u8; 4]` — per-role outer-Sexp
    /// cache-key bytes) on the SAME closed-set QuoteForm algebra;
    /// where those four 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
    /// `[_; 4]` forced arity.
    ///
    /// Sibling posture to [`AtomKind::SHAPES`] (`[SexpShape; 6]`) —
    /// the peer atomic-payload carving's family-wide embed-target
    /// array on the AtomKind ⊂ SexpShape 6-of-12 carving. Together the
    /// two `SHAPES` arrays cover the TWO bidirectional sub-carvings of
    /// [`SexpShape`] (`Iso(AtomKind, AtomShape ⊂ SexpShape)` + `Iso(QuoteForm,
    /// QuoteShape ⊂ SexpShape)`) — a family-wide sweep zipping every
    /// carving's `ALL` + `SHAPES` in lockstep now closes over TWO
    /// carvings' 10-of-12 embed targets at ONE typed pair-of-arrays
    /// each.
    ///
    /// Pre-lift the four [`SexpShape`] embed targets had NO per-role
    /// primitive on this closed-set algebra — a consumer with a
    /// `QuoteForm` variant in hand at compile time reaching for the
    /// canonical embed target had to spell
    /// `QuoteForm::Quote.sexp_shape()` (runtime dispatch through the
    /// four-arm match body) OR re-derive the QuoteForm ⊂ SexpShape
    /// variant pairing at the call site by importing both enums and
    /// spelling `SexpShape::Quote` inline. Post-lift the FOUR canonical
    /// embed targets bind at ONE `pub const` per role on the typed
    /// [`QuoteForm`] algebra AND at [`Self::SHAPES`] as a family-wide
    /// forced-arity array — a future LSP / REPL completion bar keyed
    /// on `QuoteForm::SHAPES` for the "which SexpShape does this
    /// QuoteForm embed into?" outer-shape column, a `tatara-check`
    /// coverage sweep zipping `QuoteForm::ALL` / `LABELS` / `PREFIXES`
    /// / `IAC_FORGE_TAGS` / `HASH_DISCRIMINATORS` / `SHAPES` in
    /// lockstep for a family-wide (variant, label, prefix, iac-forge
    /// tag, byte, embed-target) sextuple 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 4-of-12 carving inline.
    ///
    /// Round-trip identity with the inverse projection
    /// [`crate::error::SexpShape::as_quote_form`]: for every index `i`,
    /// `Self::SHAPES[i].as_quote_form() == Some(Self::ALL[i])`
    /// (pinned by
    /// `quote_form_shapes_align_with_all_by_index_through_as_quote_form`) —
    /// the embed / project section closes as a family-wide array-
    /// indexed law rather than as a per-variant assertion sweep.
    /// Adding a hypothetical fifth quote-family wrapper (e.g. `,~`
    /// reverse-unquote, `,?` conditional-unquote, `#'` Common-Lisp
    /// function-quote) 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_quote_form`] arm must grow
    /// in lockstep to preserve the round-trip identity.
    ///
    /// Theory anchor: THEORY.md §III — the typescape; the four
    /// canonical [`SexpShape`] embed targets bind at ONE typed
    /// `[SexpShape; 4]` array on the closed-set QuoteForm algebra
    /// rather than at zero-primitive-on-this-subset-plus-four-inline-
    /// lookups scattered across the substrate. Closes the FOURTH
    /// per-role `pub const` axis on the QuoteForm carving alongside
    /// the pre-existing LABELS + PREFIXES + IAC_FORGE_TAGS +
    /// 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. 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
    /// [`crate::error::SexpShape::as_quote_form`] — 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_quote_form`, membership
    /// through `sexp_shape`, pairwise injectivity across the four
    /// embed targets) emerge from the composition of TWO substrate
    /// primitives (this `pub const` array + the four per-role
    /// `pub const *_SHAPE` aliases) rather than as per-variant inline
    /// assertions duplicated at each call site.
    pub const SHAPES: [SexpShape; 4] = [
        Self::QUOTE_SHAPE,
        Self::QUASIQUOTE_SHAPE,
        Self::UNQUOTE_SHAPE,
        Self::UNQUOTE_SPLICE_SHAPE,
    ];

    /// Project the typed marker into its matching [`crate::error::SexpShape`]
    /// variant — `Quote → SexpShape::Quote`, `Quasiquote → SexpShape::Quasiquote`,
    /// `Unquote → SexpShape::Unquote`, `UnquoteSplice → SexpShape::UnquoteSplice`.
    /// ONE projection on the closed-set quote-family algebra the substrate's
    /// outer-shape projection ([`crate::domain::sexp_shape`]) routes through
    /// for the four quote-family arms — so the (Sexp variant, SexpShape
    /// variant) pairing binds at ONE site on the typed algebra rather than
    /// at four byte-identical inline arms in [`crate::domain::sexp_shape`].
    ///
    /// The SIXTH consumer of the closed-set [`QuoteForm`] algebra, sibling
    /// of [`Self::prefix`] (Display / reader prefix-string surface),
    /// [`Self::hash_discriminator`] (Hash cache-key bytes surface),
    /// [`Self::as_unquote_form`] (2-of-4 template-substitution subset gate),
    /// [`Self::iac_forge_tag`] (cross-crate canonical-form tag surface), and
    /// [`Self::wrap`] (reader's marker → `Sexp::*` constructor surface).
    /// Composes with [`SexpShape::label`] to yield the short diagnostic
    /// label string the substrate's `LispError::TypeMismatch.got` slot
    /// renders — the (QuoteForm variant, SexpShape variant, short label)
    /// triple binds end-to-end through the typed algebra so a regression
    /// that drifts the short label silently between the typed marker and
    /// the diagnostic surface is structurally impossible.
    ///
    /// Each arm routes through the per-role `pub const` on `impl Self`
    /// ([`Self::QUOTE_SHAPE`], [`Self::QUASIQUOTE_SHAPE`],
    /// [`Self::UNQUOTE_SHAPE`], [`Self::UNQUOTE_SPLICE_SHAPE`]) so the
    /// four canonical embed targets bind at ONE typed source of truth
    /// per role rather than as inline `SexpShape::X` literals scattered
    /// across the `match` body. Sibling posture to
    /// [`AtomKind::sexp_shape`]'s post-lift routing through
    /// [`AtomKind::SYMBOL_SHAPE`] … [`AtomKind::BOOL_SHAPE`] on the peer
    /// 6-of-12 atomic-payload carving — the per-role `pub const *_SHAPE`
    /// routing is now uniform across every sub-carving of [`SexpShape`]
    /// that has a bidirectional (embed, project) isomorphism, closing
    /// the (embed-target constant, embed-target array, projection
    /// method) trio on each sub-carving in lockstep.
    ///
    /// Post-lift routing pin
    /// `quote_form_sexp_shape_routes_through_typed_per_role_constants`
    /// catches a regression that re-inlines the four `SexpShape::X` arm
    /// literals here and silently drifts ONE arm from the per-role
    /// `pub const` alias — the routing agreement is a TYPED CONSEQUENCE
    /// of the composition rather than literal discipline at two sites.
    ///
    /// Bidirectional dual: the inverse projection
    /// [`crate::error::SexpShape::as_quote_form`] (12→4, partial)
    /// covers the 4-of-12 carving of [`SexpShape`] this embed reaches.
    /// The pair `(QuoteForm::sexp_shape,
    /// SexpShape::as_quote_form)` forms an `Iso(QuoteForm, QuoteShape ⊂
    /// SexpShape)`: every typed marker round-trips through the embed
    /// (`QuoteForm::sexp_shape(qf).as_quote_form() == Some(qf)` for
    /// every `qf: QuoteForm`), every quote-shape pre-image recovers
    /// the typed marker. The non-quote-family shapes (`Nil`, `List`,
    /// every atomic-payload variant) form the kernel of the inverse —
    /// `as_quote_form` returns `None` for them. See
    /// [`crate::error::SexpShape::as_quote_form`]'s docstring for the
    /// composition law's other direction + disjointness with the
    /// atomic-payload sibling `SexpShape::as_atom_kind`.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the (QuoteForm
    /// variant, SexpShape variant) pairing becomes a TYPE projection on
    /// the substrate algebra rather than four inline arms in
    /// [`crate::domain::sexp_shape`]. 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; SIX
    /// consumers of the [`QuoteForm`] algebra now route through ONE typed
    /// closed-set match family, so a regression that drifts ONE consumer's
    /// pairing from the others cannot reach the substrate's runtime.
    /// THEORY.md §VI.1 — generation over composition; the (Sexp variant,
    /// SexpShape variant) pairing appeared at four arms in `sexp_shape` —
    /// past the ≥2 PRIME-DIRECTIVE trigger once the structural shape is
    /// named.
    #[must_use]
    pub fn sexp_shape(self) -> SexpShape {
        match self {
            Self::Quote => Self::QUOTE_SHAPE,
            Self::Quasiquote => Self::QUASIQUOTE_SHAPE,
            Self::Unquote => Self::UNQUOTE_SHAPE,
            Self::UnquoteSplice => Self::UNQUOTE_SPLICE_SHAPE,
        }
    }

    /// Project the typed marker to its canonical short diagnostic label —
    /// `"quote"` for [`Self::Quote`], `"quasiquote"` for
    /// [`Self::Quasiquote`], `"unquote"` for [`Self::Unquote`],
    /// `"unquote-splice"` for [`Self::UnquoteSplice`]. Body composes
    /// through `self.sexp_shape().label()` — routing through
    /// [`Self::sexp_shape`] (the typed 4-of-12 outer-value → SexpShape
    /// projection) then [`SexpShape::label`] (the canonical 12-arm
    /// diagnostic-label projection) so the (QuoteForm variant, short
    /// diagnostic string) pairing lives at ONE canonical site
    /// ([`SexpShape::label`]'s four quote-family arms in `error.rs`)
    /// rather than at four inline `&'static str` arms on the closed-set
    /// `QuoteForm` algebra.
    ///
    /// The outer-shape peer of [`crate::ast::Sexp::type_name`] one
    /// algebra layer up (`self.shape().label()` on outer-`Sexp`) and of
    /// [`crate::ast::Atom::label`] one algebra layer down
    /// (`self.kind().label()` on outer-`Atom` through [`AtomKind`]).
    /// Where `Atom::label` composes through the atomic-payload 6-of-12
    /// carving via [`AtomKind`] into [`SexpShape::label`], this method
    /// composes through the quote-family 4-of-12 carving directly onto
    /// [`SexpShape::label`] — the (label, sexp_shape, hash_discriminator)
    /// trio the outer-`Atom` algebra closed one lift back
    /// (`Atom::hash_discriminator`, e49f550) is now mirrored on the
    /// `QuoteForm` algebra: `prefix` (reader punctuation) and
    /// `iac_forge_tag` (CL canonical form) key the SAME closed set on
    /// their own boundaries, and `label` keys it on the substrate's
    /// operator-facing diagnostic boundary.
    ///
    /// Composition law: `qf.label() == qf.sexp_shape().label()` for every
    /// `qf: QuoteForm`. Pinned by
    /// `quote_form_label_composes_through_sexp_shape_label_for_every_variant`
    /// across all four variants — the pin asserts pointer-equality on the
    /// returned `&'static str` so a regression that re-inlines the four
    /// literals here (and gains its own drift surface separate from the
    /// canonical [`SexpShape::label`] site) surfaces immediately. Sibling
    /// of `atom_label_composes_through_kind_label_for_every_variant` one
    /// algebra layer down (on the outer-`Atom` value / `AtomKind` marker
    /// pair) and
    /// `sexp_type_name_method_composes_through_shape_label_for_every_outer_shape`
    /// one algebra layer up (on the outer-`Sexp` value / `SexpShape`
    /// marker pair).
    ///
    /// Cross-algebra agreement law: for every `qf: QuoteForm` and every
    /// `inner: Sexp`, `qf.label() == qf.wrap(inner).type_name()`. The
    /// (QuoteForm variant, canonical label) pairing lands at the SAME
    /// `&'static str` regardless of whether the consumer holds the typed
    /// marker directly or an outer-`Sexp` wrapper produced from
    /// [`Self::wrap`] — so a regression that drifts one algebra layer's
    /// label from the other (a `QuoteForm::label` re-inlined onto a
    /// different literal, a `Sexp::type_name` re-routed through a stale
    /// shape projection, a `QuoteForm::sexp_shape` arm that swaps two
    /// markers) fails-loudly here rather than as a silent operator-facing
    /// diagnostic drift at every consumer that pattern-matches on the
    /// outer-`Sexp` label vs the outer-`QuoteForm` label independently.
    /// Pinned by `quote_form_label_agrees_with_sexp_type_name_at_every_quote_form_arm`.
    ///
    /// Divergence law (boundary distinction with [`Self::iac_forge_tag`]):
    /// at the [`Self::UnquoteSplice`] arm, `qf.label() == "unquote-splice"`
    /// while `qf.iac_forge_tag() == "unquote-splicing"`. The two
    /// projections key the SAME closed-set on TWO distinct boundaries
    /// (substrate diagnostic surface vs cross-crate CL canonical form)
    /// and their intentional divergence at the `Splice` arm is pinned by
    /// `quote_form_label_diverges_from_iac_forge_tag_for_unquote_splice`
    /// — sibling posture to
    /// `quote_form_iac_forge_tag_diverges_from_sexp_shape_label_for_unquote_splice`
    /// which pinned the divergence at the `sexp_shape().label()`
    /// composition; this pin lifts the divergence contract onto the new
    /// typed peer.
    ///
    /// The `&'static str` lifetime is load-bearing: every future consumer
    /// with a `QuoteForm` in hand wanting the substrate's short
    /// diagnostic string projects through this method into the
    /// `LispError::TypeMismatch.got` slot / REPL / LSP surface without an
    /// allocation, parallel to how [`Self::prefix`] projects the reader
    /// punctuation and [`Self::iac_forge_tag`] projects the CL canonical
    /// tag. A future homoiconic prefix-wrapper (e.g. hypothetical `,~`
    /// reverse-unquote) extends [`Self`] AND [`SexpShape::label`]
    /// together — rustc binds the diagnostic surface to the algebra
    /// through the closed-set composition without touching this method.
    ///
    /// Theory anchor: THEORY.md §V.1 — knowable platform; the (QuoteForm
    /// variant, canonical short label) pairing becomes a TYPE projection
    /// on the substrate algebra composed through the pre-existing outer-
    /// shape projection, rather than at a per-callsite
    /// `.sexp_shape().label()` two-hop the load-bearing pin already
    /// carries as a composition-law contract. THEORY.md §II.1 invariant 2
    /// — free middle; the outer-`QuoteForm` diagnostic-label algebra now
    /// closes over THREE typed layers (`QuoteForm` → [`SexpShape`] →
    /// `&'static str`) with rustc-enforced consistency across each — a
    /// regression that drifts ONE layer's mapping from the others cannot
    /// reach the substrate's runtime typed-witness surface,
    /// `LispError::TypeMismatch.got` slot, or [`crate::error::SexpWitness::shape`]
    /// projection. THEORY.md §VI.1 — generation over composition; the
    /// outer-value diagnostic-label projection is the missing algebra
    /// layer between the outer `QuoteForm` and the pre-existing marker-
    /// level label projection — the two pre-existing typed layers become
    /// a full THREE-layer typed composition through ONE new named
    /// projection, closing the (prefix, iac_forge_tag, sexp_shape,
    /// hash_discriminator, label) quintet on the outer-`QuoteForm`
    /// algebra.
    ///
    /// Frontier inspiration: MLIR's `mlir::OperationName::getStringRef()`
    /// composed with an op-family typed projection — narrowing a
    /// closed-set op-family value through its typed identity yields the
    /// canonical diagnostic string identity in ONE typed composition on
    /// the op-family algebra. Translated through the substrate's
    /// [`QuoteForm`] outer-marker algebra, `qf.sexp_shape().label()`
    /// closes the (typed marker, canonical diagnostic label) pairing at
    /// ONE typed projection on the marker algebra composed through the
    /// outer-shape's per-carving canonical site. Racket's `(quote-kind
    /// qf)` composed with `(kind-label kind)` on the quote-family
    /// taxonomy — the typed diagnostic label emerges from a two-hop
    /// composition on the closed-set marker through the typed outer-shape
    /// identity. `QuoteForm::label` is the Rust-typed peer on the
    /// closed-set outer-[`QuoteForm`] algebra with [`SexpShape`] standing
    /// in for Racket's quote-family taxonomy.
    #[must_use]
    pub fn label(self) -> &'static str {
        self.sexp_shape().label()
    }

    /// Canonical `&'static str` bytes for the [`Self::Quote`] quote-family
    /// marker — aliases [`SexpShape::QUOTE_LABEL`] on the QuoteForm ⊂
    /// SexpShape carving so the marker-level per-role bytes bind at ONE
    /// `pub const` on the parent superset's quote-family arm rather than
    /// at TWO sites (the per-role `pub const` AND a parallel inline
    /// literal). Per-role peer of `Self::Quote` on the closed-set quote-
    /// family algebra; consumers reach for `QuoteForm::QUOTE_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 LABEL aliases ([`crate::ast::AtomKind::SYMBOL_LABEL`] …
    /// [`crate::ast::AtomKind::BOOL_LABEL`] — every one an alias of its
    /// [`SexpShape`] peer) and the peer 2-of-12 structural-residual
    /// carving's per-role LABEL aliases
    /// ([`crate::error::StructuralKind::NIL_LABEL`] +
    /// [`crate::error::StructuralKind::LIST_LABEL`]) — this closes the
    /// fourth and final closed-set sub-carving of [`SexpShape`] whose
    /// per-role diagnostic-label bytes are surfaced through the same
    /// alias-chain shape rather than reachable only through the
    /// composition [`Self::sexp_shape`] + [`SexpShape::label`]. Every
    /// SexpShape sub-carving (atomic payload, quote family, structural
    /// residual) now exposes its per-role LABEL bytes at ONE `pub const`
    /// per role on its subset algebra AS WELL AS at the parent
    /// superset's `SexpShape::*_LABEL`.
    ///
    /// The prefix-family peer of THIS `&'static str` constant is
    /// [`Self::QUOTE_PREFIX`] (`"'"` — reader-punctuation byte); the
    /// canonical-form peer is [`Self::QUOTE_IAC_FORGE_TAG`] (`"quote"` —
    /// cross-crate iac-forge tag). At the `Quote` arm the label and
    /// the iac-forge tag agree byte-for-byte (`"quote"`); the divergence
    /// axis lives at [`Self::UNQUOTE_SPLICE_LABEL`] (`"unquote-splice"`)
    /// vs [`Self::UNQUOTE_SPLICE_IAC_FORGE_TAG`] (`"unquote-splicing"`).
    /// The three parallel per-role `pub const` families (prefix, label,
    /// iac-forge tag) close the (reader, diagnostic, canonical-form)
    /// triple on the outer-`QuoteForm` algebra.
    pub const QUOTE_LABEL: &'static str = SexpShape::QUOTE_LABEL;

    /// Canonical `&'static str` bytes for the [`Self::Quasiquote`] quote-
    /// family marker — aliases [`SexpShape::QUASIQUOTE_LABEL`] on the
    /// QuoteForm ⊂ SexpShape carving. Per-role peer of `Self::Quasiquote`.
    /// See [`Self::QUOTE_LABEL`] for the alias-chain shape every sibling
    /// shares.
    pub const QUASIQUOTE_LABEL: &'static str = SexpShape::QUASIQUOTE_LABEL;

    /// Canonical `&'static str` bytes for the [`Self::Unquote`] quote-
    /// family marker — aliases [`SexpShape::UNQUOTE_LABEL`] on the
    /// QuoteForm ⊂ SexpShape carving. Per-role peer of `Self::Unquote`.
    /// See [`Self::QUOTE_LABEL`] for the alias-chain shape every sibling
    /// shares.
    pub const UNQUOTE_LABEL: &'static str = SexpShape::UNQUOTE_LABEL;

    /// Canonical `&'static str` bytes for the [`Self::UnquoteSplice`]
    /// quote-family marker — aliases [`SexpShape::UNQUOTE_SPLICE_LABEL`]
    /// on the QuoteForm ⊂ SexpShape carving. Per-role peer of
    /// `Self::UnquoteSplice`; the `"unquote-splice"` short label matches
    /// [`SexpShape::UNQUOTE_SPLICE_LABEL`] byte-for-byte and diverges
    /// INTENTIONALLY from [`Self::UNQUOTE_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). The divergence is pinned
    /// by `quote_form_label_diverges_from_iac_forge_tag_for_unquote_splice`
    /// on the runtime projection and by the byte-equality pins on THIS
    /// constant vs its iac-forge peer on the per-role `pub const`
    /// surface. See [`Self::QUOTE_LABEL`] for the alias-chain shape
    /// every sibling shares.
    pub const UNQUOTE_SPLICE_LABEL: &'static str = SexpShape::UNQUOTE_SPLICE_LABEL;

    /// Closed-set forced-arity ALL array over the canonical quote-family
    /// marker `&'static str` bytes, in declaration order matching
    /// [`Self::ALL`] element-wise (pinned by
    /// `quote_form_labels_align_with_all_by_index`). Sibling posture to
    /// [`crate::error::SexpShape::LABELS`] (`[&'static str; 12]` — the
    /// superset carving this QuoteForm subset embeds into),
    /// [`crate::ast::AtomKind::LABELS`] (`[&'static str; 6]` — the peer
    /// 6-of-12 atomic-payload carving's ALL array),
    /// [`crate::error::StructuralKind::LABELS`] (`[&'static str; 2]` —
    /// the peer 2-of-12 structural-residual carving's ALL array),
    /// [`Self::PREFIXES`] (`[&'static str; 4]` — reader-prefix axis on
    /// this same algebra), and [`Self::IAC_FORGE_TAGS`]
    /// (`[&'static str; 4]` — canonical-form tag axis on this same
    /// algebra) — 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 four quote-family marker labels had NO per-role
    /// primitive on this closed-set algebra — a consumer with a
    /// [`QuoteForm`] variant in hand at compile time reaching for the
    /// canonical diagnostic bytes had to spell `QuoteForm::Quote.label()`
    /// (runtime dispatch through the composition [`Self::sexp_shape`] +
    /// [`SexpShape::label`]) OR reach across the algebra boundary into
    /// [`SexpShape::QUOTE_LABEL`] and re-derive the QuoteForm ⊂
    /// SexpShape variant pairing at the call site. Post-lift the FOUR
    /// canonical labels bind at ONE `pub const` per role on the typed
    /// [`QuoteForm`] algebra AND at [`Self::LABELS`] as a family-wide
    /// forced-arity array — a future LSP / REPL completion bar keyed on
    /// `QuoteForm::LABELS` for the "quote-family" carving-axis column,
    /// a `tatara-check` coverage sweep over the quote-family arms of a
    /// `TypeMismatch.got` corpus, or a Sekiban audit-trail metric
    /// jointly labeled by the quote-family marker
    /// (`tatara_lisp_quote_family_label_total{label="quote"}`) reads
    /// through the typed constants on this subset algebra without re-
    /// deriving the 4-of-12 carving inline OR reaching across into the
    /// superset's twelve-entry `SexpShape::LABELS` array + filtering.
    ///
    /// Each entry is byte-for-byte identical to the corresponding
    /// [`SexpShape`] quote-family arm — an intentional cross-axis
    /// overlap pinned by
    /// `quote_form_per_role_labels_alias_sexp_shape_per_role_labels_byte_for_byte`
    /// so a future label rename on EITHER side (a `SexpShape`
    /// `"quote"` → `"cite"` drift, a `QuoteForm` rename that skips the
    /// alias, a hypothetical Racket-compat swap of `"quasiquote"`)
    /// fails-loudly at the alias test rather than as a silent operator-
    /// facing vocabulary fracture. Adding a hypothetical fifth
    /// homoiconic prefix-wrapper (a `,~` reverse-unquote, a `,?`
    /// conditional-unquote, a `#'` Common-Lisp function-quote) 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 four
    /// canonical quote-family marker labels bind at ONE typed
    /// `[&'static str; 4]` array on the closed-set [`QuoteForm`]
    /// algebra rather than at zero-primitive-on-this-subset-plus-four-
    /// inline-lookups scattered across the substrate. Closes the
    /// fourth SexpShape sub-carving's per-role LABEL parity with
    /// [`AtomKind`] and [`crate::error::StructuralKind`]. 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. The alias-
    /// chain shape is load-bearing: a [`SexpShape`]-side rename
    /// propagates through the const-eval alias chain byte-for-byte
    /// without silent drift. THEORY.md §VI.1 — generation over
    /// composition; the family-wide contract sweeps (alignment with
    /// [`Self::ALL`], pairwise disjointness, membership through
    /// [`Self::label`]) emerge from the composition of TWO substrate
    /// primitives (this `pub const` array + the four 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 `QuoteForm::LABELS[i] ==
    /// QuoteForm::ALL[i].sexp_shape().label()` binds the family-wide
    /// array to the composition through [`Self::sexp_shape`] +
    /// [`SexpShape::label`] at rustc time.
    pub const LABELS: [&'static str; 4] = [
        Self::QUOTE_LABEL,
        Self::QUASIQUOTE_LABEL,
        Self::UNQUOTE_LABEL,
        Self::UNQUOTE_SPLICE_LABEL,
    ];

    /// Project the typed marker back into its matching `Sexp::*` wrapper
    /// variant applied to `inner` — the structural inverse of
    /// [`crate::ast::Sexp::as_quote_form`]. [`Self::Quote`] yields
    /// [`Sexp::Quote`], [`Self::Quasiquote`] yields [`Sexp::Quasiquote`],
    /// [`Self::Unquote`] yields [`Sexp::Unquote`], [`Self::UnquoteSplice`]
    /// yields [`Sexp::UnquoteSplice`], each boxing `inner` into the
    /// corresponding tuple-variant constructor (`fn(Box<Sexp>) -> Sexp`).
    ///
    /// Round-trip identity with [`crate::ast::Sexp::as_quote_form`] — the
    /// structural law every consumer can pin against:
    ///
    /// ```ignore
    /// // for every (qf, inner): qf.wrap(inner.clone()).as_quote_form() == Some((qf, &inner))
    /// // for every Sexp s matching the quote family:
    /// //     let (qf, inner) = s.as_quote_form().unwrap();
    /// //     qf.wrap(inner.clone()) == s
    /// ```
    ///
    /// Consumer: [`crate::reader::read_quoted`] — the FIFTH consumer site
    /// of the closed-set `QuoteForm` algebra (sibling to `Hash for Sexp`'s
    /// `hash_discriminator` arm, `Display for Sexp`'s `prefix` arm,
    /// `Sexp::as_unquote`'s `as_unquote_form` subset-gate composition, and
    /// the feature-gated `From<&Sexp> for iac_forge::SExpr`'s
    /// `iac_forge_tag` arm). Pre-lift the reader's parse dispatch carried
    /// its own parallel closed set: a local `Token::{Quote, Quasiquote,
    /// Unquote, UnquoteSplice}` enum paired with the matching `Sexp::*`
    /// tuple-variant constructors threaded as `fn(Box<Sexp>) -> Sexp`
    /// arguments to `read_quoted`. The (Token variant, Sexp::* constructor)
    /// pairing was load-bearing yet only enforced by callsite discipline
    /// at the FIFTH consumer site the prior `QuoteForm` lifts did not
    /// reach — a regression that swapped `Sexp::Quote` and
    /// `Sexp::Quasiquote` between the parser arms type-checked but
    /// silently corrupted every program's quote-family parse.
    ///
    /// Post-lift the reader's `Token` collapses to ONE typed variant
    /// `Token::Quoted(QuoteForm)`, the parser's four prefix arms collapse
    /// to ONE arm `Some((Token::Quoted(qf), _)) => read_quoted(it,
    /// eof_pos, qf)`, and `read_quoted` routes through this projection to
    /// produce the matching `Sexp::*` variant. The (QuoteForm variant,
    /// Sexp::* constructor) pairing now binds at ONE site on the typed
    /// algebra — rustc enforces exhaustiveness across [`Self`]'s closed
    /// set, so a regression that drifts the (marker, constructor) pair
    /// becomes a typed compile error rather than a silent program-text
    /// corruption.
    ///
    /// The `Sexp` (owned) return type complements [`Sexp::as_quote_form`]'s
    /// `&Sexp` (borrowed) — `wrap` consumes the inner body to build the
    /// new wrapper, `as_quote_form` borrows the inner body from the
    /// existing wrapper. The asymmetry is intentional: at the reader's
    /// parse-then-wrap boundary the inner is fresh from `parse(...)?` and
    /// has no caller-owned binding; the typed `Box::new(inner)` allocation
    /// lives at ONE site rather than four (one per pre-lift parser arm),
    /// so a future allocation-policy change (e.g. arena-allocated wrappers
    /// for span-aware Sexp) lands as ONE edit.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 1 — typed entry; the
    /// reader's prefix-token → Sexp-wrapper gate IS the rust-level
    /// typed-entry gate at the source-text boundary, and naming the
    /// typed projection from [`QuoteForm`] back to the `Sexp::*` wrapper
    /// lifts the gate from per-arm constructor literals to ONE method
    /// the closed-set algebra owns — parallel to how [`Self::prefix`]
    /// lifts the Display↔reader prefix-string surface. THEORY.md §II.1
    /// invariant 2 — free middle; ALL FIVE consumers (Hash, Display,
    /// as_unquote, iac-forge interop, reader's parse) now route through
    /// the SAME closed-set algebra 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 (QuoteForm
    /// variant, Sexp::* constructor) pairing becomes a TYPE projection on
    /// the substrate algebra rather than four `fn(Box<Sexp>) -> Sexp`
    /// function pointers threaded as call arguments. A typo or
    /// swap is no longer a runtime drift but a compile error against the
    /// typed projection. THEORY.md §VI.1 — generation over composition;
    /// the (QuoteForm variant, Sexp::* constructor) pairing appeared at
    /// the four reader arms — past the ≥2 PRIME-DIRECTIVE trigger once
    /// the structural shape is named. The typed projection lands the
    /// structural-completeness floor for the reader's quote-family
    /// surface, completing the FIVE-consumer closure of the
    /// `QuoteForm` algebra.
    #[must_use]
    pub fn wrap(self, inner: Sexp) -> Sexp {
        let boxed = Box::new(inner);
        match self {
            Self::Quote => Sexp::Quote(boxed),
            Self::Quasiquote => Sexp::Quasiquote(boxed),
            Self::Unquote => Sexp::Unquote(boxed),
            Self::UnquoteSplice => Sexp::UnquoteSplice(boxed),
        }
    }
}

// `impl fmt::Display for QuoteForm` is generated by
// `#[derive(tatara_closed_set::DeriveClosedSet)]` + `#[closed_set(display)]` on
// the enum declaration above — emits the substrate-wide
// `f.write_str(Self::prefix(*self))` block byte-for-byte.

// `impl std::str::FromStr for QuoteForm` + `impl tatara_closed_set::ClosedSet for
// QuoteForm` + `pub struct UnknownQuoteForm(pub String)` are generated by
// `#[derive(tatara_closed_set::DeriveClosedSet)]` on the enum declaration
// above. `label` delegates to the inherent `QuoteForm::prefix` via
// `#[closed_set(via = "prefix")]` so the domain-canonical
// reader-punctuation projection (`"'" / "`" / "," / ",@"`) stays
// load-bearing at the inherent surface while the trait surface unifies
// every closed-set implementor's projection name onto `label`.
// `#[closed_set(generate_unknown = "quote form")]` emits the typed
// parse-rejection carrier with the substrate-wide `Debug + Clone +
// PartialEq + Eq + thiserror::Error` derives and the `#[error("unknown
// quote form: {0}")]` annotation byte-for-byte; the explicit label pins
// the pre-lift wording even though the auto-derived
// `pascal_to_spaced_lowercase("QuoteForm")` projects to the same
// `"quote form"` literal. The FromStr decode is a linear sweep over
// `QuoteForm::ALL` keyed on `prefix`: every successful decode round-trips
// through `prefix()`, cross-axis labels from `SexpShape` (`"quote" /
// "quasiquote" / ...`) and `iac_forge_tag` (`"unquote-splicing"`) reject —
// pinned by `quote_form_prefix_round_trips_through_from_str` +
// `quote_form_from_str_rejects_sexp_shape_labels_on_homoiconic_prefix_axis`.

/// Iterate over the argument tails of every form in `forms` whose call head
/// matches `keyword` — the *slice-side* sibling of [`Sexp::as_call_to`].
/// Where [`Sexp::as_call_to`] answers "is THIS form a call to `K`, and what
/// are its arguments?" on ONE form, `iter_calls_to` answers "which forms
/// in this SLICE are calls to `K`, and what are their arguments?" on a
/// `&[Sexp]`. Yields `&[Sexp]` for each matching form's argument tail
/// (`&form_list[1..]`, the empty slice for a singleton call like `(K)`);
/// non-matching forms — every shape [`Sexp::as_call_to`] rejects — are
/// skipped silently, matching the soft-projection posture the per-form
/// sibling carries.
///
/// Two consumers in [`compile.rs`](crate::compile) route through this
/// primitive:
///   * [`compile_typed::<T>`](crate::compile::compile_typed) — walks every
///     expanded top-level form and compiles every `(T::KEYWORD :k v …)`
///     form into a typed `T`.
///   * [`compile_named_from_forms::<T>`](crate::compile::compile_named_from_forms)
///     — walks every expanded form and compiles every
///     `(T::KEYWORD NAME :k v …)` form into a [`NamedDefinition<T>`](crate::compile::NamedDefinition).
///
/// Before this lift both consumers opened the same `for form in &expanded
/// { if let Some(args) = form.as_call_to(T::KEYWORD) { … } }` walk inline
/// — well past the ≥2 PRIME-DIRECTIVE trigger once the per-form sibling
/// had a name. After this lift the walk lives in ONE function the two
/// dispatchers route through; a regression that drifts ONE consumer's
/// walk from the other (a future emitter that inlines a partial filter,
/// a debug-mode logger that loses track of non-matching forms, a span-
/// aware walk that threads a borrowed `&Sexp` position alongside the
/// tail) becomes structurally impossible because there is exactly ONE
/// implementation both dispatchers consume. A future authoring tool
/// (LSP / REPL / `tatara-check`) that wants to surface "which forms in
/// this program invoke `K`?" binds to ONE function on the slice algebra
/// instead of re-deriving the walk per consumer.
///
/// Closes the soft-dispatch family at the slice level: the per-form
/// projections `{head_symbol, as_call, as_call_to, as_call_to_any}` each
/// answer "what does THIS form's head say?", and the slice-side
/// `iter_calls_to` extends them to "what do THESE forms' heads say,
/// projected through one keyword?". Typed-decoded sibling on the
/// slice algebra: [`iter_calls_to_any`] — the closure-typed extension
/// of THIS function the same way [`Sexp::as_call_to_any`] extends
/// [`Sexp::as_call_to`] on the per-form algebra. The (per-form,
/// slice-side) × (keyword, classifier) 2×2 of soft-dispatch
/// primitives is closed at the slice corner this lift establishes;
/// the closed-form composition binding the slice-side projection to
/// its per-form sibling is the structural identity every consumer
/// can pin against:
///
/// ```ignore
/// iter_calls_to(forms, k) == forms.iter().filter_map(|f| f.as_call_to(k))
/// ```
///
/// Post-lift `iter_calls_to`'s body composes
/// [`iter_calls_to_any`] with a keyword-equality decoder
/// (`|h| (h == keyword).then_some(())`) and drops the decoded unit, so
/// the keyword-typed slice walk IS the typed-decoded slice walk
/// restricted to a constant-keyword classifier. The (slice-side
/// keyword projection, slice-side typed-decoded projection) pair
/// binds at ONE filter-and-fuse implementation on the algebra
/// rather than at two parallel `forms.iter().filter_map(_)` triples
/// that the type system would not catch when one drifts from the
/// other (a future emitter that adds debug logging at one site but
/// not the other, a future span-aware walk that threads borrowed
/// positional metadata through one site but skips the other).
///
/// The yielded `&[Sexp]` slices borrow `&forms[i][1..]` verbatim — no
/// copy, no allocation, same lifetime as [`Sexp::as_call_to`]'s tail.
/// The iterator's lifetime `'a` is the unified outer lifetime of `forms`
/// AND `keyword`: the keyword string must outlive the iterator's borrow
/// of the slice (typical caller passes `T::KEYWORD: &'static str`, which
/// unifies trivially; a caller passing a locally-allocated `&str` ties
/// the iterator to that local). The closure captures `keyword` by move
/// (the `move` keyword on the `filter_map` closure), so each invocation
/// re-derives the head comparison via [`Sexp::as_call_to`]'s `head ==
/// keyword` check at every form — no shared-state, fully Iterator-fused.
///
/// Theory anchor: THEORY.md §VI.1 — generation over composition; the
/// two-site `for + as_call_to` inline walk is past the ≥2 PRIME-DIRECTIVE
/// trigger once the per-form sibling has a name. THEORY.md §V.1 —
/// knowable platform / "make invalid states unrepresentable"; the
/// slice-side projection becomes a NAMED primitive on the substrate's
/// `&[Sexp]` algebra rather than a re-derived for-loop at every consumer
/// site, so authoring tools (REPL, LSP, `tatara-check`) bind to ONE
/// function instead of re-implementing the walk. THEORY.md §II.1
/// invariant 1 — typed entry; the typed-keyword filter on a slice IS the
/// rust-level typed-entry-batch gate (the batch sibling of `as_call_to`'s
/// per-form gate), and naming its single shape lifts the gate from
/// two-site duplication to one rust function the substrate's diagnostic
/// promotions hang off of. THEORY.md §II.1 invariant 2 — free middle;
/// both dispatchers route through the SAME projection, so a regression
/// that drifts one consumer's walk from the other cannot reach the
/// substrate's runtime: the type system binds every consumer to the
/// projection's single emission shape.
///
/// Frontier inspiration: MLIR's `op.getOps<NamedOp>()` — every rewrite
/// pattern over a typed-op block binds to ONE typed-filter iterator
/// regardless of whether it's matching one op kind or batching across a
/// region's contents; the substrate's `iter_calls_to` is the
/// unstructured-projection peer of that iterator, lifted onto the
/// substrate's typed `&[Sexp]` algebra. Racket's `syntax-parse`
/// `~seq (defmacro id args …) …` ellipsis-form — the slice-level
/// matched-keyword filter is the closed-form sibling of `~seq`'s
/// repeated-pattern matcher, translated through pleme-io primitives as
/// ONE `iter_calls_to(forms, keyword)` projection. Tree-sitter's
/// `Query::matches` over a node sequence — the same "iterate the
/// matched forms in a parent" projection, inherited here for the typed
/// `Sexp` algebra without a new IR layer.
pub fn iter_calls_to<'a>(
    forms: &'a [Sexp],
    keyword: &'a str,
) -> impl Iterator<Item = &'a [Sexp]> + 'a {
    iter_calls_to_any(forms, move |h| (h == keyword).then_some(())).map(|(_, args)| args)
}

/// Iterate over the `(decoded, args)` pairs of every form in `forms` whose
/// call head decodes through `decode` — the *slice-side* sibling of
/// [`Sexp::as_call_to_any`]. Where [`Sexp::as_call_to_any`] answers "is
/// THIS form a call whose head decodes through `F`, and what are its
/// arguments?" on ONE form, `iter_calls_to_any` answers "which forms in
/// this SLICE are calls whose heads decode through `F`, and what do they
/// decode to alongside their arguments?" on a `&[Sexp]`. Yields
/// `(decoded, &[Sexp])` for each matching form — the decoded typed
/// witness alongside the matched form's argument tail (`&form_list[1..]`,
/// the empty slice for a singleton call like `(K)`); non-matching forms
/// — every shape [`Sexp::as_call_to_any`] rejects, including calls whose
/// head is present but `decode` returns `None` for — are skipped silently,
/// matching the soft-projection posture the per-form sibling carries.
///
/// Closes the soft-dispatch family at the slice corner this lift
/// establishes — the (per-form, slice-side) × (keyword, classifier) 2×2
/// of soft-dispatch primitives on the `Sexp`/`&[Sexp]` algebras:
///
/// |                | per-form              | slice-side               |
/// |----------------|-----------------------|--------------------------|
/// | keyword        | [`Sexp::as_call_to`]  | [`iter_calls_to`]        |
/// | classifier `F` | [`Sexp::as_call_to_any`] | `iter_calls_to_any` (this) |
///
/// The keyword corner is the constant-classifier projection of the
/// classifier corner: [`iter_calls_to`] now composes through THIS
/// primitive with a `move |h| (h == keyword).then_some(())` decoder
/// and drops the decoded unit, parallel to how
/// `Sexp::as_call_to(k) == Sexp::as_call_to_any(|h| (h ==
/// k).then_some(())).map(|(_, a)| a)` (modulo the discarded `()`) on
/// the per-form algebra. The slice-side filter-and-fuse implementation
/// now lives at ONE site, so a regression that drifts a debug-logging
/// instrumentation, span-aware borrow threading, or fused-iterator
/// invariant from one slice consumer to the other becomes
/// structurally impossible.
///
/// Two plausible future consumer shapes the typed-decoded slice walk
/// admits with no boilerplate:
///   * **Closed-set classifier** — `iter_calls_to_any(forms,
///     MacroDefHead::from_keyword)` walks a slice yielding `(head: MacroDefHead,
///     args: &[Sexp])` for every `(defmacro …)` / `(defpoint-template …)`
///     / `(defcheck …)` form, decoded to the typed `MacroDefHead` enum.
///     Future LSP / `tatara-check` consumers that surface "every
///     defmacro-family form in this buffer with its kind tag" bind to
///     ONE projection rather than a hand-rolled
///     `forms.iter().filter_map(|f| f.as_call_to_any(MacroDefHead::from_keyword))`
///     triple at each consumer site.
///   * **Live-registry classifier** — `iter_calls_to_any(forms, |h|
///     registry.get(h))` walks a slice yielding `(handler: &Handler,
///     args: &[Sexp])` for every form whose head matches a runtime
///     registry. Future REPL / `tatara-check` consumers that route
///     every form through a registry dispatcher bind to ONE
///     projection rather than re-deriving the `filter_map` pattern
///     per consumer surface — sibling shape to
///     [`Expander::expand`](crate::macro_expand::Expander::expand)'s
///     per-form `as_call_to_any(|h| self.macros.get(h))` macro-call
///     dispatch, lifted onto the slice algebra so a batch walk picks
///     up the same dispatch shape without re-derivation.
///
/// The closed-form composition binding the slice-side projection to
/// its per-form sibling is the structural identity every consumer can
/// pin against:
///
/// ```ignore
/// iter_calls_to_any(forms, decode) ==
///     forms.iter().filter_map(|f| f.as_call_to_any(&mut decode))
/// ```
///
/// The yielded `&[Sexp]` slices borrow `&forms[i][1..]` verbatim — no
/// copy, no allocation, same lifetime as [`Sexp::as_call_to_any`]'s
/// tail. `T` is owned because `decode` is `FnMut(&str) -> Option<T>`
/// and a `&'_ str` borrow into the head symbol would not outlive the
/// helper boundary; consumers projecting to a typed `Copy` enum
/// (e.g. `MacroDefHead`) get the value directly per form, consumers
/// projecting to a borrowed `&'static str` (a closed-set head)
/// project to `&'static str` and inherit the static lifetime through
/// the classifier. The closure is `FnMut` (rather than the per-form
/// sibling's `FnOnce`) because the slice walk calls it once per form
/// — a closure that captures mutable state (a counter, a registry
/// cache) maintains that state across the batch walk; a closure with
/// no mutable state is admitted trivially.
///
/// The iterator's lifetime `'a` unifies `forms`'s borrow lifetime
/// with the closure `F`'s captures lifetime: the decoder must outlive
/// the iterator's borrow of the slice, the typical caller passes a
/// `'static` decoder (a `fn` item like `MacroDefHead::from_keyword`,
/// or a closure capturing nothing) which unifies trivially. The
/// closure captures `decode` by move (the `move` keyword on the
/// `filter_map` closure), so each invocation re-borrows it as
/// `&mut decode` and calls [`Sexp::as_call_to_any`] with a fresh
/// `FnOnce`-coerced borrow — no shared-state hazard, fully
/// Iterator-fused.
///
/// Theory anchor: THEORY.md §VI.1 — generation over composition; the
/// per-form classifier sibling [`Sexp::as_call_to_any`] has two
/// production consumers (`macro_def_from` via closed-set classifier
/// `MacroDefHead::from_keyword`, `Expander::expand` via live-registry
/// classifier `|h| self.macros.get(h)`) — past the ≥2 PRIME-DIRECTIVE
/// trigger once the slice-side projection is named. Future
/// authoring-tool surfaces (LSP buffer walks, `tatara-check` batch
/// dispatchers, REPL exhaustive listers) join the family without
/// re-deriving the `filter_map(|f| f.as_call_to_any(_))` triple per
/// consumer. THEORY.md §V.1 — knowable platform; the slice-side
/// typed-decoded projection becomes a NAMED primitive on the
/// substrate's `&[Sexp]` algebra, closing the 2×2 of soft-dispatch
/// primitives the per-form algebra already establishes. THEORY.md
/// §II.1 invariant 2 — free middle; the slice-side keyword filter
/// ([`iter_calls_to`]) now routes through the slice-side classifier
/// filter (THIS function) via the constant-classifier composition, so
/// a regression that drifts the keyword filter's instrumentation
/// from the classifier filter's instrumentation becomes structurally
/// impossible.
///
/// Frontier inspiration: MLIR's
/// `op.walk<OpInterface, OpInterface2, …>([&](auto op) { … })` — the
/// typed-IR walk over a region yielding ops decoded to their typed
/// interface witness IS the slice-side typed-decoded projection on
/// MLIR's op algebra; `iter_calls_to_any` is the unstructured-Rust
/// peer on the substrate's typed `&[Sexp]` algebra, with `decode:
/// FnMut(&str) -> Option<T>` standing in for MLIR's typed-interface
/// dyn-cast bag. Racket's `syntax-parse` `~or* (~datum defmacro)
/// (~datum defpoint-template) (~datum defcheck) (head args …)` over
/// an ellipsis-form — the slice-level matched-set filter decoded to
/// a typed witness is the closed-form sibling of `~or*`'s
/// typed-choice repeater, translated through pleme-io primitives as
/// ONE `iter_calls_to_any(forms, F)` projection.
pub fn iter_calls_to_any<'a, F, T>(
    forms: &'a [Sexp],
    mut decode: F,
) -> impl Iterator<Item = (T, &'a [Sexp])> + 'a
where
    F: FnMut(&str) -> Option<T> + 'a,
    T: 'a,
{
    forms
        .iter()
        .filter_map(move |f| f.as_call_to_any(&mut decode))
}

/// Iterate over the `Result<(decoded, NAME, spec_args)>` triples of every
/// form in `forms` whose call head decodes through `decode` AND carries a
/// positional NAME slot — the *slice-side* sibling of
/// [`Sexp::as_call_to_any`] specialized to the named NAME-then-kwargs
/// form shape, with the named-form structural gate
/// [`crate::compile::split_name_slot`] composed in. Where
/// [`iter_calls_to_any`] answers "which forms in this SLICE are calls
/// whose heads decode through `F`, and what do they decode to alongside
/// their args tail?" on a `&[Sexp]`, `iter_named_calls_to_any` answers
/// the same question AND extracts the borrowed NAME slot AND the
/// remaining spec args tail in ONE projection per matched form, lifting
/// the named-form gate from inside the projection at every consumer
/// site to the slice algebra itself.
///
/// The yielded `Result<(T, &'a str, &'a [Sexp])>` shape carries the
/// classifier's typed witness `T` alongside the BORROWED NAME slot AND
/// the BORROWED spec args tail. Non-matching forms (every shape
/// [`Sexp::as_call_to_any`] rejects, AND every call whose head is
/// present but `decode` returns `None` for) are skipped silently — the
/// classifier filter precedes the named gate, mirroring how
/// [`crate::compile::split_name_slot`] is composed into the projection
/// AFTER the classifier-decoded args tail is already in hand. Matched
/// forms whose NAME slot is missing yield `Err(NamedFormMissingName {
/// keyword })` carrying the classifier-supplied keyword; matched forms
/// whose NAME slot is a non-symbol-or-string yield `Err(NamedFormNonSymbolName
/// { keyword, got })` carrying the same keyword and the typed
/// [`SexpShape`](crate::error::SexpShape) projection of the offending
/// slot. Consumers `.collect::<Result<Vec<_>, _>>()` to short-circuit
/// at the first malformed NAME slot, exactly as
/// [`Expander::expand_and_collect_named_calls_to_any`](crate::macro_expand::Expander::expand_and_collect_named_calls_to_any)
/// short-circuits today via the same `split_name_slot` gate composed
/// inside its projection closure.
///
/// Decoder signature `FnMut(&str) -> Option<(T, &'static str)>` pairs
/// the typed witness `T` with the canonical static keyword threaded
/// through the `NamedFormMissingName.keyword` /
/// `NamedFormNonSymbolName.keyword` slots of the named-form gate — the
/// `&'static` constraint pins the same compile-time discipline
/// [`crate::compile::split_name_slot`]'s `keyword: &'static str`
/// parameter pins at its boundary. A classifier consumer that wants
/// "filter forms by a constant keyword" supplies a constant-classifier
/// decoder `|h| (h == keyword).then_some(((), keyword))`; the
/// [`iter_named_calls_to`] sibling below is exactly that specialization.
///
/// Closes the (per-form, slice-side) × (keyword, classifier) × (bare,
/// named) 2×2×2 cube of soft-dispatch primitives on the substrate's
/// `Sexp`/`&[Sexp]` algebras at the slice-side × classifier × named
/// corner — the cube the per-form algebra
/// (`as_call_to{,_any}`), the slice algebra
/// (`iter_calls_to{,_any}`), and the Expander surface
/// (`expand_and_collect_calls_to{,_any}` /
/// `expand_and_collect_named_calls_to{,_any}`) collectively shape:
///
/// |                | bare-kwargs              | named NAME-then-kwargs                           |
/// |----------------|--------------------------|--------------------------------------------------|
/// | per-form       | [`Sexp::as_call_to_any`] | [`Sexp::as_named_call_to_any`]                   |
/// | slice          | [`iter_calls_to_any`]    | `iter_named_calls_to_any` (this)                 |
/// | expander       | `expand_and_collect_calls_to_any` | `expand_and_collect_named_calls_to_any`  |
///
/// Pre-lift the bare expander surface (`expand_and_collect_calls_to_any`)
/// routed through the slice primitive ([`iter_calls_to_any`]) via a
/// uniform `expand_program + iter_calls_to_any + map + collect`
/// pipeline; the named expander surface
/// (`expand_and_collect_named_calls_to_any`) routed through the
/// BARE expander surface and welded
/// [`crate::compile::split_name_slot`] INSIDE the projection closure —
/// the named gate composition lived at the expander level rather than
/// at the slice level the bare row sat at. Post-lift the named expander
/// surface routes through THIS slice primitive via the SAME
/// `expand_program + iter_named_calls_to_any + map + collect`
/// pipeline shape, so both rows now share the same composition skeleton
/// on the slice algebra — a regression that drifts a future debug-mode
/// logger, span-aware borrow walker, or fused-iterator invariant from
/// one row to the other becomes structurally impossible at the slice
/// boundary.
///
/// Two plausible future consumer shapes the slice-side named-classifier
/// walk admits with no boilerplate:
///   * **Closed-set classifier** — `iter_named_calls_to_any(forms, |h|
///     match h { "defmonitor" => Some((Kind::Monitor, "defmonitor")),
///     "defalertpolicy" => Some((Kind::Alert, "defalertpolicy")), _ =>
///     None }).collect::<Result<Vec<_>, _>>()?` walks a slice of
///     already-expanded forms, yielding the `(typed Kind, NAME, spec
///     args)` triple for every `(defmonitor NAME …)` / `(defalertpolicy
///     NAME …)` form. Future `tatara-check` consumers that already hold
///     expanded forms (the workspace coherence checker walks
///     `checks.lisp`'s post-expansion top-level) bind to ONE projection
///     on the slice algebra rather than re-deriving the
///     `iter_calls_to_any(forms, decode).map(|(decoded, args)| {
///     split_name_slot(args, kw).map(|(name, rest)| (decoded, name,
///     rest)) })` four-step inline composition.
///   * **Live-registry classifier** — `iter_named_calls_to_any(forms,
///     |h| registry.lookup(h).map(|h| (h, h.canonical_label())))` walks
///     a slice of expanded forms, yielding the `(handler reference, NAME,
///     spec args)` triple for every form whose head matches a runtime
///     registry. Future REPL / authoring-tool surfaces that dispatch
///     named forms through a live registry bind to ONE projection,
///     sibling shape to how the macro expander already routes through
///     a live-registry classifier via
///     [`Sexp::as_call_to_any`].
///
/// The closed-form composition binding this slice primitive to its
/// per-form sibling AND to the bare-kwargs slice primitive is the
/// structural identity every consumer can pin against:
///
/// ```ignore
/// iter_named_calls_to_any(forms, decode) ==
///     iter_calls_to_any(forms, decode).map(|(decoded, args)| {
///         let kw = /* keyword the decoder returned alongside decoded */;
///         split_name_slot(args, kw).map(|(name, rest)| (decoded, name, rest))
///     })
/// ```
///
/// The yielded `&'a str` NAME slot and `&'a [Sexp]` spec args tail
/// borrow from `&forms[i]` verbatim — no copy, no allocation, same
/// lifetime as [`Sexp::as_call_to_any`]'s tail. Consumers that need
/// owned ownership of the NAME (`NamedDefinition.name: String`,
/// JSON-serialized payloads) `.to_string()` themselves — pushing the
/// clone to the consumer boundary keeps the primitive allocation-free.
///
/// Theory anchor: THEORY.md §VI.1 — generation over composition; the
/// named-form gate composition lived at the Expander level pre-lift
/// (inside `expand_and_collect_named_calls_to_any`'s projection
/// closure); the slice algebra had no named sibling to the bare
/// [`iter_calls_to_any`]. Post-lift the slice algebra closes at the
/// named corner, and the Expander surface routes through it via the
/// SAME `expand_program + iter + map + collect` pipeline the bare
/// expander surface uses. THEORY.md §V.1 — knowable platform; the
/// slice-side named-classifier walk becomes a NAMED primitive on the
/// substrate's `&[Sexp]` algebra, discoverable by any future authoring
/// tool (LSP, REPL, `tatara-check`) that already holds expanded forms.
/// THEORY.md §II.1 invariant 2 — free middle; the bare and named slice
/// projections share the same `forms.iter().filter_map(_)` skeleton, so
/// a regression that drifts ONE row's instrumentation from the other
/// becomes structurally impossible.
///
/// Frontier inspiration: MLIR's
/// `region.walk<NamedOp>([&](auto op) { auto name = op.getName(); … })`
/// — the typed-IR walk over a region yielding ops decoded to their
/// typed kind with the NAMED-symbol accessor pre-extracted is the MLIR
/// idiom for a named-op visitor; `iter_named_calls_to_any` is the
/// unstructured-Rust peer on the substrate's `&[Sexp]` algebra, with
/// `decode: FnMut(&str) -> Option<(T, &'static str)>` standing in for
/// MLIR's typed-interface dyn-cast bag AND `split_name_slot` standing
/// in for the named accessor. Racket's `syntax-parse` `~or* ((~datum
/// defX) name:id arg ...) ((~datum defY) name:id arg ...)` over an
/// ellipsis-form — the slice-level matched-set named-form filter
/// decoded to a typed witness is the closed-form sibling of `~or*`'s
/// typed-choice repeater with the `name:id` capture binder, translated
/// through pleme-io primitives as ONE projection on the `&[Sexp]`
/// algebra.
pub fn iter_named_calls_to_any<'a, F, T>(
    forms: &'a [Sexp],
    mut decode: F,
) -> impl Iterator<Item = crate::error::Result<(T, &'a str, &'a [Sexp])>> + 'a
where
    F: FnMut(&str) -> Option<(T, &'static str)> + 'a,
    T: 'a,
{
    forms
        .iter()
        .filter_map(move |f| f.as_named_call_to_any(&mut decode))
}

/// Iterate over the `Result<(NAME, spec_args)>` pairs of every form in
/// `forms` whose call head matches `keyword` AND carries a positional
/// NAME slot — the *slice-side* sibling of [`Sexp::as_call_to`]
/// specialized to the named NAME-then-kwargs form shape, with the
/// named-form structural gate [`crate::compile::split_name_slot`]
/// composed in. Where [`iter_calls_to`] answers "which forms in this
/// SLICE are calls to `K`, and what are their args tails?" on a
/// `&[Sexp]`, `iter_named_calls_to` answers the same question AND
/// extracts the borrowed NAME slot AND the remaining spec args tail in
/// ONE projection per matched form.
///
/// Routes through the typed-decoded sibling [`iter_named_calls_to_any`]
/// with a constant-classifier decoder — the same constant-classifier
/// composition [`iter_calls_to`] uses to route through
/// [`iter_calls_to_any`] on the bare-kwargs axis, and that
/// [`crate::macro_expand::Expander::expand_and_collect_named_calls_to`]
/// uses to route through
/// [`crate::macro_expand::Expander::expand_and_collect_named_calls_to_any`]
/// on the Expander surface. The discarded `()` typed witness
/// (`then_some(((), keyword))`) is consumed by the wrapper projection so
/// the consumer's per-form mapper sees only the `(name, spec_args)`
/// borrowed pair, matching the bare projection signature on the named
/// axis.
///
/// `keyword: &'static str` threads verbatim through the
/// `NamedFormMissingName.keyword` / `NamedFormNonSymbolName.keyword`
/// slots of the named-form gate — same `&'static` discipline
/// [`crate::compile::split_name_slot`] pins at its boundary. Consumers
/// that want a runtime keyword whose lifetime is `&'static` (typical:
/// `T::KEYWORD` of a typed-domain witness, a hardcoded literal like
/// `"defcheck"`) bind to this primitive; consumers that want a runtime
/// keyword whose lifetime is shorter use [`iter_named_calls_to_any`]
/// directly with a constant-classifier decoder that converts
/// post-resolution.
///
/// Closes the (slice-side × constant-keyword × named) corner of the
/// soft-dispatch cube — see [`iter_named_calls_to_any`]'s docstring for
/// the cube shape. The closed-form composition binding this primitive
/// to the typed-decoded sibling is the structural identity every
/// consumer can pin against:
///
/// ```ignore
/// iter_named_calls_to(forms, k) ==
///     iter_named_calls_to_any(forms, |h| (h == k).then_some(((), k)))
///         .map(|maybe_triple| maybe_triple.map(|(_, name, args)| (name, args)))
/// ```
///
/// Theory anchor: THEORY.md §VI.1 — generation over composition; the
/// constant-keyword named slice projection is a CONSEQUENCE of the
/// typed-decoded named slice projection + a constant-classifier
/// decoder, parallel to how [`iter_calls_to`] is a consequence of
/// [`iter_calls_to_any`] on the bare-kwargs axis. THEORY.md §II.1
/// invariant 2 — free middle; both rows of the slice algebra
/// (bare-kwargs, named) route through their classifier sibling via
/// constant-classifier composition, so a regression that drifts ONE
/// row's pipeline from the other becomes structurally impossible.
pub fn iter_named_calls_to<'a>(
    forms: &'a [Sexp],
    keyword: &'static str,
) -> impl Iterator<Item = crate::error::Result<(&'a str, &'a [Sexp])>> + 'a {
    iter_named_calls_to_any(forms, move |h| (h == keyword).then_some(((), keyword)))
        .map(|maybe_triple| maybe_triple.map(|(_, name, args)| (name, args)))
}

/// Render an `Atom::Float`'s `f64` value to a form that re-reads as
/// `Atom::Float` — preserves the float-vs-int typed identity across the
/// `Sexp::Display` → [`crate::reader::read`] round-trip.
///
/// Rust's stdlib `Display` impl for `f64` elides the trailing `.0` for
/// finite integral values: `format!("{}", 1.0_f64) == "1"`,
/// `format!("{}", 100.0_f64) == "100"`. The substrate's reader
/// (via the typed-entry classifier [`Atom::from_lexeme`]) tries
/// `i64::parse` BEFORE `f64::parse`, so a bare `1` re-reads as
/// `Atom::Int(1)` — NOT as `Atom::Float(1.0)`. The default Display rendering therefore drifts the
/// typed identity at the Display→read boundary: `Float(1.0)` round-trips
/// to `Int(1)` and a regression silently coerces an authoring-surface
/// `1.0` slot into the typed `Int` track.
///
/// This helper emits `1.0` for `1.0_f64` and `1.5` for `1.5_f64` — the
/// `.0` suffix is appended IFF the value is finite AND already integral
/// (`n == n.trunc()`). Non-integral values render through the default
/// `f64` Display impl, which already preserves the fractional component
/// (`1.5`, `0.99`, etc.) round-trippably. Non-finite values (`NaN`,
/// `inf`, `-inf`) also fall through to the default impl — they cannot be
/// reliably round-tripped through the reader regardless (the Hash impl
/// already warns about NaN's PartialEq irregularity at the cache-key
/// boundary), so the helper does not paper over that prior limitation.
///
/// Theory anchor: THEORY.md §II.1 invariant 1 — typed entry; the
/// substrate's typed-entry gate distinguishes `Atom::Int` from
/// `Atom::Float`, and the Display→read round-trip is the typed-exit-side
/// mirror that must preserve the distinction. Pre-lift the
/// `Float(integral) → Int(integral)` collapse silently violated the
/// invariant at the round-trip boundary; post-lift the typed identity is
/// preserved. THEORY.md §V.1 — knowable platform; diagnostics that
/// project a `Float(1.0)` slot through `SexpWitness::display` (sourced
/// from `Sexp::to_string()`) used to surface as `got 1` — confusingly
/// identical to the typed `Int(1)` projection. Post-lift the diagnostic
/// shape names the offender's typed identity (`got 1.0`) so operators
/// distinguish "you wrote 1.0 in an int slot" from "you wrote 1 in a
/// kwarg slot the kwarg gate rejected" without re-reading source.
fn fmt_float(n: f64, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    if n.is_finite() && n == n.trunc() {
        write!(f, "{n}.0")
    } else {
        write!(f, "{n}")
    }
}

/// Canonical reader-round-trippable rendering of a single atomic payload —
/// `Symbol(s) → "{s}"`, `Keyword(s) → ":{s}"`, `Str(s) → "{s:?}"` (the
/// debug-quoted form: `\"…\"` with embedded `"` and `\` escaped), `Int(n)
/// → "{n}"`, `Float(n)` through [`fmt_float`] so integral values render
/// with the `.0` suffix that preserves the typed-`Float`-vs-typed-`Int`
/// distinction at the Display→read boundary, `Bool(true) → "#t"`,
/// `Bool(false) → "#f"` (the Scheme bool spellings the reader's
/// typed-entry classifier [`Atom::from_lexeme`] dispatches on — `true`
/// / `false` re-read as symbols, NOT as bools — see the CLAUDE.md
/// "Lisp bools" warning).
///
/// This is the *atomic-payload Display surface* — the typed-exit-side
/// peer of [`Atom::from_lexeme`]'s atomic-payload typed-entry surface
/// (the FOURTH and LAST of the per-`Atom`-variant projection sites
/// lifted onto the closed-set algebra, after the typed-exit Display
/// [this impl], JSON [`Atom::to_json`], and iac-forge canonical
/// attestation `Atom::to_iac_forge_sexpr` (removed) projections — completing
/// the bidirectional typed-entry/typed-exit sweep). Before this lift
/// the per-variant rendering arms
/// lived inline at the `Sexp::Atom(a) => match a { … }` arm of
/// [`fmt::Display for Sexp`]; routing the outer arm through this impl
/// lifts the seven inline sub-arms (the Bool variant splits into
/// `true`/`false` to short-circuit the `if-else` branch) into ONE
/// typed-algebra method the `Sexp` Display arm calls into via
/// `fmt::Display::fmt(a, f)`. Sibling closed-set lift to
/// [`QuoteForm::prefix`] (the four homoiconic prefix wrappers) and
/// [`AtomKind::label`] (the six diagnostic labels) — those name the
/// quote-family and atomic-discriminator pairings at the `Sexp` and
/// `Atom` algebras respectively; this names the atomic-payload
/// rendering at the `Atom` algebra so future consumers of "render a
/// bare atom" land on this impl directly without unwrapping through
/// `Sexp::Atom(_).to_string()` and stripping the outer wrap.
///
/// Three production-site sibling shapes the substrate carries that
/// route through a per-`Atom`-variant projection, all 6/7-arm inline
/// matches pre-lift:
///   * [`fmt::Display for Sexp`]'s atom arm — 7 sub-arms (Bool splits),
///     produces a `fmt::Formatter` body. Post-lift collapses to
///     ONE `fmt::Display::fmt(a, f)` delegation.
///   * [`crate::domain::sexp_to_json`]'s atom arms — 6 inline arms
///     producing `serde_json::Value`. Now lifted onto [`Atom::to_json`]
///     in the sibling pattern this impl's docstring named; the
///     `sexp_to_json` site collapses to ONE `Sexp::Atom(a) =>
///     a.to_json()` arm.
///   * `crate::interop`'s `From<&Sexp> for SExpr` (removed)'s
///     atom arm (feature-gated `iac-forge`) — 6 inline arms producing
///     `iac_forge::sexpr::SExpr`. Now lifted onto
///     `Atom::to_iac_forge_sexpr` (removed) in the sibling pattern this impl's
///     docstring named; the interop site collapses to ONE
///     `Sexp::Atom(a) => a.to_iac_forge_sexpr()` arm. THIRD and LAST
///     of the three production-site atom-arm shapes lifted onto the
///     typed `Atom` algebra; the sweep across the Lisp / JSON /
///     iac-forge canonical-form surfaces is complete.
///
/// The (Atom variant, rendered prefix/suffix/body) quadruple now lives
/// at ONE typed-algebra Display impl rather than at seven inline
/// sub-arms inside `Display for Sexp`'s outer Atom arm. A regression
/// that drifts the Bool spelling (`#t`/`#f` vs `true`/`false`) — the
/// CLAUDE.md-pinned reader-round-trip invariant — now lands at ONE
/// site, and the test surface pins each variant's canonical rendering
/// AND the round-trip identity through the reader at the Atom level
/// directly (no Sexp wrap required to exercise the round-trip).
///
/// Bidirectional contract anchored by tests in this module:
///   * `atom_display_renders_each_variant_to_canonical_form` —
///     sweeps `AtomKind::ALL` and pins each variant's canonical
///     rendering byte-for-byte against the pre-lift inline literal,
///     so a future regression that drifts ONE arm (e.g. swaps
///     `#t`/`#f` for `true`/`false`, or strips `Str`'s quote marks)
///     fails loudly.
///   * `sexp_atom_display_arm_routes_through_atom_display_for_every_variant`
///     — pins the lifted boundary: `Sexp::Atom(a).to_string() ==
///     a.to_string()` for every atomic payload variant, AND that
///     both equal the legacy inline rendering. Catches a future
///     drift where one surface's per-variant body changes without
///     the other.
///   * `atom_display_round_trips_through_reader_preserving_typed_identity`
///     — sweeps a representative atom of each variant, renders it
///     via `Atom::Display`, parses the rendering through
///     [`crate::reader::read`], and pins the parsed atom equals
///     the seed atom (modulo `Str`'s debug-quoted spelling — pinned
///     separately because the reader expects unquoted source-level
///     `"foo"`). Pins that the (`Atom::Display`, reader) pair forms
///     a typed round-trip at the atom layer, the same invariant
///     [`fmt_float`]'s `.0` suffix preserves for the float-vs-int
///     distinction at the Sexp layer.
///
/// Theory anchor: THEORY.md §VI.1 — generation over composition; the
/// (Atom variant, canonical rendering) pair appeared inline at THREE
/// production sites (`Display for Sexp`'s 7-sub-arm atom arm,
/// `sexp_to_json`'s 6 atom arms, `From<&Sexp> for SExpr`'s 6 atom arms)
/// — well past the ≥2 PRIME-DIRECTIVE trigger once the structural
/// shape is named. THIS lift retires the Display-surface site by
/// naming the typed primitive on the `Atom` algebra; future runs route
/// the JSON and iac-forge sites through parallel sibling projections
/// (`Atom::to_json`, `Atom::to_iac_forge_sexpr`) the same pattern
/// names. THEORY.md §II.1 invariant 1 — typed entry; the substrate's
/// [`Atom::from_lexeme`] is the typed-entry gate at the atomic-payload
/// boundary (lifted onto the typed [`Atom`] algebra from the reader's
/// pre-lift free function), and this impl is the typed-exit-side
/// mirror — the closed-set [`AtomKind`] algebra now threads BOTH gates
/// through ONE projection family, so a regression that drifts one side's
/// per-variant rendering from the other (e.g. extends `Atom` with a
/// `Char` variant the reader accepts but the writer can't emit) is no
/// longer a silent two-site divergence — rustc binds both sides to
/// the same closed-set enum. THEORY.md §II.1 invariant 2 — free middle;
/// the typed-exit rendering, the reader, the diagnostic surface
/// (`LispError::TypeMismatch.got` slot rendering an atomic witness),
/// and any future authoring tool (LSP / REPL pretty-printer) all
/// route through ONE per-variant rendering rather than per-callsite
/// re-derivation.
///
/// Frontier inspiration: Racket's `(syntax->datum stx)` / `write` pair
/// — where `syntax->datum` unwraps the homoiconic surface to its
/// atomic-payload layer and `write` emits the canonical S-expression
/// rendering bound to the reader's `read` inverse; `Atom::Display`
/// is the substrate's typed-algebra peer at the atomic-payload boundary,
/// with the closed-set [`AtomKind`] standing in for Racket's
/// datum-prim taxonomy. MLIR's `mlir::AsmPrinter::printAttribute` — the
/// typed-IR attribute printer dispatches on the closed-set
/// `AttributeKind` so every printer body for a kind lives at ONE
/// implementation site; `Atom::Display` is the unstructured Rust peer
/// for the `Sexp`/`Atom` algebra, with `fmt::Display` standing in for
/// MLIR's `AsmPrinter` interface.
impl fmt::Display for Atom {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Symbol(s) => f.write_str(s),
            Self::Keyword(s) => write!(f, "{}{s}", Self::KEYWORD_MARKER),
            // NOT `{s:?}`. Rust's `str` Debug escapes NUL as `\0`, and this
            // reader deliberately decodes `\0` as the DIGIT `0` — see
            // `decode_str_escape`'s passthrough arm and the test pinning it.
            // So `{s:?}` emitted an escape that means something else here, and
            // `"nul\0byte"` round-tripped to `"nul0byte"`: silent corruption
            // from two locally-correct decisions disagreeing.
            //
            // This escaper emits exactly what THIS reader decodes: the five
            // named/self escapes, and `\u{…}` for anything else non-printable
            // (which the reader gained an arm for alongside this fix). Display
            // and read are inverses again.
            Self::Str(s) => write!(f, "{}", Self::escape_str_payload(s)),
            Self::Int(n) => write!(f, "{n}"),
            Self::Float(n) => fmt_float(*n, f),
            // Bool arm collapses to ONE branch routing through
            // `Self::bool_literal` — the closed-set `bool` fork happens
            // at the typed projection on the [`Atom`] algebra, not at
            // this consumer's match body. Sibling lift to the Keyword
            // arm, which routes through `Self::KEYWORD_MARKER` at the
            // same algebra layer.
            Self::Bool(b) => f.write_str(Self::bool_literal(*b)),
        }
    }
}

impl fmt::Display for Sexp {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            // The empty-list rendering `()` composes BOTH structural
            // delimiters — [`Self::LIST_OPEN`] followed by
            // [`Self::LIST_CLOSE`] — on the closed-set outer [`Sexp`]
            // algebra. Pre-lift the same two bytes lived inline as one
            // `"()"` string literal at this arm; post-lift each byte
            // binds to its typed constant, so a delimiter swap flips
            // both this arm AND the `Self::List(_)` opener/closer arm
            // below AND the reader's `Token::LParen` / `Token::RParen`
            // outer-dispatch arms in lockstep — at ONE constant per
            // side rather than at four inline bytes across two files.
            Self::Nil => {
                f.write_char(Self::LIST_OPEN)?;
                f.write_char(Self::LIST_CLOSE)
            }
            // The atomic-payload rendering lives at the typed
            // [`fmt::Display for Atom`] impl above — the seven inline
            // sub-arms `Symbol → s`, `Keyword → ":{s}"`, `Str → "{s:?}"`,
            // `Int → "{n}"`, `Float → fmt_float`, `Bool(true) → "#t"`,
            // `Bool(false) → "#f"` all bind at ONE site on the closed-set
            // `Atom` algebra rather than at this outer arm. A future
            // atomic-kind extension (e.g. `Char` for `#\x` reader syntax,
            // `Bigint` for arbitrary-precision integers) extends `Atom`'s
            // Display impl once and this arm picks up the new variant
            // for free.
            Self::Atom(a) => fmt::Display::fmt(a, f),
            // The `Self::List(_)` opener AND closer arms bind to
            // [`Self::LIST_OPEN`] AND [`Self::LIST_CLOSE`] on the
            // closed-set outer [`Sexp`] algebra — the SAME two typed
            // constants the reader's `Token::LParen` / `Token::RParen`
            // outer-dispatch arms AND the `Self::Nil` two-char
            // rendering all route through. Adding a fifth structural
            // outer-shape (e.g. an eventual `Self::Vector` for `[…]`
            // reader syntax) lands as ONE new pair of `Sexp::VEC_OPEN`
            // / `Sexp::VEC_CLOSE` constants with the reader arms +
            // Display arms binding through them, extending the
            // outer-structural algebra by ONE axis without touching
            // this arm's `LIST_OPEN` / `LIST_CLOSE` binding.
            Self::List(xs) => {
                f.write_char(Self::LIST_OPEN)?;
                for (i, x) in xs.iter().enumerate() {
                    if i > 0 {
                        f.write_str(" ")?;
                    }
                    write!(f, "{x}")?;
                }
                f.write_char(Self::LIST_CLOSE)
            }
            // The four quote-family variants share the
            // `write!(f, "<prefix>{inner}")` Display shape — all route
            // through `as_quote_form`'s typed-marker projection so the
            // per-variant prefix (`'`, `` ` ``, `,`, `,@`) binds at ONE
            // site on the closed-set `QuoteForm` algebra and the
            // recursive `inner` rendering composes through the unified
            // Display arm. The (prefix, variant) pairing IS the structural
            // dual of the reader's `read_quoted` (prefix, variant-ctor)
            // dispatch — naming it once threads the round-trip discipline
            // through ONE rust function the reader and the Display impl
            // both bind against.
            Self::Quote(_) | Self::Quasiquote(_) | Self::Unquote(_) | Self::UnquoteSplice(_) => {
                let (qf, inner) = self.expect_quote_form();
                write!(f, "{}{inner}", qf.prefix())
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    // ── head_symbol: the operator-position projection ───────────────────
    //
    // `head_symbol` lifts the `self.as_list()?.first()?.as_symbol()` chain
    // that recurred at four soft-dispatch sites (compile.rs `compile_typed`
    // + `compile_named_from_forms`, macro_expand.rs `Expander::expand` +
    // `macro_def_from`) into ONE named query on the Sexp algebra. These
    // tests pin its contract directly; the existing dispatch tests in
    // compile.rs / macro_expand.rs are the path-uniformity guards proving
    // the four sites route through it without behavior drift.

    #[test]
    fn head_symbol_returns_operator_for_list_form() {
        // `(defpoint obs :class x)` — the operator is the head symbol.
        let form = Sexp::List(vec![
            Sexp::symbol("defpoint"),
            Sexp::symbol("obs"),
            Sexp::keyword("class"),
            Sexp::symbol("x"),
        ]);
        assert_eq!(form.head_symbol(), Some("defpoint"));
    }

    #[test]
    fn head_symbol_none_for_non_list_shapes() {
        // A bare atom is not an invocation — there is no operator position.
        assert_eq!(Sexp::symbol("foo").head_symbol(), None);
        assert_eq!(Sexp::int(5).head_symbol(), None);
        assert_eq!(Sexp::keyword("k").head_symbol(), None);
        assert_eq!(Sexp::string("s").head_symbol(), None);
        assert_eq!(Sexp::boolean(true).head_symbol(), None);
        assert_eq!(Sexp::float(1.5).head_symbol(), None);
        assert_eq!(Sexp::Nil.head_symbol(), None);
        // Quote-family wrappers are not lists at the outer layer either.
        assert_eq!(Sexp::Quote(Box::new(Sexp::symbol("x"))).head_symbol(), None);
    }

    #[test]
    fn head_symbol_none_for_empty_list() {
        // `()` has no first element to read an operator from.
        assert_eq!(Sexp::List(vec![]).head_symbol(), None);
    }

    #[test]
    fn head_symbol_none_for_non_symbol_head() {
        // A list whose head is present but not a symbol is not a dispatchable
        // invocation — the soft projection yields None (the STRICT sibling
        // `compile_from_sexp` is the one that rejects these loudly).
        assert_eq!(
            Sexp::List(vec![Sexp::int(5), Sexp::symbol("a")]).head_symbol(),
            None
        );
        assert_eq!(
            Sexp::List(vec![Sexp::keyword("kw"), Sexp::symbol("a")]).head_symbol(),
            None
        );
        assert_eq!(
            Sexp::List(vec![Sexp::string("s"), Sexp::symbol("a")]).head_symbol(),
            None
        );
        assert_eq!(
            Sexp::List(vec![
                Sexp::List(vec![Sexp::symbol("nested")]),
                Sexp::symbol("a")
            ])
            .head_symbol(),
            None
        );
        assert_eq!(
            Sexp::List(vec![Sexp::Nil, Sexp::symbol("a")]).head_symbol(),
            None
        );
    }

    #[test]
    fn head_symbol_reads_singleton_list_operator() {
        // `(defcompiler)` — a keyword-only form still has an operator head;
        // this is exactly the arity-gate input compile_named dispatches on
        // before rejecting the missing NAME.
        assert_eq!(
            Sexp::List(vec![Sexp::symbol("defcompiler")]).head_symbol(),
            Some("defcompiler")
        );
    }

    #[test]
    fn head_symbol_borrows_the_actual_head_string() {
        // The returned &str borrows the head atom's contents verbatim — no
        // copy, no normalization. Pin that a multi-segment symbol round-trips
        // unchanged so the dispatch comparison against `T::KEYWORD` is exact.
        let form = Sexp::List(vec![Sexp::symbol("defalert-policy"), Sexp::symbol("p")]);
        assert_eq!(form.head_symbol(), Some("defalert-policy"));
    }

    // ── as_call: the call-form decomposition ────────────────────────────
    //
    // `as_call` pairs `head_symbol` (the operator projection) with the
    // argument tail every dispatch site reads right after matching the
    // operator — `Some((op, &args))` for a symbol-headed list, `None` for
    // everything else. It lifts the `as_list()`-for-the-tail +
    // `head_symbol()`-for-the-operator pairing that recurred at the three
    // soft-dispatch sites (compile.rs `compile_typed` + `compile_named_
    // from_forms`, macro_expand.rs `Expander::expand`) into ONE match.
    // `head_symbol` now delegates to it, so the `as_list()?.first()?.
    // as_symbol()` chain lives in exactly one place. These tests pin the
    // decomposition's contract directly; the existing dispatch tests in
    // compile.rs / macro_expand.rs are the path-uniformity guards proving
    // the three sites route through it without behavior drift.

    #[test]
    fn as_call_decomposes_list_form_into_operator_and_args() {
        // `(defpoint obs :class x)` — the operator is the head symbol and
        // the args are everything after it.
        let args = [
            Sexp::symbol("obs"),
            Sexp::keyword("class"),
            Sexp::symbol("x"),
        ];
        let form = Sexp::List(
            std::iter::once(Sexp::symbol("defpoint"))
                .chain(args.iter().cloned())
                .collect(),
        );
        assert_eq!(form.as_call(), Some(("defpoint", &args[..])));
    }

    #[test]
    fn as_call_none_for_non_call_shapes() {
        // Every shape `head_symbol` rejects, `as_call` rejects identically:
        // non-lists, the empty list, and non-symbol heads have no operator
        // to apply, hence no call decomposition.
        assert_eq!(Sexp::symbol("foo").as_call(), None);
        assert_eq!(Sexp::int(5).as_call(), None);
        assert_eq!(Sexp::keyword("k").as_call(), None);
        assert_eq!(Sexp::string("s").as_call(), None);
        assert_eq!(Sexp::Nil.as_call(), None);
        assert_eq!(Sexp::Quote(Box::new(Sexp::symbol("x"))).as_call(), None);
        assert_eq!(Sexp::List(vec![]).as_call(), None);
        assert_eq!(
            Sexp::List(vec![Sexp::int(5), Sexp::symbol("a")]).as_call(),
            None
        );
        assert_eq!(
            Sexp::List(vec![Sexp::keyword("kw"), Sexp::symbol("a")]).as_call(),
            None
        );
    }

    #[test]
    fn as_call_yields_empty_args_for_singleton_list() {
        // `(defcompiler)` — a keyword-only form decomposes to its operator
        // with an EMPTY argument tail. This is exactly the arity-gate input
        // `compile_named_from_forms` dispatches on before rejecting the
        // missing NAME via `rest.split_first()` returning `None`.
        assert_eq!(
            Sexp::List(vec![Sexp::symbol("defcompiler")]).as_call(),
            Some(("defcompiler", &[][..]))
        );
    }

    #[test]
    fn as_call_args_are_exactly_the_tail_after_the_operator() {
        // The args slice borrows `&list[1..]` verbatim — the head is
        // excluded, every following element is included in order.
        let form = Sexp::List(vec![
            Sexp::symbol("defmonitor"),
            Sexp::symbol("cpu"),
            Sexp::keyword("threshold"),
            Sexp::int(90),
        ]);
        let (op, args) = form.as_call().expect("symbol-headed list decomposes");
        assert_eq!(op, "defmonitor");
        assert_eq!(args.len(), 3);
        assert_eq!(args[0], Sexp::symbol("cpu"));
        assert_eq!(args[2], Sexp::int(90));
    }

    #[test]
    fn head_symbol_is_the_operator_projection_of_as_call() {
        // The structural relationship the lift establishes: `head_symbol`
        // is `as_call().map(|(h, _)| h)`. Pin it across every shape so a
        // regression that drifts one query's head-recognition from the
        // other — e.g. `as_call` accepting a keyword head that `head_symbol`
        // still rejects — fails loudly. The two share ONE chain.
        let shapes = [
            Sexp::symbol("foo"),
            Sexp::int(5),
            Sexp::keyword("k"),
            Sexp::Nil,
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::int(5), Sexp::symbol("a")]),
            Sexp::List(vec![Sexp::symbol("defpoint"), Sexp::symbol("p")]),
            Sexp::List(vec![Sexp::symbol("solo")]),
        ];
        for s in &shapes {
            assert_eq!(
                s.head_symbol(),
                s.as_call().map(|(h, _)| h),
                "head_symbol must equal the operator component of as_call for {s}"
            );
        }
    }

    // ── as_call_to: the keyword-typed call decomposition ────────────────
    //
    // `as_call_to(keyword)` answers "is this a call to ONE specific
    // operator, and what are its arguments?" — the keyword-aware sibling
    // of `as_call`. It lifts the `as_call() + head == T::KEYWORD` two-step
    // chain that recurred at the two `compile.rs` dispatch sites
    // (`compile_typed` and `compile_named_from_forms`) into ONE structural
    // query on the Sexp algebra. The tests below pin its contract
    // directly; the existing `compile_*` tests are the path-uniformity
    // guards proving the two production sites route through it without
    // behavior drift.

    #[test]
    fn as_call_to_returns_args_for_matching_head() {
        // `(defmonitor :name "x")` — head is the exact symbol `defmonitor`,
        // so `as_call_to("defmonitor")` returns `Some(args)` with the tail
        // after the head verbatim.
        let form = Sexp::List(vec![
            Sexp::symbol("defmonitor"),
            Sexp::keyword("name"),
            Sexp::string("x"),
        ]);
        let args = form
            .as_call_to("defmonitor")
            .expect("matching head must yield Some(args)");
        assert_eq!(args.len(), 2);
        assert_eq!(args[0], Sexp::keyword("name"));
        assert_eq!(args[1], Sexp::string("x"));
    }

    #[test]
    fn as_call_to_returns_none_for_mismatched_head() {
        // `(defmonitor …)` against keyword `"defpoint"` — same form is a
        // call (so `as_call().is_some()`), but the head doesn't equal the
        // requested keyword. `as_call_to` is the keyword-typed projection,
        // so it yields `None` exactly when the head doesn't match. Pin the
        // gate: the two pre-lift inline sites both rejected this case via
        // `if head != T::KEYWORD { continue }` / `if head == T::KEYWORD`,
        // and the lifted primitive must reject identically.
        let form = Sexp::List(vec![
            Sexp::symbol("defmonitor"),
            Sexp::keyword("name"),
            Sexp::string("x"),
        ]);
        assert!(form.as_call().is_some());
        assert_eq!(form.as_call_to("defpoint"), None);
        assert_eq!(form.as_call_to(""), None);
        assert_eq!(form.as_call_to("DEFMONITOR"), None);
    }

    #[test]
    fn as_call_to_yields_empty_args_for_singleton_matching_call() {
        // `(defcompiler)` against keyword `"defcompiler"` — the head
        // matches and the argument tail is the empty slice. Pin the
        // empty-tail posture: this is exactly the input
        // `compile_named_from_forms` dispatches on before rejecting the
        // missing NAME via `rest.split_first()` returning `None`, so the
        // lifted primitive must yield `Some(&[])` here (NOT `None`) so
        // the downstream split-first gate fires structurally.
        let form = Sexp::List(vec![Sexp::symbol("defcompiler")]);
        assert_eq!(form.as_call_to("defcompiler"), Some(&[][..]));
    }

    #[test]
    fn as_call_to_returns_none_for_non_call_shapes() {
        // Every shape `as_call` rejects, `as_call_to` rejects identically
        // regardless of the requested keyword: non-lists, the empty list,
        // and non-symbol heads have no operator to compare to. Pin
        // path-uniformity with the `as_call` sibling so a regression that
        // narrows the keyword-typed projection to admit a shape the bare
        // soft projection rejected (e.g. accepting a keyword head when
        // `keyword` matches the keyword's symbol-string projection) fails
        // here.
        let shapes = [
            Sexp::symbol("foo"),
            Sexp::int(5),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::boolean(true),
            Sexp::float(1.5),
            Sexp::Nil,
            Sexp::Quote(Box::new(Sexp::symbol("foo"))),
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::int(5), Sexp::symbol("a")]),
            Sexp::List(vec![Sexp::keyword("foo"), Sexp::symbol("a")]),
            Sexp::List(vec![Sexp::string("foo"), Sexp::symbol("a")]),
        ];
        for s in &shapes {
            assert_eq!(
                s.as_call_to("foo"),
                None,
                "non-call shape must yield None for any keyword, got Some for {s}"
            );
            assert_eq!(s.as_call_to("anything"), None);
        }
    }

    #[test]
    fn as_call_to_args_borrow_is_same_pointer_as_as_call_tail() {
        // The structural identity binding `as_call_to` to its `as_call`
        // sibling: on the matching-head path, the returned `args` slice IS
        // the same `&[Sexp]` slice `as_call` would return as the tail
        // component. Pin pointer equality so a regression that
        // re-allocates or copies the tail in the keyword-typed projection
        // fails loudly — the soft-projection contract is borrow, not
        // clone, AND `as_call_to` inherits the contract verbatim from
        // `as_call`.
        let form = Sexp::List(vec![
            Sexp::symbol("defmonitor"),
            Sexp::keyword("name"),
            Sexp::string("x"),
        ]);
        let (_, via_as_call) = form.as_call().expect("call shape");
        let via_as_call_to = form
            .as_call_to("defmonitor")
            .expect("matching keyword shape");
        assert!(
            std::ptr::eq(via_as_call.as_ptr(), via_as_call_to.as_ptr()),
            "as_call_to args must borrow the SAME slice as as_call's tail"
        );
        assert_eq!(via_as_call.len(), via_as_call_to.len());
    }

    #[test]
    fn as_call_to_is_the_keyword_typed_projection_of_as_call() {
        // The structural identity the lift establishes:
        //   `as_call_to(k) == as_call().and_then(|(h, args)| (h == k).then_some(args))`
        //   `as_call_to(k).is_some() == (head_symbol() == Some(k))`
        // Pin both across every shape so a regression that drifts the
        // keyword-typed projection from its closed-form definition fails
        // loudly. The three soft-projection primitives — `head_symbol`,
        // `as_call`, `as_call_to` — must agree on operator-position
        // recognition at every shape they share.
        let shapes = [
            Sexp::symbol("foo"),
            Sexp::int(5),
            Sexp::keyword("k"),
            Sexp::Nil,
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::int(5), Sexp::symbol("a")]),
            Sexp::List(vec![Sexp::symbol("defpoint"), Sexp::symbol("p")]),
            Sexp::List(vec![Sexp::symbol("defmonitor"), Sexp::keyword("name")]),
            Sexp::List(vec![Sexp::symbol("solo")]),
        ];
        for s in &shapes {
            for k in ["defpoint", "defmonitor", "solo", "foo", ""] {
                let via_chain = s.as_call().and_then(|(h, args)| (h == k).then_some(args));
                assert_eq!(
                    s.as_call_to(k),
                    via_chain,
                    "as_call_to({k:?}) must equal as_call+filter for {s}"
                );
                assert_eq!(
                    s.as_call_to(k).is_some(),
                    s.head_symbol() == Some(k),
                    "as_call_to({k:?}).is_some() must equal (head_symbol() == Some({k:?})) for {s}"
                );
            }
        }
    }

    // ── as_call_to_any: the typed-decoded call decomposition ────────────
    //
    // `as_call_to_any(decode)` answers "is this a call whose head decodes
    // through `decode`, and what are its arguments?" — the closure-typed
    // sibling of `as_call_to`. It lifts the
    // `as_list() + head_symbol() + decode(head)` three-step chain that
    // recurred at the macro-expander's `macro_def_from` site (the typed
    // `MacroDefHead::from_keyword` dispatch surface) into ONE structural
    // query on the Sexp algebra. The tests below pin its contract
    // directly; the existing macro-expansion tests are the path-
    // uniformity guards proving the production site routes through it
    // without behavior drift.
    //
    // The test classifier `Op::from_keyword` mirrors `MacroDefHead::from_keyword`
    // — a closed-set typed enum projection from a `&str` head — so the
    // tests cover the macro-expander's real consumer shape rather than a
    // synthetic predicate.
    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    enum Op {
        Quote,
        If,
        Let,
    }
    impl Op {
        fn from_keyword(head: &str) -> Option<Self> {
            match head {
                "quote" => Some(Self::Quote),
                "if" => Some(Self::If),
                "let" => Some(Self::Let),
                _ => None,
            }
        }
    }

    #[test]
    fn as_call_to_any_returns_decoded_head_and_args_for_matching_head() {
        // `(if c t e)` — head `if` decodes to `Op::If`, args are the
        // three-element tail verbatim. Pin both halves of the returned
        // tuple: the decoded typed witness AND the borrowed args slice.
        let form = Sexp::List(vec![
            Sexp::symbol("if"),
            Sexp::symbol("c"),
            Sexp::symbol("t"),
            Sexp::symbol("e"),
        ]);
        let (op, args) = form
            .as_call_to_any(Op::from_keyword)
            .expect("matching head must yield Some((decoded, args))");
        assert_eq!(op, Op::If);
        assert_eq!(args.len(), 3);
        assert_eq!(args[0], Sexp::symbol("c"));
        assert_eq!(args[2], Sexp::symbol("e"));
    }

    #[test]
    fn as_call_to_any_returns_none_when_decoder_rejects_head() {
        // `(defmonitor :name "x")` — head `defmonitor` is a valid symbol
        // (so `as_call().is_some()`), but `Op::from_keyword` rejects it
        // (it's not one of the closed `{quote, if, let}` set). Pin the
        // gate: `as_call_to_any` yields `None` exactly when the decoder
        // rejects the head, mirroring how the pre-lift inline chain in
        // `macro_def_from` returned `Ok(None)` when
        // `MacroDefHead::from_keyword(head_str)` returned `None`.
        let form = Sexp::List(vec![
            Sexp::symbol("defmonitor"),
            Sexp::keyword("name"),
            Sexp::string("x"),
        ]);
        assert!(form.as_call().is_some());
        assert!(form.as_call_to_any(Op::from_keyword).is_none());
    }

    #[test]
    fn as_call_to_any_yields_empty_args_for_singleton_decoded_call() {
        // `(quote)` against the classifier — head decodes to `Op::Quote`
        // and the argument tail is the empty slice. Pin the empty-tail
        // posture: a downstream arity gate (analogous to
        // `if list.len() < 4` inside `macro_def_from`) dispatches on
        // `args.is_empty()` AFTER the decoder accepts the head; the
        // helper must yield `Some((decoded, &[]))` (NOT `None`) so that
        // gate fires structurally.
        let form = Sexp::List(vec![Sexp::symbol("quote")]);
        let (op, args) = form
            .as_call_to_any(Op::from_keyword)
            .expect("singleton matching call must decompose");
        assert_eq!(op, Op::Quote);
        assert_eq!(args.len(), 0);
    }

    #[test]
    fn as_call_to_any_returns_none_for_non_call_shapes() {
        // Every shape `as_call` rejects, `as_call_to_any` rejects
        // identically regardless of the decoder: non-lists, the empty
        // list, and non-symbol heads have no operator string to feed
        // the decoder. Pin path-uniformity with the `as_call` sibling so
        // a regression that admits a non-call shape (e.g. accepting a
        // bare symbol via a permissive decoder) fails here. Pass
        // `Some` for every input to prove the call-shape gate fires
        // BEFORE the decoder runs — the decoder cannot rescue a
        // non-call.
        let shapes = [
            Sexp::symbol("foo"),
            Sexp::int(5),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::boolean(true),
            Sexp::float(1.5),
            Sexp::Nil,
            Sexp::Quote(Box::new(Sexp::symbol("foo"))),
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::int(5), Sexp::symbol("a")]),
            Sexp::List(vec![Sexp::keyword("foo"), Sexp::symbol("a")]),
            Sexp::List(vec![Sexp::string("foo"), Sexp::symbol("a")]),
        ];
        for s in &shapes {
            // The promiscuous decoder accepts every &str head, so the
            // only way to see `None` here is if the call-shape gate
            // rejects the shape upstream of the decoder.
            assert_eq!(
                s.as_call_to_any(|h: &str| Some(h.to_string())),
                None,
                "non-call shape must yield None even for a promiscuous decoder, got Some for {s}"
            );
        }
    }

    #[test]
    fn as_call_to_any_args_borrow_is_same_pointer_as_as_call_tail() {
        // The structural identity binding `as_call_to_any` to its
        // `as_call` sibling: on the decoded path, the returned `args`
        // slice IS the same `&[Sexp]` slice `as_call` would return as
        // the tail component. Pin pointer equality so a regression that
        // re-allocates or copies the tail in the typed-decoded
        // projection fails loudly — the soft-projection contract is
        // borrow, not clone, AND `as_call_to_any` inherits the contract
        // verbatim from `as_call`. Parallel to the
        // `as_call_to_args_borrow_is_same_pointer_as_as_call_tail` pin
        // for `as_call_to`.
        let form = Sexp::List(vec![
            Sexp::symbol("if"),
            Sexp::symbol("c"),
            Sexp::symbol("t"),
        ]);
        let (_, via_as_call) = form.as_call().expect("call shape");
        let (_, via_as_call_to_any) = form
            .as_call_to_any(Op::from_keyword)
            .expect("decoded shape");
        assert!(
            std::ptr::eq(via_as_call.as_ptr(), via_as_call_to_any.as_ptr()),
            "as_call_to_any args must borrow the SAME slice as as_call's tail"
        );
        assert_eq!(via_as_call.len(), via_as_call_to_any.len());
    }

    #[test]
    fn as_call_to_any_is_the_decoded_projection_of_as_call() {
        // The structural identity the lift establishes:
        //   `as_call_to_any(decode) == as_call().and_then(|(h, args)| decode(h).map(|d| (d, args)))`
        //   `as_call_to_any(decode).is_some() == as_call().map_or(false, |(h, _)| decode(h).is_some())`
        // Pin both across every shape so a regression that drifts the
        // typed-decoded projection from its closed-form definition fails
        // loudly. The four soft-projection primitives — `head_symbol`,
        // `as_call`, `as_call_to`, `as_call_to_any` — must agree on
        // operator-position recognition at every shape they share.
        let shapes = [
            Sexp::symbol("foo"),
            Sexp::int(5),
            Sexp::keyword("k"),
            Sexp::Nil,
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::int(5), Sexp::symbol("a")]),
            Sexp::List(vec![Sexp::symbol("if"), Sexp::symbol("c")]),
            Sexp::List(vec![Sexp::symbol("quote"), Sexp::symbol("x")]),
            Sexp::List(vec![Sexp::symbol("let"), Sexp::List(vec![])]),
            Sexp::List(vec![Sexp::symbol("defpoint"), Sexp::symbol("p")]),
            Sexp::List(vec![Sexp::symbol("solo")]),
        ];
        for s in &shapes {
            let via_chain = s
                .as_call()
                .and_then(|(h, args)| Op::from_keyword(h).map(|d| (d, args)));
            assert_eq!(
                s.as_call_to_any(Op::from_keyword),
                via_chain,
                "as_call_to_any(Op::from_keyword) must equal as_call+decode for {s}"
            );
        }
    }

    #[test]
    fn as_call_to_any_subsumes_as_call_to_via_unit_decoder() {
        // The closed-form composition `as_call_to(k) == as_call_to_any
        // (|h| (h == k).then_some(())).map(|(_, a)| a)` (modulo the
        // discarded `()` decoded witness). Pin it across every shape ×
        // keyword pair so a regression that drifts the typed-decoded
        // projection from its single-keyword sibling fails loudly. This
        // makes the family closure: `as_call_to` is the trivial-decoder
        // instance of `as_call_to_any`, and naming both lets each
        // consumer pick the projection that fits its call site.
        let shapes = [
            Sexp::symbol("foo"),
            Sexp::Nil,
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::int(5), Sexp::symbol("a")]),
            Sexp::List(vec![Sexp::symbol("if"), Sexp::symbol("c")]),
            Sexp::List(vec![Sexp::symbol("defpoint"), Sexp::symbol("p")]),
        ];
        for s in &shapes {
            for k in ["if", "defpoint", "let", "foo", "", "DEFPOINT"] {
                let via_unit_decoder = s
                    .as_call_to_any(|h: &str| (h == k).then_some(()))
                    .map(|(_, args)| args);
                assert_eq!(
                    s.as_call_to(k),
                    via_unit_decoder,
                    "as_call_to({k:?}) must equal as_call_to_any+unit-decoder for {s}"
                );
            }
        }
    }

    // ── iter_calls_to: the slice-side projection of as_call_to ──────────
    //
    // `iter_calls_to(forms, keyword)` lifts the per-form projection
    // `as_call_to` onto a `&[Sexp]`, yielding the args tails of every
    // matching form in source order — the substrate's typed-keyword
    // filter over a batch of forms. The two inline `for form in
    // &expanded { if let Some(args) = form.as_call_to(T::KEYWORD) { … } }`
    // walks at the `compile_typed` + `compile_named_from_forms` dispatch
    // sites (compile.rs) collapse to ONE `iter_calls_to(&expanded,
    // T::KEYWORD)` call. Tests pin the slice-side primitive's contract
    // directly; the existing dispatch tests in compile.rs are the
    // path-uniformity guards proving the two consumers route through it
    // without behavior drift.

    #[test]
    fn iter_calls_to_yields_args_for_every_matching_form_in_slice() {
        // Three forms: two match "defmonitor", one matches "defalert".
        // `iter_calls_to("defmonitor")` yields the two matching args
        // slices in source order — the matched forms' tails verbatim,
        // skipping the non-matching `defalert` form silently.
        let forms = vec![
            Sexp::List(vec![
                Sexp::symbol("defmonitor"),
                Sexp::keyword("name"),
                Sexp::string("a"),
            ]),
            Sexp::List(vec![
                Sexp::symbol("defalert"),
                Sexp::keyword("name"),
                Sexp::string("p"),
            ]),
            Sexp::List(vec![
                Sexp::symbol("defmonitor"),
                Sexp::keyword("name"),
                Sexp::string("b"),
            ]),
        ];
        let args: Vec<&[Sexp]> = iter_calls_to(&forms, "defmonitor").collect();
        assert_eq!(args.len(), 2);
        assert_eq!(args[0], &[Sexp::keyword("name"), Sexp::string("a")][..]);
        assert_eq!(args[1], &[Sexp::keyword("name"), Sexp::string("b")][..]);
    }

    #[test]
    fn iter_calls_to_skips_every_non_call_shape_silently() {
        // Every shape `as_call_to` rejects, `iter_calls_to` skips: non-
        // lists (atoms across all 6 atom kinds, Nil, quote-family
        // wrapper), the empty list, and non-symbol-head lists. Pin
        // path-uniformity with the per-form sibling: passing ANY keyword
        // against a slice of non-call shapes yields zero items. Closes
        // the soft-projection posture at the slice level — a regression
        // that admits a non-call shape (e.g. accepting a bare symbol
        // whose name matches the keyword) fails here.
        let forms = vec![
            Sexp::symbol("foo"),
            Sexp::int(5),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::boolean(true),
            Sexp::float(1.5),
            Sexp::Nil,
            Sexp::Quote(Box::new(Sexp::symbol("foo"))),
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::int(5), Sexp::symbol("a")]),
            Sexp::List(vec![Sexp::keyword("foo"), Sexp::symbol("a")]),
        ];
        for k in ["foo", "anything", "", "defpoint"] {
            let args: Vec<&[Sexp]> = iter_calls_to(&forms, k).collect();
            assert!(
                args.is_empty(),
                "non-call slice must yield zero items for keyword {k:?}, got {} items",
                args.len()
            );
        }
    }

    #[test]
    fn iter_calls_to_yields_empty_args_slice_for_singleton_matching_call() {
        // `(defcompiler)` — the head matches and the args tail is the
        // empty slice. Pin the empty-tail posture: `iter_calls_to` must
        // yield `Some(&[])` for the matching singleton (NOT skip it),
        // mirroring `as_call_to`'s contract — the (possibly-empty) args
        // slice on a match, NOT `None` on an empty tail. This is exactly
        // the input `compile_named_from_forms` dispatches on before
        // rejecting the missing NAME via `rest.split_first()`'s `None`.
        let forms = vec![Sexp::List(vec![Sexp::symbol("defcompiler")])];
        let args: Vec<&[Sexp]> = iter_calls_to(&forms, "defcompiler").collect();
        assert_eq!(args.len(), 1);
        assert_eq!(args[0], &[][..]);
    }

    #[test]
    fn iter_calls_to_yields_nothing_for_empty_slice() {
        // An empty forms slice yields zero items regardless of keyword.
        // Pin the slice-side primitive's degenerate boundary: empty in,
        // empty out — the iterator is fused-empty without consulting
        // `as_call_to` at all.
        let forms: Vec<Sexp> = vec![];
        let mut iter = iter_calls_to(&forms, "anything");
        assert!(iter.next().is_none());
    }

    #[test]
    fn iter_calls_to_yields_nothing_when_keyword_matches_no_form() {
        // A slice of valid call forms whose heads none match the
        // requested keyword yields zero items. Pin path-uniformity with
        // the per-form sibling: every form's `as_call_to(missing)` is
        // `None`, so the slice-side iterator yields nothing — the filter
        // fires uniformly across the batch.
        let forms = vec![
            Sexp::List(vec![Sexp::symbol("defmonitor"), Sexp::int(1)]),
            Sexp::List(vec![Sexp::symbol("defalert"), Sexp::int(2)]),
            Sexp::List(vec![Sexp::symbol("defpoint"), Sexp::int(3)]),
        ];
        let args: Vec<&[Sexp]> = iter_calls_to(&forms, "missing").collect();
        assert!(args.is_empty());
    }

    #[test]
    fn iter_calls_to_args_borrow_is_same_pointer_as_per_form_as_call_to_tail() {
        // The structural identity binding `iter_calls_to` to its per-form
        // sibling: each yielded `&[Sexp]` IS the same slice `as_call_to`
        // would return as the tail component for the corresponding form
        // (pinned via `std::ptr::eq` on `as_ptr()`). The soft-projection
        // contract is borrow, not clone, AND `iter_calls_to` inherits the
        // contract verbatim from `as_call_to`. Parallel to the
        // `as_call_to_args_borrow_is_same_pointer_as_as_call_tail` pin
        // for `as_call_to`.
        let forms = vec![Sexp::List(vec![
            Sexp::symbol("defmonitor"),
            Sexp::keyword("name"),
            Sexp::string("a"),
        ])];
        let via_iter: &[Sexp] = iter_calls_to(&forms, "defmonitor")
            .next()
            .expect("one match");
        let via_per_form: &[Sexp] = forms[0].as_call_to("defmonitor").expect("one match");
        assert!(
            std::ptr::eq(via_iter.as_ptr(), via_per_form.as_ptr()),
            "iter_calls_to args must borrow the SAME slice as as_call_to's tail"
        );
        assert_eq!(via_iter.len(), via_per_form.len());
    }

    #[test]
    fn iter_calls_to_is_the_slice_side_projection_of_as_call_to() {
        // The structural identity the lift establishes:
        //   `iter_calls_to(forms, k) == forms.iter().filter_map(|f| f.as_call_to(k))`
        // Pin shape AND ordering AND pointer-identity across mixed inputs
        // and a range of keywords (including matching, non-matching, and
        // edge-case empty/case-mismatched keywords) so a regression that
        // drifts the slice-side projection from its closed-form
        // definition fails loudly. The five soft-projection primitives —
        // `head_symbol`, `as_call`, `as_call_to`, `as_call_to_any`, AND
        // `iter_calls_to` — must agree on operator-position recognition
        // at every shape/slice they share.
        let forms = vec![
            Sexp::symbol("foo"),
            Sexp::List(vec![Sexp::symbol("a"), Sexp::int(1)]),
            Sexp::Nil,
            Sexp::List(vec![Sexp::symbol("a"), Sexp::int(2)]),
            Sexp::int(99),
            Sexp::List(vec![Sexp::symbol("b"), Sexp::int(3)]),
            Sexp::List(vec![Sexp::symbol("a")]),
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::keyword("a"), Sexp::int(4)]),
        ];
        for k in ["a", "b", "c", "", "A"] {
            let via_iter: Vec<&[Sexp]> = iter_calls_to(&forms, k).collect();
            let via_chain: Vec<&[Sexp]> = forms.iter().filter_map(|f| f.as_call_to(k)).collect();
            assert_eq!(
                via_iter.len(),
                via_chain.len(),
                "len drift for keyword {k:?}"
            );
            for (a, b) in via_iter.iter().zip(via_chain.iter()) {
                assert!(
                    std::ptr::eq(a.as_ptr(), b.as_ptr()),
                    "ptr drift at keyword {k:?}: iter slice does not borrow the SAME tail as the per-form chain"
                );
                assert_eq!(a.len(), b.len(), "len drift at keyword {k:?}");
            }
        }
    }

    // ── iter_calls_to_any: the typed-decoded slice-side projection ──────
    //
    // `iter_calls_to_any(forms, decode)` lifts the per-form projection
    // `as_call_to_any` onto a `&[Sexp]`, yielding the `(decoded,
    // &[Sexp])` pair of every form whose head decodes through `decode`
    // — the substrate's typed-decoded filter over a batch of forms,
    // closing the (per-form, slice-side) × (keyword, classifier) 2×2
    // of soft-dispatch primitives at the slice-side classifier corner.
    // The slice-side keyword projection `iter_calls_to` now routes
    // through THIS primitive with a constant-keyword decoder, so the
    // filter-and-fuse implementation lives at ONE site on the slice
    // algebra. Tests pin the slice-side primitive's contract directly
    // alongside the (slice-side keyword, slice-side classifier)
    // composition law that the keyword projection's re-routing
    // establishes.

    #[test]
    fn iter_calls_to_any_yields_decoded_pair_for_every_matching_form_in_slice() {
        // Three forms: two decode through `Op::from_keyword`, one does
        // not (the head `"defalert"` is outside the closed set). The
        // typed-decoded slice walk yields the `(decoded, args)` pair
        // for each matching form in source order, skipping non-decoding
        // forms silently — parallel to how `iter_calls_to` yields ONLY
        // the args slice for keyword-matching forms.
        #[derive(Debug, PartialEq, Eq)]
        enum Op {
            Defmonitor,
            Defpoint,
        }
        impl Op {
            fn from_keyword(h: &str) -> Option<Self> {
                match h {
                    "defmonitor" => Some(Self::Defmonitor),
                    "defpoint" => Some(Self::Defpoint),
                    _ => None,
                }
            }
        }
        let forms = vec![
            Sexp::List(vec![
                Sexp::symbol("defmonitor"),
                Sexp::keyword("name"),
                Sexp::string("a"),
            ]),
            Sexp::List(vec![
                Sexp::symbol("defalert"),
                Sexp::keyword("name"),
                Sexp::string("p"),
            ]),
            Sexp::List(vec![
                Sexp::symbol("defpoint"),
                Sexp::keyword("name"),
                Sexp::string("b"),
            ]),
        ];
        let decoded: Vec<(Op, &[Sexp])> = iter_calls_to_any(&forms, Op::from_keyword).collect();
        assert_eq!(decoded.len(), 2);
        assert_eq!(decoded[0].0, Op::Defmonitor);
        assert_eq!(
            decoded[0].1,
            &[Sexp::keyword("name"), Sexp::string("a")][..]
        );
        assert_eq!(decoded[1].0, Op::Defpoint);
        assert_eq!(
            decoded[1].1,
            &[Sexp::keyword("name"), Sexp::string("b")][..]
        );
    }

    #[test]
    fn iter_calls_to_any_skips_every_shape_per_form_sibling_rejects() {
        // Every shape `as_call_to_any` rejects, `iter_calls_to_any`
        // skips: non-list shapes, the empty list, non-symbol-head
        // lists, AND lists whose head is a symbol the decoder rejects.
        // Pin the soft-projection contract at the slice level —
        // parallel to `iter_calls_to_skips_every_non_call_shape_silently`
        // but with the decoder rejection axis added so the per-form
        // sibling's two rejection sources (shape-level + decoder-level)
        // both route through the slice-side filter uniformly.
        let forms = vec![
            Sexp::symbol("foo"),
            Sexp::int(5),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::boolean(true),
            Sexp::float(1.5),
            Sexp::Nil,
            Sexp::Quote(Box::new(Sexp::symbol("foo"))),
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::int(5), Sexp::symbol("a")]),
            Sexp::List(vec![Sexp::keyword("foo"), Sexp::symbol("a")]),
            // A call whose head IS a symbol but the decoder rejects —
            // this is the decoder-level rejection axis the per-form
            // sibling's classifier closure adds beyond the keyword
            // sibling's `head == k` axis.
            Sexp::List(vec![Sexp::symbol("unknown-head"), Sexp::int(1)]),
        ];
        let decoded: Vec<(&'static str, &[Sexp])> =
            iter_calls_to_any(&forms, |_h: &str| None::<&'static str>).collect();
        assert!(
            decoded.is_empty(),
            "non-call / decoder-rejecting slice must yield zero items, got {} items",
            decoded.len()
        );
    }

    #[test]
    fn iter_calls_to_any_yields_empty_args_slice_for_singleton_decoded_call() {
        // `(defcompiler)` decoded through a classifier that accepts
        // the head — the args tail is the empty slice. Pin the
        // empty-tail posture: the typed-decoded slice walk must yield
        // `(decoded, &[])` for the matching singleton (NOT skip it),
        // mirroring the per-form sibling's contract — the
        // (possibly-empty) args slice on a decoded match, NOT `None`
        // on an empty tail. Parallel to
        // `iter_calls_to_yields_empty_args_slice_for_singleton_matching_call`
        // for the keyword sibling and
        // `as_call_to_any_yields_empty_args_for_singleton_decoded_call`
        // for the per-form sibling.
        let forms = vec![Sexp::List(vec![Sexp::symbol("defcompiler")])];
        let decoded: Vec<(&'static str, &[Sexp])> = iter_calls_to_any(&forms, |h: &str| {
            (h == "defcompiler").then_some("defcompiler")
        })
        .collect();
        assert_eq!(decoded.len(), 1);
        assert_eq!(decoded[0].0, "defcompiler");
        assert_eq!(decoded[0].1, &[][..]);
    }

    #[test]
    fn iter_calls_to_any_yields_nothing_for_empty_slice() {
        // An empty forms slice yields zero items regardless of
        // decoder. Pin the slice-side primitive's degenerate boundary:
        // empty in, empty out — the iterator is fused-empty without
        // consulting `as_call_to_any` at all. The decoder's body must
        // never run (we assert with an explicitly-panicking closure
        // body to prove the fused-empty contract holds before the
        // per-form sibling is consulted). Parallel to
        // `iter_calls_to_yields_nothing_for_empty_slice` for the
        // keyword sibling.
        let forms: Vec<Sexp> = vec![];
        let mut iter = iter_calls_to_any(&forms, |_h: &str| -> Option<()> {
            panic!("decoder must not run on an empty forms slice")
        });
        assert!(iter.next().is_none());
    }

    #[test]
    fn iter_calls_to_any_args_borrow_is_same_pointer_as_per_form_as_call_to_any_tail() {
        // The structural identity binding `iter_calls_to_any` to its
        // per-form sibling: each yielded `&[Sexp]` IS the same slice
        // `as_call_to_any` would return as the tail component for the
        // corresponding form (pinned via `std::ptr::eq` on `as_ptr()`).
        // The soft-projection contract is borrow, not clone, AND
        // `iter_calls_to_any` inherits the contract verbatim from
        // `as_call_to_any`. Parallel to the
        // `iter_calls_to_args_borrow_is_same_pointer_as_per_form_as_call_to_tail`
        // pin for the keyword sibling and the
        // `as_call_to_any_args_borrow_is_same_pointer_as_as_call_tail`
        // pin for the per-form sibling.
        let forms = vec![Sexp::List(vec![
            Sexp::symbol("defmonitor"),
            Sexp::keyword("name"),
            Sexp::string("a"),
        ])];
        let (_, via_iter): (&'static str, &[Sexp]) = iter_calls_to_any(&forms, |h: &str| {
            (h == "defmonitor").then_some("defmonitor")
        })
        .next()
        .expect("one decoded match");
        let (_, via_per_form): (&'static str, &[Sexp]) = forms[0]
            .as_call_to_any(|h: &str| (h == "defmonitor").then_some("defmonitor"))
            .expect("one decoded match");
        assert!(
            std::ptr::eq(via_iter.as_ptr(), via_per_form.as_ptr()),
            "iter_calls_to_any args must borrow the SAME slice as as_call_to_any's tail"
        );
        assert_eq!(via_iter.len(), via_per_form.len());
    }

    #[test]
    fn iter_calls_to_any_is_the_slice_side_projection_of_as_call_to_any() {
        // The structural identity the lift establishes:
        //   iter_calls_to_any(forms, decode) ==
        //       forms.iter().filter_map(|f| f.as_call_to_any(&mut decode))
        // Pin shape AND ordering AND pointer-identity across mixed
        // inputs and a range of decoders (closed-set classifier,
        // always-accept identity, always-reject `None`, partial
        // closed-set on a single head) so a regression that drifts
        // the slice-side projection from its closed-form definition
        // fails loudly. The six soft-projection primitives —
        // `head_symbol`, `as_call`, `as_call_to`, `as_call_to_any`,
        // `iter_calls_to`, AND `iter_calls_to_any` — must agree on
        // operator-position recognition at every shape/slice they
        // share. Parallel to
        // `iter_calls_to_is_the_slice_side_projection_of_as_call_to`
        // for the keyword sibling.
        let forms = vec![
            Sexp::symbol("foo"),
            Sexp::List(vec![Sexp::symbol("a"), Sexp::int(1)]),
            Sexp::Nil,
            Sexp::List(vec![Sexp::symbol("a"), Sexp::int(2)]),
            Sexp::int(99),
            Sexp::List(vec![Sexp::symbol("b"), Sexp::int(3)]),
            Sexp::List(vec![Sexp::symbol("a")]),
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::keyword("a"), Sexp::int(4)]),
            Sexp::List(vec![Sexp::symbol("c"), Sexp::int(5)]),
        ];
        // Closed-set classifier: accept "a" and "c", reject everything
        // else (including the call whose head is "b", to pin the
        // decoder-level rejection axis the keyword sibling does not
        // have).
        let decode_set =
            |h: &str| -> Option<&'static str> { matches!(h, "a" | "c").then_some("ac") };
        let via_iter: Vec<(&'static str, &[Sexp])> =
            iter_calls_to_any(&forms, decode_set).collect();
        let via_chain: Vec<(&'static str, &[Sexp])> = forms
            .iter()
            .filter_map(|f| f.as_call_to_any(decode_set))
            .collect();
        assert_eq!(
            via_iter.len(),
            via_chain.len(),
            "len drift between slice-side and per-form-chain"
        );
        for (a, b) in via_iter.iter().zip(via_chain.iter()) {
            assert_eq!(a.0, b.0, "decoded drift");
            assert!(
                std::ptr::eq(a.1.as_ptr(), b.1.as_ptr()),
                "ptr drift: slice-side does not borrow the SAME tail as the per-form chain"
            );
            assert_eq!(a.1.len(), b.1.len(), "len drift");
        }
    }

    #[test]
    fn iter_calls_to_routes_through_iter_calls_to_any_via_constant_classifier_composition() {
        // The post-lift composition law binding the slice-side
        // keyword projection to the slice-side classifier projection:
        //
        //   iter_calls_to(forms, k) ==
        //       iter_calls_to_any(forms, |h| (h == k).then_some(())).map(|(_, a)| a)
        //
        // Pin shape AND ordering AND pointer-identity across a mixed
        // slice and three representative keywords (matching some,
        // matching none, edge-case empty string) so a regression that
        // drifts `iter_calls_to`'s body away from the typed-decoded
        // routing (e.g. re-inlines the `forms.iter().filter_map(|f|
        // f.as_call_to(keyword))` triple directly) fails loudly even
        // though the rendered slice-of-slices would still match the
        // keyword sibling's output. The pointer-equality axis is
        // load-bearing: a regression that re-derives the filter at
        // both sites would yield byte-identical slices but with
        // distinct closure-capture state, which the
        // pointer-identity check rejects only because both routes
        // share the SAME underlying form-tail borrow chain.
        //
        // Sibling-shape lift to prior-run `UnquoteForm::marker` ⊂
        // `to_quote_form().prefix()` composition (commit 250c001) and
        // `AtomKind::label` ⊂ `sexp_shape().label()` composition
        // (commit 1db697f): both pin the invariant that a typed
        // subset/keyword projection is structurally derived from its
        // parent superset/classifier projection, not a parallel
        // implementation the type system happens to not catch when
        // the two drift.
        let forms = vec![
            Sexp::List(vec![Sexp::symbol("a"), Sexp::int(1)]),
            Sexp::List(vec![Sexp::symbol("b"), Sexp::int(2)]),
            Sexp::List(vec![Sexp::symbol("a"), Sexp::int(3)]),
            Sexp::List(vec![Sexp::symbol("c"), Sexp::int(4)]),
            Sexp::int(99),
        ];
        for k in ["a", "missing", ""] {
            let via_keyword: Vec<&[Sexp]> = iter_calls_to(&forms, k).collect();
            let via_classifier: Vec<&[Sexp]> =
                iter_calls_to_any(&forms, |h: &str| (h == k).then_some(()))
                    .map(|(_, a)| a)
                    .collect();
            assert_eq!(
                via_keyword.len(),
                via_classifier.len(),
                "len drift between keyword projection and classifier composition for k={k:?}"
            );
            for (a, b) in via_keyword.iter().zip(via_classifier.iter()) {
                assert!(
                    std::ptr::eq(a.as_ptr(), b.as_ptr()),
                    "ptr drift at k={k:?}: keyword projection does not share the SAME borrow with the classifier composition"
                );
                assert_eq!(a.len(), b.len(), "len drift at k={k:?}");
            }
        }
    }

    #[test]
    fn iter_calls_to_any_admits_fnmut_classifier_maintaining_state_across_batch_walk() {
        // The slice-side primitive's `FnMut` constraint (vs the
        // per-form sibling's `FnOnce`) admits a classifier that
        // captures mutable state — a counter, a registry cache, a
        // visited-set. Pin the mutable-state contract: a counter
        // closure increments once per matching form (NOT once per
        // call to `f.as_call_to_any(decode)` at every form, since
        // `as_call_to_any` short-circuits before running `decode` on
        // non-list / empty-list / non-symbol-head shapes — only forms
        // that pass the shape gate reach the decoder). The counter's
        // post-walk value pins the exact number of forms that
        // (a) passed the shape gate AND (b) had a head matching the
        // classifier's predicate.
        let forms = vec![
            Sexp::List(vec![Sexp::symbol("a"), Sexp::int(1)]),
            Sexp::int(99), // not a call — `as_call_to_any` short-circuits, decoder never runs
            Sexp::List(vec![Sexp::symbol("a"), Sexp::int(2)]),
            Sexp::List(vec![Sexp::symbol("b"), Sexp::int(3)]),
            Sexp::List(vec![]), // empty list — `as_call_to_any` short-circuits before decoder
            Sexp::List(vec![Sexp::symbol("a"), Sexp::int(4)]),
        ];
        let mut decoder_calls = 0usize;
        // Consume the iterator into a count (NOT a Vec) so the closure
        // capture of `decoder_calls` is dropped at the iterator's end,
        // releasing the mutable borrow before the post-walk assertions
        // re-read `decoder_calls` immutably. A `Vec<((), &[Sexp])>`
        // collection would inherit the closure's `'a` lifetime through
        // the `iter_calls_to_any` return type's unified lifetime
        // parameter and keep the mutable borrow live across the assert
        // (the rust-borrow-checker contract — `decoded`'s lifetime
        // ties to `min(forms, closure)` even though the items
        // themselves only borrow from `forms`).
        let decoded_count = iter_calls_to_any(&forms, |h: &str| {
            decoder_calls += 1;
            (h == "a").then_some(())
        })
        .count();
        // Three forms have head "a"; one form has head "b"; the
        // non-call shapes (Int + empty list) short-circuit before the
        // decoder runs. Decoder is called 4 times (the 4 shape-gate-
        // passing forms); yields 3 matches.
        assert_eq!(
            decoder_calls, 4,
            "decoder must run once per shape-gate-passing form"
        );
        assert_eq!(
            decoded_count, 3,
            "three forms decode through the classifier"
        );
    }

    // ── iter_named_calls_to_any / iter_named_calls_to: slice-side closure
    //    of the (slice × classifier × named) and (slice × constant × named)
    //    corners of the soft-dispatch cube. Pre-lift the named gate
    //    composition (`split_name_slot` over a classifier-decoded args
    //    tail) lived ONLY inside `Expander::expand_and_collect_named_calls_to_any`'s
    //    projection closure — the slice algebra had no named sibling to
    //    the bare [`iter_calls_to_any`]. Post-lift the gate is composed
    //    at the slice level and the Expander surface routes through it
    //    via the SAME `expand_program + iter + map + collect` pipeline
    //    the bare expander surface uses. The tests below pin the slice
    //    primitive's contract DIRECTLY — independent of the Expander
    //    surface — so a classifier-NAME consumer that already holds
    //    expanded forms (a `tatara-check` runner, an LSP buffer walker,
    //    a REPL exhaustive lister) sees the SAME `NamedFormMissingName`
    //    / `NamedFormNonSymbolName` rejection chain the Expander
    //    consumer sees through the surface method.

    #[test]
    fn iter_named_calls_to_any_yields_decoded_triple_for_every_matching_named_form_in_slice() {
        // Closed-set classifier (`Kind::{Foo, Bar}`) that rejects one head
        // out of three on a slice. Every matching form yields a
        // `Result<(Kind, &str, &[Sexp])>` triple in source order; the
        // unmatched form is skipped silently (NOT yielded as `Err`).
        // Fail-before-pass-after: this assert requires the slice
        // primitive to exist AND to yield the typed witness ALONGSIDE
        // the borrowed NAME slot AND the borrowed spec args tail — pre-
        // lift the slice algebra had no named sibling; consumers had
        // to re-derive the four-step `iter_calls_to_any(forms,
        // decode).map(|(d, args)| split_name_slot(args, k).map(|(n,
        // r)| (d, n, r)))` composition at their call site.
        #[derive(Debug, PartialEq, Eq, Clone, Copy)]
        enum Kind {
            Foo,
            Bar,
        }
        let forms = crate::reader::read(
            "(deffoo alpha 1) (defbaz gamma 2) (defbar beta 3) (deffoo delta 4)",
        )
        .unwrap();
        let yielded: Vec<(Kind, String, usize)> =
            super::iter_named_calls_to_any(&forms, |h: &str| match h {
                "deffoo" => Some((Kind::Foo, "deffoo")),
                "defbar" => Some((Kind::Bar, "defbar")),
                _ => None,
            })
            .map(|maybe_triple| {
                maybe_triple.map(|(kind, name, args)| (kind, name.to_string(), args.len()))
            })
            .collect::<crate::error::Result<Vec<_>>>()
            .expect("slice-side named-classifier walk must succeed on well-formed forms");
        assert_eq!(
            yielded,
            vec![
                (Kind::Foo, "alpha".to_string(), 1),
                (Kind::Bar, "beta".into(), 1),
                (Kind::Foo, "delta".into(), 1),
            ],
            "iter_named_calls_to_any must yield (decoded, NAME, args_len) in source order, skipping defbaz",
        );
    }

    #[test]
    fn iter_named_calls_to_any_skips_every_non_matching_form_shape_silently() {
        // Soft-projection contract: the slice primitive must skip every
        // shape the classifier rejects — non-list atoms, empty lists,
        // lists with non-symbol heads, lists with unrecognized symbol
        // heads — WITHOUT emitting the `NamedFormMissingName` /
        // `NamedFormNonSymbolName` variants. The named gate fires ONLY
        // for matched-keyword forms whose NAME slot is malformed, NEVER
        // for forms the classifier filtered out first.
        let forms = crate::reader::read(r#":kw "str" 42 () (unrecognized x) (5 y)"#).unwrap();
        let yielded: Vec<()> = super::iter_named_calls_to_any(&forms, |h: &str| {
            (h == "deffoo").then_some(((), "deffoo"))
        })
        .map(|maybe_triple| maybe_triple.map(|_| ()))
        .collect::<crate::error::Result<Vec<_>>>()
        .expect("slice-side named-classifier walk must succeed when zero forms match");
        assert!(
            yielded.is_empty(),
            "slice-side named-classifier walk must yield empty Vec when zero forms match",
        );
    }

    #[test]
    fn iter_named_calls_to_any_emits_named_form_missing_name_for_matched_form_with_no_name_slot() {
        // `(deffoo)` — head matches the classifier (yielding the typed
        // witness AND the classifier-supplied static keyword), but the
        // NAME slot is missing. `split_name_slot`'s arity gate fires
        // inside the slice primitive and emits `NamedFormMissingName {
        // keyword: "deffoo" }`. Pin that the keyword threaded through
        // is the CLASSIFIER-supplied keyword (NOT a hardcoded fallback,
        // NOT the form's head symbol) — a regression that drifted the
        // keyword binding from `decode`'s tuple's second element to the
        // head symbol or to a constant would fail loudly here.
        let forms = crate::reader::read("(deffoo)").unwrap();
        let mut iter = super::iter_named_calls_to_any(&forms, |h: &str| {
            (h == "deffoo").then_some(((), "deffoo"))
        });
        let first = iter.next().expect("matched form must yield an item");
        let err = first.expect_err("matched form with missing NAME must yield Err");
        assert!(
            matches!(
                err,
                crate::error::LispError::NamedFormMissingName { keyword: "deffoo" }
            ),
            "expected NamedFormMissingName {{ keyword: \"deffoo\" }} through slice primitive, got: {err:?}"
        );
    }

    #[test]
    fn iter_named_calls_to_any_emits_named_form_non_symbol_name_for_matched_form_with_int_name() {
        // `(deffoo 42)` — head matches and the NAME-slot arity gate
        // passes, but the NAME slot's shape gate rejects the int
        // literal. Pin that BOTH the classifier-supplied keyword AND
        // the typed `SexpShape::Int` projection flow into the
        // structural variant, identically to how
        // `Expander::expand_and_collect_named_calls_to_any` emits the
        // same variant when its projection composes the same gate.
        let forms = crate::reader::read("(deffoo 42)").unwrap();
        let mut iter = super::iter_named_calls_to_any(&forms, |h: &str| {
            (h == "deffoo").then_some(((), "deffoo"))
        });
        let first = iter.next().expect("matched form must yield an item");
        let err = first.expect_err("matched form with non-symbol NAME must yield Err");
        assert!(
            matches!(
                err,
                crate::error::LispError::NamedFormNonSymbolName {
                    keyword: "deffoo",
                    got: crate::error::SexpShape::Int,
                }
            ),
            "expected NamedFormNonSymbolName {{ keyword: \"deffoo\", got: Int }} through slice primitive, got: {err:?}"
        );
    }

    #[test]
    fn iter_named_calls_to_any_emits_named_form_non_symbol_name_for_matched_form_with_keyword_name()
    {
        // `(deffoo :name)` — sibling shape pin to the int case: a
        // matched form whose NAME slot is a keyword. Together with the
        // int case this closes path-uniformity across distinct
        // non-symbol-or-string `SexpShape` cells at the slice primitive
        // boundary — every consumer routes through the SAME gate
        // composition regardless of the offending shape.
        let forms = crate::reader::read("(deffoo :name)").unwrap();
        let mut iter = super::iter_named_calls_to_any(&forms, |h: &str| {
            (h == "deffoo").then_some(((), "deffoo"))
        });
        let first = iter.next().expect("matched form must yield an item");
        let err = first.expect_err("matched form with keyword NAME must yield Err");
        assert!(
            matches!(
                err,
                crate::error::LispError::NamedFormNonSymbolName {
                    keyword: "deffoo",
                    got: crate::error::SexpShape::Keyword,
                }
            ),
            "expected NamedFormNonSymbolName {{ keyword: \"deffoo\", got: Keyword }} through slice primitive, got: {err:?}"
        );
    }

    #[test]
    fn iter_named_calls_to_any_accepts_string_name_slot_routing_past_the_gate() {
        // `(deffoo "quoted-name" :k v)` — NAME slot is a string
        // literal, which `as_symbol_or_string` (inside `split_name_slot`)
        // accepts alongside symbols. Pin that the slice primitive
        // erases the quote-vs-symbol distinction at the boundary so a
        // consumer sees ONE `&str` shape regardless of authoring
        // choice, matching the equivalent gate in the typed-domain
        // consumer downstream of `named_form_projection<T>`.
        let forms = crate::reader::read(r#"(deffoo "quoted-name" :k "v")"#).unwrap();
        let yielded: Vec<(String, usize)> = super::iter_named_calls_to_any(&forms, |h: &str| {
            (h == "deffoo").then_some(((), "deffoo"))
        })
        .map(|maybe_triple| maybe_triple.map(|(_, name, args)| (name.to_string(), args.len())))
        .collect::<crate::error::Result<Vec<_>>>()
        .expect("string-author NAME slot must route past gate");
        assert_eq!(yielded, vec![("quoted-name".into(), 2)]);
    }

    #[test]
    fn iter_named_calls_to_any_short_circuits_on_first_malformed_name_under_collect() {
        // `(deffoo good 1) (deffoo) (deffoo also-good 2)` — three
        // matched forms; the SECOND has no NAME slot. Pin that
        // `.collect::<Result<Vec<_>, _>>()` short-circuits at the
        // second form (yielding `Err`) WITHOUT yielding the third
        // form's payload. The iterator's lazy iteration combined with
        // `Result::collect`'s short-circuit gives consumers
        // first-failure semantics at the slice boundary, identical to
        // how `Expander::expand_and_collect_named_calls_to_any` already
        // short-circuits.
        let forms = crate::reader::read("(deffoo good 1) (deffoo) (deffoo also-good 2)").unwrap();
        let collected: crate::error::Result<Vec<()>> =
            super::iter_named_calls_to_any(&forms, |h: &str| {
                (h == "deffoo").then_some(((), "deffoo"))
            })
            .map(|maybe_triple| maybe_triple.map(|_| ()))
            .collect();
        let err = collected.expect_err("collect must surface the first failure");
        assert!(
            matches!(
                err,
                crate::error::LispError::NamedFormMissingName { keyword: "deffoo" }
            ),
            "expected NamedFormMissingName at the first malformed NAME, got: {err:?}"
        );
    }

    #[test]
    fn iter_named_calls_to_yields_name_and_spec_args_for_every_matching_form_in_slice() {
        // Constant-keyword sibling of `iter_named_calls_to_any` —
        // discards the `()` typed witness and yields `Result<(&str,
        // &[Sexp])>` per matching form. Pin that the constant-keyword
        // primitive yields the SAME source-ordered set of triples the
        // typed-decoded sibling does on the same source, modulo the
        // discarded typed witness.
        let forms =
            crate::reader::read("(defcheck alpha 1) (other beta) (defcheck gamma 2 3)").unwrap();
        let yielded: Vec<(String, usize)> = super::iter_named_calls_to(&forms, "defcheck")
            .map(|maybe_pair| maybe_pair.map(|(name, args)| (name.to_string(), args.len())))
            .collect::<crate::error::Result<Vec<_>>>()
            .expect("constant-keyword named slice walk must succeed on well-formed forms");
        assert_eq!(
            yielded,
            vec![("alpha".into(), 1), ("gamma".into(), 2)],
            "iter_named_calls_to must yield (NAME, args_len) in source order, skipping unrelated forms",
        );
    }

    #[test]
    fn iter_named_calls_to_routes_through_iter_named_calls_to_any_via_constant_classifier_composition(
    ) {
        // Pin the closed-form composition law binding the constant-
        // keyword named cell to the typed-decoded named-classifier cell
        // at the slice algebra boundary:
        //
        //   iter_named_calls_to(forms, k) ==
        //       iter_named_calls_to_any(forms, |h| (h == k).then_some(((), k)))
        //           .map(|maybe| maybe.map(|(_, n, a)| (n, a)))
        //
        // This makes the typed-decoded named-classifier slice primitive
        // the CANONICAL composition point the constant-keyword sibling
        // routes through — parallel to how `iter_calls_to` /
        // `iter_calls_to_any` bind their composition law on the bare-
        // kwargs axis at the slice level. A regression that drifts ONE
        // sibling's pipeline from the other becomes loudly visible at
        // this assertion.
        let forms =
            crate::reader::read("(defcheck alpha 1) (other beta) (defcheck gamma 2 3)").unwrap();
        let via_constant: Vec<(String, usize)> = super::iter_named_calls_to(&forms, "defcheck")
            .map(|maybe| maybe.map(|(name, args)| (name.to_string(), args.len())))
            .collect::<crate::error::Result<Vec<_>>>()
            .expect("constant-keyword named slice walk must succeed");
        let via_classifier: Vec<(String, usize)> =
            super::iter_named_calls_to_any(&forms, |h: &str| {
                (h == "defcheck").then_some(((), "defcheck"))
            })
            .map(|maybe| maybe.map(|(_, name, args)| (name.to_string(), args.len())))
            .collect::<crate::error::Result<Vec<_>>>()
            .expect("typed-decoded named slice walk with constant-classifier decoder must succeed");
        assert_eq!(
            via_constant, via_classifier,
            "iter_named_calls_to(forms, k) must yield byte-identical payload to iter_named_calls_to_any(forms, |h| (h == k).then_some(((), k))).map(strip)",
        );
    }

    #[test]
    fn iter_named_calls_to_threads_static_keyword_through_missing_variant() {
        // Path-uniformity at the constant-keyword slice primitive
        // boundary: a static `&'static str` keyword threaded into the
        // primitive routes verbatim through the
        // `NamedFormMissingName.keyword` slot when a matched form has
        // no NAME — same threading discipline `split_name_slot` pins at
        // its boundary. Pin three distinct keywords ALL round-trip
        // through the variant's keyword slot.
        for keyword in ["defmonitor", "defalertpolicy", "defcheck"] {
            let src = format!("({keyword})");
            let forms = crate::reader::read(&src).unwrap();
            let mut iter = super::iter_named_calls_to(&forms, keyword);
            let first = iter.next().expect("matched form must yield an item");
            let err = first.expect_err("matched form with missing NAME must yield Err");
            match err {
                crate::error::LispError::NamedFormMissingName { keyword: got } => {
                    assert_eq!(
                        got, keyword,
                        "constant-keyword slice primitive must thread keyword verbatim"
                    );
                }
                other => {
                    panic!("expected NamedFormMissingName for keyword {keyword:?}, got: {other:?}")
                }
            }
        }
    }

    #[test]
    fn iter_named_calls_to_any_admits_fnmut_classifier_maintaining_state_across_batch_walk() {
        // The slice-side typed-decoded named primitive's `FnMut`
        // classifier constraint admits a closure that captures mutable
        // state across the batch walk — counter, registry cache,
        // visited-set — matching the bare-kwargs slice sibling's
        // contract. Pin: a counter-bumping decoder increments once per
        // shape-gate-passing form (NOT once per slice element, since
        // `iter_calls_to_any` short-circuits before the decoder on
        // non-list / empty-list / non-symbol-head shapes), and the
        // post-walk counter equals the number of forms that reached
        // the decoder.
        let forms =
            crate::reader::read("(deffoo a 1) 42 (deffoo b 2) () (defbar c 3) (deffoo d 4)")
                .unwrap();
        let mut decoder_calls = 0usize;
        let yielded: Vec<String> = super::iter_named_calls_to_any(&forms, |h: &str| {
            decoder_calls += 1;
            (h == "deffoo").then_some(((), "deffoo"))
        })
        .map(|maybe| maybe.map(|(_, name, _)| name.to_string()))
        .collect::<crate::error::Result<Vec<_>>>()
        .expect("FnMut classifier dispatch must succeed on well-formed NAME slots");
        // Four (defX …) call forms in the slice pass the shape gate;
        // the int atom and empty list short-circuit before the
        // decoder. Three of the four pass-through-decoder forms
        // dispatch to deffoo; one dispatches to defbar (rejected by
        // the decoder).
        assert_eq!(
            decoder_calls, 4,
            "FnMut decoder must run once per shape-gate-passing form (4 call forms)"
        );
        assert_eq!(
            yielded,
            vec!["a".to_string(), "b".into(), "d".into()],
            "three (deffoo …) forms match; one (defbar …) form is rejected by the decoder",
        );
    }

    #[test]
    fn iter_named_calls_to_any_yields_borrowed_name_and_args_with_form_lifetime() {
        // Pin the borrow-lifetime contract at the slice primitive
        // boundary: the yielded `&'a str` NAME slot and `&'a [Sexp]`
        // spec args tail must borrow from the input slice verbatim —
        // no copy, no allocation. A consumer that holds the iterator's
        // yields alongside the input slice borrow can use the NAME as
        // a lookup key against a registry without paying for a clone.
        let forms = crate::reader::read("(deffoo my-name :k 1 :j 2)").unwrap();
        let mut iter = super::iter_named_calls_to_any(&forms, |h: &str| {
            (h == "deffoo").then_some(((), "deffoo"))
        });
        let (_, name, spec_args) = iter
            .next()
            .expect("matched form must yield an item")
            .expect("well-formed NAME slot must split");
        // Identity-check the NAME borrow: it must point at the same
        // bytes the form's NAME slot symbol borrows from.
        let form_list = forms[0].as_list().expect("form must be a list");
        let form_name = form_list[1]
            .as_symbol()
            .expect("form NAME must be a symbol");
        assert!(
            std::ptr::eq(name.as_ptr(), form_name.as_ptr()),
            "iter_named_calls_to_any must yield the borrowed NAME, NOT an allocated copy"
        );
        // Spec args tail must borrow from the form's tail starting at
        // index 2 (after the NAME slot at index 1).
        assert!(
            std::ptr::eq(spec_args.as_ptr(), &form_list[2] as *const Sexp),
            "iter_named_calls_to_any must yield the borrowed spec args tail, NOT an allocated copy"
        );
        assert_eq!(spec_args.len(), 4);
    }

    // ── as_named_call_to_any / as_named_call_to: per-form × named cell ──
    //
    // The per-form × named corner of the soft-dispatch cube the slice
    // primitive `iter_named_calls_to_any`'s docstring table identified as
    // the documented gap pre-lift ("(composed inline at each named
    // consumer)"). Post-lift the per-form × named row binds to ONE
    // primitive every per-form named consumer composes through, and the
    // slice-side `iter_named_calls_to_any` routes through it via the SAME
    // `forms.iter().filter_map(_)` skeleton `iter_calls_to_any` uses to
    // route through `as_call_to_any`. These tests pin: (a) the three-arm
    // result shape (None for non-match, Some(Ok) for matched-and-
    // well-formed, Some(Err) for matched-but-malformed-NAME) across each
    // distinct shape, (b) the constant-keyword sibling routes through
    // the typed-decoded sibling via constant-classifier composition, (c)
    // the slice-side `iter_named_calls_to_any` IS the
    // `forms.iter().filter_map(|f| f.as_named_call_to_any(_))` projection
    // — the structural identity binding the per-form to the slice row.

    #[test]
    fn as_named_call_to_any_returns_decoded_triple_for_matched_well_formed_form() {
        // `(deffoo my-name :k 1)` — head matches the classifier's `deffoo`
        // arm, NAME slot is the symbol `my-name`, spec args tail is the
        // two-element `:k 1` pair. Pin Some(Ok((decoded, name, args))).
        // Fail-before-pass-after: this assert requires the per-form
        // method to exist AND to thread the typed witness + borrowed
        // NAME + borrowed spec args through ONE projection.
        #[derive(Debug, PartialEq, Eq)]
        enum Kind {
            Foo,
        }
        let form = crate::reader::read("(deffoo my-name :k 1)").unwrap()[0].clone();
        let res = form
            .as_named_call_to_any(|h: &str| match h {
                "deffoo" => Some((Kind::Foo, "deffoo")),
                _ => None,
            })
            .expect("matched head must yield Some(_)")
            .expect("well-formed NAME slot must split");
        assert_eq!(res.0, Kind::Foo);
        assert_eq!(res.1, "my-name");
        assert_eq!(res.2.len(), 2);
    }

    #[test]
    fn as_named_call_to_any_returns_none_when_decoder_rejects_head() {
        // `(unrelated my-name :k 1)` — head is a symbol, but the
        // classifier returns `None`. Pin: the classifier filter face is
        // identical to `as_call_to_any` — `None` short-circuits BEFORE
        // the named gate runs, so a non-matching head with a malformed
        // NAME slot still yields `None`, NOT `Some(Err)`. The soft-
        // filter face is preserved across the cube row.
        let form = crate::reader::read("(unrelated my-name :k 1)").unwrap()[0].clone();
        assert!(form
            .as_named_call_to_any(|h: &str| (h == "deffoo").then_some(((), "deffoo")))
            .is_none());
    }

    #[test]
    fn as_named_call_to_any_returns_none_for_non_call_shapes() {
        // Every shape `as_call_to_any` rejects, `as_named_call_to_any`
        // rejects identically — atom, keyword, empty list, list with
        // non-symbol head. The classifier-filter face is uniformly the
        // soft per-form posture of every other `as_*` method on `Sexp`.
        let shapes: Vec<Sexp> = vec![
            Sexp::int(5),
            Sexp::keyword("deffoo"),
            Sexp::Nil,
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::int(1), Sexp::symbol("my-name")]),
        ];
        for s in shapes {
            assert!(
                s.as_named_call_to_any(|h: &str| (h == "deffoo").then_some(((), "deffoo")))
                    .is_none(),
                "non-call shape must yield None for as_named_call_to_any: {s}"
            );
        }
    }

    #[test]
    fn as_named_call_to_any_returns_some_err_for_matched_head_with_no_name_slot() {
        // `(deffoo)` — head matches the classifier's `deffoo` arm but
        // the form is a singleton: NO NAME slot at all. The named gate
        // (`split_name_slot`'s arity gate) fires structurally, yielding
        // `Some(Err(LispError::NamedFormMissingName { keyword: "deffoo" }))`.
        // Pin the strict-gate face on the named row: matched-and-
        // malformed yields the typed structural rejection variant, NOT
        // `None` (which would conflate "not our head" with "our head
        // but missing NAME" and break the cube's strict-vs-soft split).
        let form = crate::reader::read("(deffoo)").unwrap()[0].clone();
        let err = form
            .as_named_call_to_any(|h: &str| (h == "deffoo").then_some(((), "deffoo")))
            .expect("matched head must yield Some(_)")
            .expect_err("missing NAME slot must yield Err");
        assert!(
            matches!(
                err,
                crate::error::LispError::NamedFormMissingName { keyword: "deffoo" }
            ),
            "expected NamedFormMissingName through per-form primitive, got: {err:?}"
        );
    }

    #[test]
    fn as_named_call_to_any_returns_some_err_for_matched_head_with_non_symbol_name() {
        // `(deffoo 5 :k 1)` — head matches but NAME slot is an int
        // literal. The named gate's `as_symbol_or_string` shape gate
        // fires, yielding `Some(Err(LispError::NamedFormNonSymbolName
        // { keyword: "deffoo", got: SexpShape::Int }))`. Pin the strict-
        // gate face for the second structural rejection variant of the
        // named gate AND the typed `SexpShape` projection of the
        // offending slot.
        let form = crate::reader::read("(deffoo 5 :k 1)").unwrap()[0].clone();
        let err = form
            .as_named_call_to_any(|h: &str| (h == "deffoo").then_some(((), "deffoo")))
            .expect("matched head must yield Some(_)")
            .expect_err("non-symbol NAME slot must yield Err");
        assert!(
            matches!(
                err,
                crate::error::LispError::NamedFormNonSymbolName {
                    keyword: "deffoo",
                    got: crate::error::SexpShape::Int,
                }
            ),
            "expected NamedFormNonSymbolName through per-form primitive, got: {err:?}"
        );
    }

    #[test]
    fn as_named_call_to_constant_keyword_routes_through_as_named_call_to_any() {
        // Pin the closed-form composition binding the constant-keyword
        // sibling to the typed-decoded sibling:
        //   as_named_call_to(k) ==
        //     as_named_call_to_any(|h| (h == k).then_some(((), k)))
        //       .map(|res| res.map(|(_, name, rest)| (name, rest)))
        // across every shape in the test fixture set. A regression
        // that re-implements the constant-keyword sibling without
        // routing through the classifier sibling fails this assertion
        // for the matched-and-well-formed AND matched-but-malformed
        // AND non-match arms simultaneously.
        let shapes: Vec<Sexp> = vec![
            crate::reader::read("(defcompiler my-comp :a 1)").unwrap()[0].clone(),
            crate::reader::read("(defcompiler)").unwrap()[0].clone(),
            crate::reader::read("(defcompiler 5)").unwrap()[0].clone(),
            crate::reader::read("(unrelated my-name :k 1)").unwrap()[0].clone(),
            Sexp::int(99),
            Sexp::List(vec![]),
        ];
        // `LispError` is not `PartialEq` (it transitively wraps `Sexp`,
        // which carries an `Atom::Float` whose `f64` is not `Eq`).
        // Compare via formatted-debug strings on the Err arm; Ok arms and
        // None arm compare structurally. The closed-form composition
        // `as_named_call_to(k) == as_named_call_to_any+unit-decoder` is
        // pinned across all three arms.
        for s in &shapes {
            let via_constant = s.as_named_call_to("defcompiler").map(|res| {
                res.map(|(name, rest)| (name.to_string(), rest.len()))
                    .map_err(|e| format!("{e:?}"))
            });
            let via_classifier = s
                .as_named_call_to_any(|h: &str| (h == "defcompiler").then_some(((), "defcompiler")))
                .map(|res| {
                    res.map(|(_, name, rest)| (name.to_string(), rest.len()))
                        .map_err(|e| format!("{e:?}"))
                });
            assert_eq!(
                via_constant, via_classifier,
                "as_named_call_to(k) must equal as_named_call_to_any+unit-decoder for {s}"
            );
        }
    }

    #[test]
    fn iter_named_calls_to_any_is_the_slice_side_filter_map_of_as_named_call_to_any() {
        // Pin the structural identity binding the slice algebra to the
        // per-form algebra:
        //   iter_named_calls_to_any(forms, decode) ==
        //     forms.iter().filter_map(|f| f.as_named_call_to_any(&mut decode))
        // Both sides must yield the SAME Result shape per element in
        // source order — `Ok(triple)` for matched-and-well-formed,
        // `Err(LispError)` for matched-but-malformed, with non-matches
        // skipped by the filter_map. Sibling pin to
        // `iter_calls_to_any_is_the_slice_side_projection_of_as_call_to_any`
        // on the bare-kwargs row — both rows now share ONE
        // `forms.iter().filter_map(_)` skeleton.
        #[derive(Debug, PartialEq, Eq, Clone, Copy)]
        enum Kind {
            Foo,
            Bar,
        }
        let src = "(deffoo a :k 1)
                   (other thing)
                   (defbar 7 :j 2)
                   (deffoo b)
                   (defbaz c :m 3)";
        let forms = crate::reader::read(src).unwrap();
        let decode = |h: &str| match h {
            "deffoo" => Some((Kind::Foo, "deffoo")),
            "defbar" => Some((Kind::Bar, "defbar")),
            _ => None,
        };
        let via_iter: Vec<crate::error::Result<(Kind, String, usize)>> =
            super::iter_named_calls_to_any(&forms, decode)
                .map(|res| res.map(|(k, name, args)| (k, name.to_string(), args.len())))
                .collect();
        let via_filter_map: Vec<crate::error::Result<(Kind, String, usize)>> = forms
            .iter()
            .filter_map(|f| f.as_named_call_to_any(decode))
            .map(|res| res.map(|(k, name, args)| (k, name.to_string(), args.len())))
            .collect();
        assert_eq!(
            via_iter.len(),
            via_filter_map.len(),
            "slice-side iter must yield the same number of items as the per-form filter_map",
        );
        for (a, b) in via_iter.iter().zip(via_filter_map.iter()) {
            match (a, b) {
                (Ok(ta), Ok(tb)) => assert_eq!(ta, tb),
                (Err(ea), Err(eb)) => assert_eq!(format!("{ea:?}"), format!("{eb:?}")),
                _ => panic!(
                    "variant drift between slice iter and per-form filter_map: {a:?} vs {b:?}"
                ),
            }
        }
        // Concretely: 3 matched forms (deffoo a, defbar 7, deffoo b);
        // `defbar 7` yields Err (int NAME), other two yield Ok.
        assert_eq!(via_iter.len(), 3);
        assert!(via_iter[0].is_ok());
        assert!(via_iter[1].is_err());
        assert!(via_iter[2].is_ok());
    }

    #[test]
    fn as_named_call_to_any_borrows_name_and_spec_args_from_form_verbatim() {
        // Pin the borrow-lifetime contract at the per-form primitive
        // boundary: the yielded `&str` NAME slot and `&[Sexp]` spec
        // args tail must borrow from the underlying form verbatim — no
        // copy, no allocation. Sibling pin to
        // `iter_named_calls_to_any_yields_borrowed_name_and_args_with_form_lifetime`
        // on the slice algebra — both rows preserve the borrow
        // contract.
        let forms = crate::reader::read("(deffoo my-name :k 1 :j 2)").unwrap();
        let form = &forms[0];
        let (_, name, spec_args) = form
            .as_named_call_to_any(|h: &str| (h == "deffoo").then_some(((), "deffoo")))
            .expect("matched head must yield Some(_)")
            .expect("well-formed NAME slot must split");
        let form_list = form.as_list().expect("form must be a list");
        let form_name = form_list[1]
            .as_symbol()
            .expect("form NAME must be a symbol");
        assert!(
            std::ptr::eq(name.as_ptr(), form_name.as_ptr()),
            "as_named_call_to_any must yield the borrowed NAME, NOT an allocated copy"
        );
        assert!(
            std::ptr::eq(spec_args.as_ptr(), &form_list[2] as *const Sexp),
            "as_named_call_to_any must yield the borrowed spec args tail, NOT an allocated copy"
        );
        assert_eq!(spec_args.len(), 4);
    }

    // ── as_unquote: the unquote-family projection ───────────────────────
    //
    // `as_unquote` lifts the per-callsite `Sexp::Unquote(inner) /
    // Sexp::UnquoteSplice(inner)` arms paired with their `UnquoteForm::
    // Unquote / UnquoteForm::Splice` literals — three sites pre-lift
    // (`compile_node` 2 arms + `substitute` top-level + `substitute`
    // list-inner) — into ONE typed projection on the `Sexp` algebra.
    // These tests pin its contract; the existing path tests in
    // macro_expand.rs are the path-uniformity guards proving the three
    // sites route through it without behavior drift.

    #[test]
    fn as_unquote_decomposes_unquote_into_typed_marker_and_inner() {
        // `,x` — Sexp::Unquote wrapping a symbol. Pin Some((Unquote, &inner)).
        let inner = Sexp::symbol("x");
        let form = Sexp::Unquote(Box::new(inner.clone()));
        let (marker, body) = form
            .as_unquote()
            .expect("`,x` must project to Some((Unquote, _))");
        assert_eq!(marker, UnquoteForm::Unquote);
        assert_eq!(body, &inner);
    }

    #[test]
    fn as_unquote_decomposes_unquote_splice_into_typed_marker_and_inner() {
        // `,@xs` — Sexp::UnquoteSplice wrapping a symbol. Pin
        // Some((Splice, &inner)). Sibling positive control to the Unquote
        // arm: pins BOTH unquote-family variants project to their typed
        // closed-set UnquoteForm pair through ONE projection function.
        let inner = Sexp::symbol("xs");
        let form = Sexp::UnquoteSplice(Box::new(inner.clone()));
        let (marker, body) = form
            .as_unquote()
            .expect("`,@xs` must project to Some((Splice, _))");
        assert_eq!(marker, UnquoteForm::Splice);
        assert_eq!(body, &inner);
    }

    #[test]
    fn as_unquote_none_for_non_unquote_shapes() {
        // Every Sexp shape OUTSIDE the unquote family — atoms, lists, nil,
        // and the OTHER quote-family variants (Quote `'x`, Quasiquote ``x`) —
        // yields None. Pins the projection's exhaustive negative coverage:
        // a regression that drifts the matched-variant set (e.g. a future
        // emitter that projects `'x` into Some((Unquote, _))) would fail
        // here, even before any downstream dispatcher tests fire.
        assert_eq!(Sexp::symbol("foo").as_unquote(), None);
        assert_eq!(Sexp::int(5).as_unquote(), None);
        assert_eq!(Sexp::keyword("k").as_unquote(), None);
        assert_eq!(Sexp::string("s").as_unquote(), None);
        assert_eq!(Sexp::boolean(true).as_unquote(), None);
        assert_eq!(Sexp::float(1.5).as_unquote(), None);
        assert_eq!(Sexp::Nil.as_unquote(), None);
        assert_eq!(Sexp::List(vec![]).as_unquote(), None);
        assert_eq!(
            Sexp::List(vec![Sexp::symbol("a"), Sexp::int(1)]).as_unquote(),
            None
        );
        // `'x` — Quote-family but NOT unquote-family. The closed-set
        // UnquoteForm projection covers only `,` and `,@`; `'` and `` ` ``
        // are siblings that this projection does NOT match.
        assert_eq!(Sexp::Quote(Box::new(Sexp::symbol("x"))).as_unquote(), None);
        assert_eq!(
            Sexp::Quasiquote(Box::new(Sexp::symbol("x"))).as_unquote(),
            None
        );
    }

    #[test]
    fn as_unquote_is_some_iff_matches_unquote_family() {
        // Structural identity: as_unquote().is_some() agrees with the
        // pre-lift `matches!(self, Sexp::Unquote(_) | Sexp::UnquoteSplice(_))`
        // discriminant across the closed Sexp variant set. Sweep every
        // representative Sexp shape and pin equality of the two discriminants
        // — a regression that drifts ONE shape's projection (e.g. adds
        // Quasiquote to the matched set) becomes a typed test failure.
        let shapes: Vec<(&str, Sexp, bool)> = vec![
            ("nil", Sexp::Nil, false),
            ("symbol", Sexp::symbol("x"), false),
            ("keyword", Sexp::keyword("k"), false),
            ("string", Sexp::string("s"), false),
            ("int", Sexp::int(7), false),
            ("float", Sexp::float(2.5), false),
            ("bool", Sexp::boolean(true), false),
            ("empty list", Sexp::List(vec![]), false),
            (
                "non-empty list",
                Sexp::List(vec![Sexp::symbol("op")]),
                false,
            ),
            ("quote", Sexp::Quote(Box::new(Sexp::symbol("x"))), false),
            (
                "quasiquote",
                Sexp::Quasiquote(Box::new(Sexp::symbol("x"))),
                false,
            ),
            ("unquote", Sexp::Unquote(Box::new(Sexp::symbol("x"))), true),
            (
                "unquote-splice",
                Sexp::UnquoteSplice(Box::new(Sexp::symbol("xs"))),
                true,
            ),
        ];
        for (label, sexp, expect_some) in &shapes {
            let via_proj = sexp.as_unquote().is_some();
            let via_pat = matches!(sexp, Sexp::Unquote(_) | Sexp::UnquoteSplice(_));
            assert_eq!(
                via_proj, *expect_some,
                "as_unquote().is_some() drifted from expected at {label}"
            );
            assert_eq!(
                via_proj, via_pat,
                "as_unquote().is_some() != pre-lift `matches!(_, Unquote | UnquoteSplice)` at {label}"
            );
        }
    }

    #[test]
    fn as_unquote_inner_pointer_is_the_boxed_body() {
        // The returned `&Sexp` borrows the inner box's body verbatim — no
        // clone, no allocation, same lifetime as `&self`. Pin pointer
        // identity: the returned `&Sexp` shares its address with the
        // contents of the original Box, proving no intermediate copy fires
        // at the projection boundary (so consumers walking deeply nested
        // template bodies pay zero allocation per unquote node).
        let inner = Sexp::symbol("payload");
        let boxed = Box::new(inner);
        let inner_ptr: *const Sexp = boxed.as_ref();
        let form = Sexp::Unquote(boxed);
        let (_, body) = form
            .as_unquote()
            .expect("Sexp::Unquote must project to Some");
        assert!(
            std::ptr::eq(body, inner_ptr),
            "as_unquote inner pointer drifted from the boxed body — projection allocates or clones"
        );

        let inner_splice = Sexp::symbol("payload-splice");
        let boxed_splice = Box::new(inner_splice);
        let inner_splice_ptr: *const Sexp = boxed_splice.as_ref();
        let form_splice = Sexp::UnquoteSplice(boxed_splice);
        let (_, body_splice) = form_splice
            .as_unquote()
            .expect("Sexp::UnquoteSplice must project to Some");
        assert!(
            std::ptr::eq(body_splice, inner_splice_ptr),
            "as_unquote inner pointer drifted from the boxed body (splice arm)"
        );
    }

    // ── fmt_float: Display→read round-trip preserves Float identity ──────
    //
    // Rust's stdlib Display for f64 elides trailing `.0` on integral
    // floats — `format!("{}", 1.0_f64) == "1"` — and the substrate's
    // reader tries `i64::parse` before `f64::parse`, so a bare `1` re-reads
    // as `Atom::Int(1)`, NOT `Atom::Float(1.0)`. The Display→read
    // round-trip pre-lift dropped the typed Float identity on every
    // integral float: `Float(1.0)` displayed as `"1"`, re-read as `Int(1)`,
    // and downstream consumers silently typed the slot as Int. The
    // `fmt_float` helper appends `.0` for finite integral values so the
    // round-trip preserves the typed identity. Tests below pin:
    //   (a) Display of `Float(1.0)` is `"1.0"` (fail-before-pass-after);
    //   (b) the Display→read round-trip lands as `Float(1.0)`, NOT
    //       `Int(1)` (the typed-identity preservation contract);
    //   (c) non-integral floats render unchanged through the default
    //       impl (`Float(1.5)` is still `"1.5"`);
    //   (d) negative integral floats inherit the `.0` suffix
    //       (`Float(-2.0)` is `"-2.0"`);
    //   (e) integer Display is unaffected (`Int(1)` is still `"1"`) —
    //       pin path-uniformity so the helper is precisely scoped to
    //       the Float arm.

    #[test]
    fn fmt_float_renders_integral_float_with_trailing_zero() {
        // Fail-before-pass-after: pre-lift `Sexp::float(1.0).to_string()`
        // was `"1"`; post-lift the typed Float identity is preserved by
        // the `.0` suffix.
        assert_eq!(Sexp::float(1.0).to_string(), "1.0");
        assert_eq!(Sexp::float(100.0).to_string(), "100.0");
        assert_eq!(Sexp::float(0.0).to_string(), "0.0");
    }

    #[test]
    fn fmt_float_round_trips_integral_float_through_reader_as_float() {
        // The structural contract the lift establishes: a `Float`
        // serialized via `Display` re-reads as `Float`, NOT `Int`. Pin
        // the round-trip via the reader so a regression that drops the
        // `.0` suffix (or that re-orders the reader's i64/f64 parse
        // attempts to drop the float arm) surfaces here.
        let orig = Sexp::float(1.0);
        let rendered = orig.to_string();
        let forms =
            crate::reader::read(&rendered).expect("integral float must round-trip through reader");
        assert_eq!(forms.len(), 1);
        match &forms[0] {
            Sexp::Atom(Atom::Float(n)) => assert_eq!(*n, 1.0),
            other => panic!("Display->read round-trip dropped the Float identity, got: {other:?}"),
        }
        // Sibling-shape control: a SECOND integral magnitude reinforces
        // that the round-trip preserves the value, not only the type.
        let orig2 = Sexp::float(-42.0);
        let rendered2 = orig2.to_string();
        let forms2 = crate::reader::read(&rendered2)
            .expect("negative integral float must round-trip through reader");
        match &forms2[0] {
            Sexp::Atom(Atom::Float(n)) => assert_eq!(*n, -42.0),
            other => panic!(
                "Display->read of negative integral float dropped Float identity, got: {other:?}"
            ),
        }
    }

    #[test]
    fn fmt_float_preserves_non_integral_float_display() {
        // Path-uniformity: non-integral floats (the case the stdlib impl
        // already handled correctly) must render unchanged. A regression
        // that always-appends `.0` would write `"1.5.0"` and fail
        // here AND fail the reader round-trip below.
        assert_eq!(Sexp::float(1.5).to_string(), "1.5");
        assert_eq!(Sexp::float(0.99).to_string(), "0.99");
        assert_eq!(Sexp::float(-2.75).to_string(), "-2.75");

        // Round-trip control for the non-integral case stays valid: the
        // helper is precisely scoped, so the fractional component is
        // preserved verbatim through the reader.
        let orig = Sexp::float(0.99);
        let forms = crate::reader::read(&orig.to_string())
            .expect("non-integral float must round-trip through reader");
        match &forms[0] {
            Sexp::Atom(Atom::Float(n)) => assert_eq!(*n, 0.99),
            other => panic!("non-integral float round-trip drift, got: {other:?}"),
        }
    }

    // ── QuoteForm + as_quote_form: closed-set quote-family projection ─────
    //
    // `as_quote_form` lifts the per-callsite `Sexp::Quote(inner)
    // / Sexp::Quasiquote(inner) / Sexp::Unquote(inner) /
    // Sexp::UnquoteSplice(inner)` arm-set paired with their
    // per-variant prefix string (`'`, `` ` ``, `,`, `,@`) and
    // discriminator byte (3, 4, 5, 6) into ONE typed projection on
    // the `Sexp` algebra. Three consumers in this file route through
    // it (`Hash for Sexp`, `Display for Sexp`, `Sexp::as_unquote`)
    // so the (Sexp variant, marker, prefix, discriminator) tuple
    // binds at ONE site. Tests below pin:
    //   (a) the projection lands `Some((QuoteForm::*, inner))` for
    //       each of the four wrapper variants AND `None` for every
    //       non-quote-family shape;
    //   (b) `QuoteForm::prefix` returns the canonical reader-token
    //       prefix for each variant — load-bearing for the round-trip
    //       property the `Display`→reader dual encodes;
    //   (c) `QuoteForm::hash_discriminator` returns the same byte
    //       values the pre-lift Hash arms emitted (3, 4, 5, 6) — pin
    //       the cache-key contract so a regression that drifts a
    //       discriminator silently invalidates every cached expansion
    //       fails loudly here;
    //   (d) `QuoteForm::as_unquote_form` projects the 2-of-4 subset
    //       `{Unquote → UnquoteForm::Unquote, UnquoteSplice →
    //       UnquoteForm::Splice}` and yields `None` for `{Quote,
    //       Quasiquote}` — the structural-subset gate the
    //       `Sexp::as_unquote` derivation routes through;
    //   (e) `Sexp::as_unquote` derived from `as_quote_form +
    //       QuoteForm::as_unquote_form` agrees with the pre-lift
    //       arm-based semantic across every Sexp shape — path
    //       uniformity across the subset gate;
    //   (f) the four homoiconic prefixes round-trip through the
    //       reader via `read(format!("{prefix}{inner}"))` into the
    //       matching `Sexp::*` variant — the typed dual of the
    //       reader's prefix dispatch, pinned end-to-end on the four
    //       wrappers (sibling to `fmt_float`'s Float round-trip pin
    //       at the Display→read boundary).

    #[test]
    fn as_quote_form_projects_each_wrapper_variant_to_typed_marker_and_inner() {
        // `'foo` — Sexp::Quote wrapping a symbol. Pin Some((Quote, &inner))
        // with the typed marker AND the borrowed inner body.
        let inner = Sexp::symbol("foo");
        let form = Sexp::Quote(Box::new(inner.clone()));
        let (qf, body) = form.as_quote_form().expect("Sexp::Quote must project");
        assert_eq!(qf, QuoteForm::Quote);
        assert_eq!(body, &inner);

        // `` `foo `` — Sexp::Quasiquote wrapping a symbol.
        let form_qq = Sexp::Quasiquote(Box::new(inner.clone()));
        let (qf_qq, body_qq) = form_qq
            .as_quote_form()
            .expect("Sexp::Quasiquote must project");
        assert_eq!(qf_qq, QuoteForm::Quasiquote);
        assert_eq!(body_qq, &inner);

        // `,foo` — Sexp::Unquote wrapping a symbol.
        let form_u = Sexp::Unquote(Box::new(inner.clone()));
        let (qf_u, body_u) = form_u.as_quote_form().expect("Sexp::Unquote must project");
        assert_eq!(qf_u, QuoteForm::Unquote);
        assert_eq!(body_u, &inner);

        // `,@xs` — Sexp::UnquoteSplice wrapping a symbol.
        let form_us = Sexp::UnquoteSplice(Box::new(Sexp::symbol("xs")));
        let (qf_us, body_us) = form_us
            .as_quote_form()
            .expect("Sexp::UnquoteSplice must project");
        assert_eq!(qf_us, QuoteForm::UnquoteSplice);
        assert_eq!(body_us, &Sexp::symbol("xs"));
    }

    #[test]
    fn as_quote_form_none_for_non_quote_family_shapes() {
        // Every shape OUTSIDE the closed quote-family must project to
        // None: Nil, every Atom variant, and List (empty + populated).
        // Pin the closed-set boundary so a regression that accidentally
        // promotes a non-wrapper variant into the quote family becomes
        // a typed test failure.
        assert_eq!(Sexp::Nil.as_quote_form(), None);
        assert_eq!(Sexp::symbol("x").as_quote_form(), None);
        assert_eq!(Sexp::keyword("k").as_quote_form(), None);
        assert_eq!(Sexp::string("s").as_quote_form(), None);
        assert_eq!(Sexp::int(7).as_quote_form(), None);
        assert_eq!(Sexp::float(2.5).as_quote_form(), None);
        assert_eq!(Sexp::boolean(true).as_quote_form(), None);
        assert_eq!(Sexp::List(vec![]).as_quote_form(), None);
        assert_eq!(
            Sexp::List(vec![Sexp::symbol("op"), Sexp::int(1)]).as_quote_form(),
            None
        );
    }

    #[test]
    fn as_quote_form_inner_pointer_is_the_boxed_body() {
        // The returned `&Sexp` borrows the inner box's body verbatim —
        // no clone, no allocation, same lifetime as `&self`. Pin
        // pointer identity for each of the four wrapper variants so a
        // regression that adds an intermediate copy at the projection
        // boundary surfaces here. Same posture as
        // `as_unquote_inner_pointer_is_the_boxed_body` for its 2-of-4
        // subset.
        let payload = Sexp::symbol("payload");
        let boxed = Box::new(payload);
        let inner_ptr: *const Sexp = boxed.as_ref();
        let form = Sexp::Quote(boxed);
        let (_, body) = form.as_quote_form().expect("Sexp::Quote must project");
        assert!(
            std::ptr::eq(body, inner_ptr),
            "as_quote_form inner pointer drifted from the boxed body — projection allocates or clones"
        );

        let payload_qq = Sexp::symbol("payload-qq");
        let boxed_qq = Box::new(payload_qq);
        let inner_ptr_qq: *const Sexp = boxed_qq.as_ref();
        let form_qq = Sexp::Quasiquote(boxed_qq);
        let (_, body_qq) = form_qq
            .as_quote_form()
            .expect("Sexp::Quasiquote must project");
        assert!(
            std::ptr::eq(body_qq, inner_ptr_qq),
            "as_quote_form inner pointer drifted (quasiquote arm)"
        );
    }

    #[test]
    fn expect_quote_form_projects_each_quote_family_variant_identically_to_as_quote_form() {
        // ASSERTED-TOTAL-FACE CONTRACT: `expect_quote_form` is the
        // asserted-total face of `as_quote_form` — for every quote-family
        // variant it MUST yield the same `(QuoteForm, &Sexp)` projection
        // that `as_quote_form` yields wrapped in `Some`. A regression
        // that drifts the two projections (e.g. a future variant
        // extension that updates `as_quote_form` but forgets to align
        // `expect_quote_form`'s body) surfaces here.
        let inner = Sexp::symbol("payload");
        for variant in [
            Sexp::Quote(Box::new(inner.clone())),
            Sexp::Quasiquote(Box::new(inner.clone())),
            Sexp::Unquote(Box::new(inner.clone())),
            Sexp::UnquoteSplice(Box::new(inner.clone())),
        ] {
            let via_total = variant.expect_quote_form();
            let via_soft = variant.as_quote_form().expect("variant is quote-family");
            assert_eq!(
                via_total.0, via_soft.0,
                "expect_quote_form's QuoteForm drifted from as_quote_form's at {variant}"
            );
            assert!(
                std::ptr::eq(via_total.1, via_soft.1),
                "expect_quote_form's inner pointer drifted from as_quote_form's at {variant}"
            );
        }
    }

    #[test]
    fn expect_quote_form_panics_with_invariant_const_on_non_quote_family_variants() {
        // STATIC-INVARIANT CONTRACT: every non-quote-family variant
        // (Nil, every Atom subkind, List empty + populated) MUST trigger
        // the asserted-total panic with the named
        // `QUOTE_FAMILY_PROJECTION_INVARIANT` message. The const-vs-
        // panic-payload pin catches a future drift where the const is
        // edited without the projection picking it up (or vice versa).
        for variant in [
            Sexp::Nil,
            Sexp::symbol("x"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::float(2.5),
            Sexp::boolean(true),
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("op"), Sexp::int(1)]),
        ] {
            let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
                let _ = variant.expect_quote_form();
            }));
            let payload = result.expect_err("expect_quote_form must panic on non-quote-family");
            let msg = payload
                .downcast_ref::<String>()
                .map(String::as_str)
                .or_else(|| payload.downcast_ref::<&'static str>().copied())
                .expect("panic payload must be a string");
            assert!(
                msg.contains(QUOTE_FAMILY_PROJECTION_INVARIANT),
                "expect_quote_form panic message {msg:?} did not name \
                 QUOTE_FAMILY_PROJECTION_INVARIANT at variant {variant:?}"
            );
        }
    }

    #[test]
    fn quote_family_projection_invariant_const_matches_legacy_inline_literal() {
        // CONST-PIN: pre-lift the panic literal "matched quote-family
        // variant must project to Some via as_quote_form" appeared inline
        // at FIVE production sites (`Hash for Sexp`, `Display for Sexp`,
        // `domain::sexp_shape`, `domain::sexp_to_json`,
        // `interop::iac_forge_tag`). Pin the lifted const to the legacy
        // inline literal bit-for-bit so a regression that drifts the
        // const silently from the historical diagnostic string surfaces
        // here. Sibling shape to `quote_form_hash_discriminator_pins_
        // legacy_cache_key_bytes` for the discriminator-byte algebra.
        assert_eq!(
            QUOTE_FAMILY_PROJECTION_INVARIANT,
            "matched quote-family variant must project to Some via as_quote_form"
        );
    }

    #[test]
    fn quote_form_prefix_pins_canonical_reader_tokens_for_every_variant() {
        // Pin every prefix string load-bearing for the Display→read
        // round-trip. A regression that drifts the prefix (e.g. swaps
        // `'` and `` ` `` between Quote and Quasiquote) silently
        // re-routes every renderer through the wrong variant; this
        // test fails loudly. Sibling-arm sweep so the (variant,
        // prefix) pair stays load-bearing under reordering refactors.
        assert_eq!(QuoteForm::Quote.prefix(), "'");
        assert_eq!(QuoteForm::Quasiquote.prefix(), "`");
        assert_eq!(QuoteForm::Unquote.prefix(), ",");
        assert_eq!(QuoteForm::UnquoteSplice.prefix(), ",@");
    }

    // ── `QuoteForm::{QUOTE_PREFIX, QUASIQUOTE_PREFIX, UNQUOTE_PREFIX,
    // UNQUOTE_SPLICE_PREFIX, PREFIXES}` — per-role `&'static str`
    // reader-prefix algebra on the closed-set outer [`QuoteForm`]. Peer
    // of [`crate::error::MacroDefHead::KEYWORDS`] (head-keyword
    // algebra), [`Atom::BOOL_LITERALS`] (Scheme-bool spelling algebra),
    // and [`crate::macro_expand::MacroParams::LAMBDA_LIST_KEYWORDS`]
    // (CL lambda-list-keyword algebra) — every closed-set outer
    // projection on the substrate now pins its canonical bytes at ONE
    // `pub const` per role plus an ALL array for family-wide consumers.

    #[test]
    fn quote_form_quote_prefix_projects_canonical_single_quote_bytes() {
        // Pin the exact `"'"` bytes at the typed constant. A regression
        // that renames the constant to a different byte fails HERE
        // rather than at silent reader-family drift where `'foo`
        // classifies as a bare atom (or through a different quote-family
        // variant) instead of `Sexp::Quote`.
        assert_eq!(QuoteForm::QUOTE_PREFIX, "'");
    }

    #[test]
    fn quote_form_quasiquote_prefix_projects_canonical_backtick_bytes() {
        // Pin the exact `` "`" `` bytes at the typed constant. Sibling
        // posture to `quote_form_quote_prefix_projects_canonical_single_quote_bytes`.
        assert_eq!(QuoteForm::QUASIQUOTE_PREFIX, "`");
    }

    #[test]
    fn quote_form_unquote_prefix_projects_canonical_comma_bytes() {
        // Pin the exact `","` bytes at the typed constant.
        assert_eq!(QuoteForm::UNQUOTE_PREFIX, ",");
    }

    #[test]
    fn quote_form_unquote_splice_prefix_projects_canonical_comma_at_bytes() {
        // Pin the exact `",@"` bytes at the typed constant — the ONLY
        // two-char prefix on the closed set. A regression that lost the
        // `@` discriminator (dropping to just `","`, colliding with
        // `UNQUOTE_PREFIX`) surfaces HERE rather than as a silent
        // reader classifier collision.
        assert_eq!(QuoteForm::UNQUOTE_SPLICE_PREFIX, ",@");
    }

    #[test]
    fn quote_form_prefix_routes_through_typed_per_role_constants() {
        // PATH-UNIFORMITY: `Self::prefix(self)` returns the per-role
        // `pub const` byte-for-byte per variant, catching a regression
        // that reverts ONE arm to an inline `"'"` / `` "`" `` / `","`
        // / `",@"` string literal (or drifts one arm's bytes silently).
        // Sibling posture to
        // `atom_bool_literal_routes_through_typed_per_variant_constants`
        // on the Scheme-bool spelling algebra.
        for (qf, expected) in [
            (QuoteForm::Quote, QuoteForm::QUOTE_PREFIX),
            (QuoteForm::Quasiquote, QuoteForm::QUASIQUOTE_PREFIX),
            (QuoteForm::Unquote, QuoteForm::UNQUOTE_PREFIX),
            (QuoteForm::UnquoteSplice, QuoteForm::UNQUOTE_SPLICE_PREFIX),
        ] {
            let actual = qf.prefix();
            assert_eq!(
                actual, expected,
                "QuoteForm::{qf:?}.prefix() `{actual}` drifted from \
                 per-role constant `{expected}` — the arm must route \
                 through the typed constant rather than an inline literal",
            );
        }
    }

    #[test]
    fn quote_form_prefixes_has_expected_cardinality() {
        // Cardinality contract: `Self::PREFIXES.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
        // `atom_bool_literals_has_expected_cardinality` and
        // `macro_def_head_keywords_has_expected_cardinality`.
        assert_eq!(
            QuoteForm::PREFIXES.len(),
            4,
            "QuoteForm::PREFIXES cardinality drifted from 4 — the \
             closed homoiconic-prefix domain admits exactly four \
             wrappers by construction; a fifth extension surfaces here"
        );
    }

    #[test]
    fn quote_form_prefixes_align_with_all_by_index() {
        // ALIGNMENT CONTRACT: `Self::PREFIXES[i] == Self::ALL[i].prefix()`
        // element-wise. Pins that the typed variant ALL and the
        // `&'static str` PREFIXES ALL stay in lockstep under any
        // reorder — a regression that reorders ONE array without
        // reordering the other silently misaligns every `zip(ALL,
        // PREFIXES)` consumer (LSP completion providers, metric-label
        // emitters, coverage reporters). Sibling posture to
        // `macro_def_head_keywords_align_with_all_by_index`.
        for (i, qf) in QuoteForm::ALL.iter().enumerate() {
            assert_eq!(
                QuoteForm::PREFIXES[i],
                qf.prefix(),
                "QuoteForm::PREFIXES[{i}] `{prefix}` drifted from \
                 QuoteForm::ALL[{i}] ({qf:?}).prefix() `{via_variant}` \
                 — the canonical declaration order of the ALL array \
                 and the prefix projection must match element-wise",
                prefix = QuoteForm::PREFIXES[i],
                via_variant = qf.prefix(),
            );
        }
    }

    #[test]
    fn quote_form_prefixes_pairwise_distinct() {
        // PAIRWISE DISJOINTNESS: every entry of the `PREFIXES` array
        // must differ so the reader-entry classifier (whether inline
        // as at [`crate::reader::tokenize`]'s outer arm or via a
        // hypothetical future `PREFIXES.iter()` sweep) cannot route
        // two homoiconic prefixes through the same arm. Family-wide
        // sweep over `PREFIXES × PREFIXES` — supersedes any per-pair
        // pin and picks up new prefixes mechanically. Sibling posture
        // to `atom_bool_literals_pairwise_distinct` on the Scheme-bool
        // algebra AND `macro_def_head_keywords_pairwise_distinct` on
        // the head-keyword algebra.
        for (i, a) in QuoteForm::PREFIXES.iter().enumerate() {
            for (j, b) in QuoteForm::PREFIXES.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "QuoteForm::PREFIXES[{i}] `{a}` collides with \
                     QuoteForm::PREFIXES[{j}] `{b}` — the reader-entry \
                     classifier's cascade would route two homoiconic \
                     prefixes through the same arm"
                );
            }
        }
    }

    #[test]
    fn quote_form_per_role_prefixes_route_through_matching_lead_char_for_every_variant() {
        // CROSS-AXIS ROUND-TRIP: every entry of `Self::PREFIXES` MUST
        // start with the corresponding variant's `lead_char()` — the
        // per-role `pub const` on the reader-prefix axis composes byte-
        // for-byte with the per-role `char` on the reader-lead-byte axis
        // ([`Self::QUOTE_LEAD`], [`Self::QUASIQUOTE_LEAD`],
        // [`Self::UNQUOTE_LEAD`]) via the [`Self::lead_char`] projection.
        // Both `Unquote` AND `UnquoteSplice` start with `UNQUOTE_LEAD`
        // (the shared `,` lead byte) — the two-char splice prefix's
        // second byte is [`Self::SPLICE_DISCRIMINATOR`], which the
        // reader's peek-then-consume arm disambiguates on. Sibling
        // posture to `atom_bool_literals_all_route_through_bool_literal_leading_byte`
        // on the Scheme-bool spelling algebra.
        for (i, qf) in QuoteForm::ALL.iter().enumerate() {
            let prefix = QuoteForm::PREFIXES[i];
            let expected_lead = qf.lead_char();
            let actual_lead = prefix.chars().next().unwrap_or_else(|| {
                panic!("QuoteForm::PREFIXES[{i}] `{prefix}` for {qf:?} must have at least one char")
            });
            assert_eq!(
                actual_lead, expected_lead,
                "QuoteForm::PREFIXES[{i}] `{prefix}` for {qf:?} — first \
                 char {actual_lead:?} drifted from lead_char {expected_lead:?} — \
                 the per-role prefix constant drifted from the shared \
                 lead byte"
            );
        }
    }

    #[test]
    fn quote_form_unquote_splice_prefix_constant_composes_from_unquote_lead_and_splice_discriminator(
    ) {
        // STRUCTURAL COMPOSITION LAW at the `pub const` level:
        // [`Self::UNQUOTE_SPLICE_PREFIX`] decomposes cleanly into
        // [`Self::UNQUOTE_LEAD`] + [`Self::SPLICE_DISCRIMINATOR`]. The
        // ONLY two-char prefix on the closed set composes from the two
        // `char`-level constants on the algebra. Section-for-retraction
        // peer of the pre-existing
        // `quote_form_unquote_splice_prefix_composes_from_unquote_lead_and_splice_discriminator`
        // pin (which composes at the [`Self::prefix`] method level);
        // where that pin composes through the runtime projection, this
        // pin composes at the `pub const` level so a regression that
        // drifts the two-char constant WITHOUT drifting the runtime
        // projection (unlikely but structurally distinct) surfaces
        // here.
        let composed = format!(
            "{}{}",
            QuoteForm::UNQUOTE_LEAD,
            QuoteForm::SPLICE_DISCRIMINATOR,
        );
        assert_eq!(
            composed,
            QuoteForm::UNQUOTE_SPLICE_PREFIX,
            "QuoteForm::UNQUOTE_SPLICE_PREFIX drifted from UNQUOTE_LEAD + \
             SPLICE_DISCRIMINATOR — the reader's two-char splice \
             promotion identity is broken at the pub-const byte level",
        );
    }

    #[test]
    fn quote_form_lead_char_pins_first_char_of_prefix_for_every_variant() {
        // Pin the (variant, lead char) pairing threaded through
        // [`crate::reader::tokenize`]'s outer quote-family dispatch AND
        // its bare-atom terminator disjunct. Quote/Quasiquote's
        // singleton chars project to `'\''` / `` '`' `` respectively;
        // Unquote AND UnquoteSplice BOTH project to `','` because the
        // splice's two-char `,@` prefix shares its lead byte with bare
        // unquote and the reader disambiguates on the peek-then-consume
        // `@` second char. A regression that split the shared-lead-char
        // collapse (e.g. gave UnquoteSplice a distinct lead char)
        // silently re-shapes every splice tokenization; this test
        // catches the drift at rustc + `cargo test` time rather than
        // as an off-by-one reader miscue that surfaces only when a
        // `,@xs` form parses wrong.
        assert_eq!(QuoteForm::Quote.lead_char(), '\'');
        assert_eq!(QuoteForm::Quasiquote.lead_char(), '`');
        assert_eq!(QuoteForm::Unquote.lead_char(), ',');
        assert_eq!(QuoteForm::UnquoteSplice.lead_char(), ',');
    }

    #[test]
    fn quote_form_lead_char_is_first_char_of_prefix_for_every_variant() {
        // COMPOSITION CONTRACT: `lead_char` MUST equal the first char of
        // `prefix()` for every variant. Pin the composition so a
        // regression that drifts one of the two projections (e.g. a
        // rename of `Quote`'s prefix from `"'"` to `"‛"` without
        // updating `lead_char`, or vice versa) surfaces immediately.
        // The typed composition binds the (`QuoteForm`, lead char,
        // full prefix) triple at ONE consistency check across every
        // arm of the closed set — a future fifth homoiconic prefix
        // extension must extend `prefix` AND `lead_char` in lockstep,
        // and this sweep pins the invariant that connects them.
        for qf in QuoteForm::ALL {
            let prefix_first =
                qf.prefix().chars().next().unwrap_or_else(|| {
                    panic!("QuoteForm::{qf:?} prefix must have at least one char")
                });
            assert_eq!(
                qf.lead_char(),
                prefix_first,
                "QuoteForm::{qf:?} — lead_char {:?} drifted from first char of prefix {:?}",
                qf.lead_char(),
                qf.prefix(),
            );
        }
    }

    #[test]
    fn quote_form_from_lead_char_decodes_every_distinct_lead_char_to_default_variant() {
        // Pin the inverse projection at every distinct lead char across
        // the closed set. Quote/Quasiquote decode to their singleton
        // owners; `,` decodes to `Some(Unquote)` (the DEFAULT variant on
        // the shared `,` lead char) — the `,@` splice promotion lives
        // at the reader's peek arm, NOT at this decode. Every other
        // char yields `None`. Includes the tokenizer's non-quote entry
        // chars (`'('`, `')'`, `';'`, `Atom::STR_DELIMITER`, ` `) as
        // the rejection sweep — a regression that leaks a quote-family
        // variant onto a non-quote lead char silently re-shapes every
        // top-level program's tokenization; this rejection sweep
        // catches the drift at test time.
        assert_eq!(QuoteForm::from_lead_char('\''), Some(QuoteForm::Quote));
        assert_eq!(QuoteForm::from_lead_char('`'), Some(QuoteForm::Quasiquote));
        assert_eq!(QuoteForm::from_lead_char(','), Some(QuoteForm::Unquote));

        // Non-quote reader entry chars must reject.
        assert_eq!(QuoteForm::from_lead_char('('), None);
        assert_eq!(QuoteForm::from_lead_char(')'), None);
        assert_eq!(QuoteForm::from_lead_char(';'), None);
        assert_eq!(QuoteForm::from_lead_char(Atom::STR_DELIMITER), None);
        assert_eq!(QuoteForm::from_lead_char(' '), None);
        assert_eq!(QuoteForm::from_lead_char('a'), None);
        assert_eq!(QuoteForm::from_lead_char('@'), None);
        assert_eq!(QuoteForm::from_lead_char(':'), None);
        assert_eq!(QuoteForm::from_lead_char('#'), None);
    }

    #[test]
    fn quote_form_lead_char_round_trips_through_from_lead_char_with_shared_lead_char_collapse() {
        // ROUND-TRIP CONTRACT: for every variant, decoding its
        // `lead_char()` back through `from_lead_char` produces
        // `Some(default_variant_on_that_lead_char)`. For the three
        // variants with singleton lead chars (`Quote`, `Quasiquote`,
        // `Unquote`) the round-trip is the identity. For `UnquoteSplice`
        // — which shares `,` with `Unquote` — the round-trip yields
        // `Some(QuoteForm::Unquote)` because `,` alone cannot signal
        // splice; the reader's peek-then-consume `@` disambiguator is
        // where the splice promotion happens. Pin this asymmetry so
        // a regression that pushed the splice promotion into
        // `from_lead_char` (a natural but wrong refactor) surfaces
        // here at test time — decoupling the char-level decode from
        // the streaming reader's two-char sequence is load-bearing
        // for the tokenizer's structure.
        for qf in QuoteForm::ALL {
            let decoded = QuoteForm::from_lead_char(qf.lead_char());
            let expected = match qf {
                QuoteForm::Quote => Some(QuoteForm::Quote),
                QuoteForm::Quasiquote => Some(QuoteForm::Quasiquote),
                // Both `,`-lead-char variants collapse onto Unquote;
                // splice promotion lives at the reader's peek arm.
                QuoteForm::Unquote | QuoteForm::UnquoteSplice => Some(QuoteForm::Unquote),
            };
            assert_eq!(
                decoded, expected,
                "QuoteForm::{qf:?} — from_lead_char(lead_char) round-trip drifted",
            );
        }
    }

    #[test]
    fn quote_form_from_lead_char_is_const_fn_over_the_closed_set() {
        // Pin the `const fn` posture of both projections by binding a
        // `const` array literal keyed on the closed set. A regression
        // that removed the `const` qualifier (dropping the compile-
        // time evaluability the reader's outer dispatch AND future
        // static lookup tables key on) fails to compile HERE — the
        // `const` context enforces the qualifier without a test-time
        // assertion.
        const _QUOTE: char = QuoteForm::Quote.lead_char();
        const _QUASIQUOTE: char = QuoteForm::Quasiquote.lead_char();
        const _UNQUOTE: char = QuoteForm::Unquote.lead_char();
        const _SPLICE: char = QuoteForm::UnquoteSplice.lead_char();
        const _FROM: Option<QuoteForm> = QuoteForm::from_lead_char(',');
        assert_eq!(_QUOTE, '\'');
        assert_eq!(_QUASIQUOTE, '`');
        assert_eq!(_UNQUOTE, ',');
        assert_eq!(_SPLICE, ',');
        assert_eq!(_FROM, Some(QuoteForm::Unquote));
    }

    #[test]
    fn quote_form_lead_constants_project_canonical_chars() {
        // Pin each constant's byte identity so a typo (`'‛'` for
        // `QUOTE_LEAD`, `'’'` for `QUASIQUOTE_LEAD`, `';'` for
        // `UNQUOTE_LEAD`) or accidental redefinition surfaces
        // immediately. Every canonical per-role reader-punctuation byte
        // on the substrate has its own byte-identity pin at its owning
        // algebra
        // (`atom_str_delimiter_projects_canonical_quote_char`,
        // `atom_str_escape_lead_projects_canonical_backslash_char`,
        // `atom_keyword_marker_lead_projects_canonical_colon_char`,
        // `atom_bool_literal_lead_projects_canonical_hash_char`,
        // `sexp_list_open_projects_canonical_char`,
        // `sexp_list_close_projects_canonical_char`,
        // `sexp_comment_lead_projects_canonical_char`,
        // `sexp_comment_term_projects_canonical_char`,
        // `quote_form_splice_discriminator_projects_canonical_at_char`);
        // this pin closes the three quote-family lead-byte constants at
        // the SAME shape.
        assert_eq!(QuoteForm::QUOTE_LEAD, '\'');
        assert_eq!(QuoteForm::QUASIQUOTE_LEAD, '`');
        assert_eq!(QuoteForm::UNQUOTE_LEAD, ',');
    }

    #[test]
    fn quote_form_lead_constants_round_trip_through_lead_char_projections() {
        // ROUND-TRIP CONTRACT: for each of the three distinct-lead-byte
        // variants (`Quote`, `Quasiquote`, `Unquote`) the (variant →
        // constant → variant) triangle closes exactly.
        // `Self::from_lead_char(Self::X_LEAD) == Some(Self::X)` AND
        // `Self::X.lead_char() == Self::X_LEAD` — the constants ARE the
        // canonical per-variant lead byte both projections route
        // through. `UnquoteSplice` shares its lead byte with `Unquote`
        // (see the merged arm in `lead_char`), so `UnquoteSplice.lead_char()
        // == Self::UNQUOTE_LEAD` too — the splice's SECOND-char
        // `SPLICE_DISCRIMINATOR` promotion lives at the reader's peek
        // arm, not at this decode. Pin the triangle at every variant so
        // a regression that drifts EITHER a constant OR one of the two
        // projection sites surfaces at test time.
        assert_eq!(
            QuoteForm::from_lead_char(QuoteForm::QUOTE_LEAD),
            Some(QuoteForm::Quote),
        );
        assert_eq!(QuoteForm::Quote.lead_char(), QuoteForm::QUOTE_LEAD);

        assert_eq!(
            QuoteForm::from_lead_char(QuoteForm::QUASIQUOTE_LEAD),
            Some(QuoteForm::Quasiquote),
        );
        assert_eq!(
            QuoteForm::Quasiquote.lead_char(),
            QuoteForm::QUASIQUOTE_LEAD,
        );

        assert_eq!(
            QuoteForm::from_lead_char(QuoteForm::UNQUOTE_LEAD),
            Some(QuoteForm::Unquote),
        );
        assert_eq!(QuoteForm::Unquote.lead_char(), QuoteForm::UNQUOTE_LEAD);
        // UnquoteSplice's `lead_char` collapses onto the shared
        // `UNQUOTE_LEAD` byte because the splice's `,@` prefix opens
        // with `,`; the promotion is a two-char peek in the reader.
        assert_eq!(
            QuoteForm::UnquoteSplice.lead_char(),
            QuoteForm::UNQUOTE_LEAD,
        );
    }

    #[test]
    fn quote_form_lead_constants_distinct_from_every_other_algebra_marker_char() {
        // CROSS-AXIS DISJOINTNESS CONTRACT: each of the three quote-
        // family lead bytes MUST differ from every other canonical
        // reader-punctuation constant on the substrate — the other two
        // quote-family lead bytes, `SPLICE_DISCRIMINATOR`,
        // `Atom::STR_DELIMITER`, `Atom::STR_ESCAPE_LEAD`,
        // `Atom::KEYWORD_MARKER_LEAD`, `Atom::BOOL_LITERAL_LEAD`,
        // `Sexp::LIST_OPEN`, `Sexp::LIST_CLOSE`, `Sexp::COMMENT_LEAD`,
        // and `Sexp::COMMENT_TERM`. Otherwise the reader's outer
        // dispatch would ambiguously route a `'` / `` ` `` / `,` lead
        // byte through the aliased sibling arm — e.g. if `QUOTE_LEAD`
        // aliased `Sexp::LIST_OPEN`, a source `'foo` would ambiguously
        // trigger the list-open arm before the quote-family arm ran.
        // Sibling-shape peer of
        // `quote_form_splice_discriminator_distinct_from_every_algebra_marker_char`
        // one axis over.
        // The three distinct-lead-byte rows bind through the typed
        // [`QuoteForm::LEADS`] ALL array — the sub-vocabulary sweep
        // now iterates ONE forced-arity `[char; 3]` array rather than
        // three inline algebra-constant enumerations.
        let leads = QuoteForm::LEADS;
        // Within-family: the three lead bytes are pairwise distinct.
        for (i, a) in leads.iter().enumerate() {
            for b in &leads[i + 1..] {
                assert_ne!(a, b, "quote-family lead bytes must be pairwise distinct",);
            }
        }
        // Cross-family disjointness against every other single-char
        // algebra marker on the substrate.
        for lead in leads {
            assert_ne!(lead, QuoteForm::SPLICE_DISCRIMINATOR);
            assert_ne!(lead, Atom::STR_DELIMITER);
            assert_ne!(lead, Atom::STR_ESCAPE_LEAD);
            assert_ne!(lead, Atom::KEYWORD_MARKER_LEAD);
            assert_ne!(lead, Atom::BOOL_LITERAL_LEAD);
            assert_ne!(lead, Sexp::LIST_OPEN);
            assert_ne!(lead, Sexp::LIST_CLOSE);
            assert_ne!(lead, Sexp::COMMENT_LEAD);
            assert_ne!(lead, Sexp::COMMENT_TERM);
        }
    }

    #[test]
    fn quote_form_unquote_splice_prefix_composes_from_unquote_lead_and_splice_discriminator() {
        // STRUCTURAL COMPOSITION LAW: [`QuoteForm::UnquoteSplice`]'s
        // two-char prefix `",@"` decomposes cleanly into
        // [`QuoteForm::UNQUOTE_LEAD`] (the `,` byte shared with
        // [`QuoteForm::Unquote`]) + [`QuoteForm::SPLICE_DISCRIMINATOR`]
        // (the `@` byte promoted by the reader's peek arm). The two
        // BYTE-LEVEL constants on the closed-set [`QuoteForm`] algebra
        // compose the ONLY two-char [`Self::prefix`] in the closed set
        // — a stronger form of the pre-existing
        // `quote_form_unquote_splice_prefix_composes_from_unquote_prefix_and_splice_discriminator`
        // pin (which composes through the `&'static str` prefix of the
        // Unquote variant). Where that pin binds the `&'static str`-level
        // composition, this pin binds the `char`-level composition; both
        // pins fail loudly on any drift of the `,` or `@` bytes. The
        // reader's two-char peek-then-consume splice-promotion arm
        // reads `Self::UNQUOTE_LEAD` then peeks `Self::SPLICE_DISCRIMINATOR`
        // to promote to `UnquoteSplice` — this identity closes the
        // read↔write duality at the byte level.
        let composed = format!(
            "{}{}",
            QuoteForm::UNQUOTE_LEAD,
            QuoteForm::SPLICE_DISCRIMINATOR,
        );
        assert_eq!(
            composed,
            QuoteForm::UnquoteSplice.prefix(),
            "UnquoteSplice.prefix() drifted from UNQUOTE_LEAD + \
             SPLICE_DISCRIMINATOR — the reader's two-char splice \
             promotion identity is broken at the byte level",
        );
    }

    #[test]
    fn quote_form_lead_constants_are_const_evaluable_over_the_closed_set() {
        // Pin the `const` posture of the three lead constants by binding
        // `const` bindings that ROUTE through the `const fn` lead_char /
        // from_lead_char projections — the compile-time evaluation
        // context enforces the qualifier without a test-time assertion.
        // Sibling posture to
        // `quote_form_from_lead_char_is_const_fn_over_the_closed_set`.
        const _QUOTE: char = QuoteForm::QUOTE_LEAD;
        const _QUASIQUOTE: char = QuoteForm::QUASIQUOTE_LEAD;
        const _UNQUOTE: char = QuoteForm::UNQUOTE_LEAD;
        const _FROM_QUOTE: Option<QuoteForm> = QuoteForm::from_lead_char(QuoteForm::QUOTE_LEAD);
        const _FROM_QUASIQUOTE: Option<QuoteForm> =
            QuoteForm::from_lead_char(QuoteForm::QUASIQUOTE_LEAD);
        const _FROM_UNQUOTE: Option<QuoteForm> = QuoteForm::from_lead_char(QuoteForm::UNQUOTE_LEAD);
        assert_eq!(_QUOTE, '\'');
        assert_eq!(_QUASIQUOTE, '`');
        assert_eq!(_UNQUOTE, ',');
        assert_eq!(_FROM_QUOTE, Some(QuoteForm::Quote));
        assert_eq!(_FROM_QUASIQUOTE, Some(QuoteForm::Quasiquote));
        assert_eq!(_FROM_UNQUOTE, Some(QuoteForm::Unquote));
    }

    #[test]
    fn quote_form_leads_composes_from_algebra_constants_in_declaration_order() {
        // FAMILY COMPOSITION LAW: pin that the ALL array's rows are the
        // three distinct-lead-byte algebra constants (`Self::QUOTE_LEAD`,
        // `Self::QUASIQUOTE_LEAD`, `Self::UNQUOTE_LEAD`) in canonical
        // declaration order matching [`QuoteForm::ALL`]'s three-of-four
        // distinct-lead-byte projection through [`QuoteForm::lead_char`].
        // A reorder of ONE row without reordering the underlying algebra
        // constants silently misaligns every index-sweep consumer (a
        // hypothetical reader outer-dispatch pre-check that keys on
        // `QuoteForm::LEADS[0]`, an LSP completion generator that
        // materialises the distinct-lead-byte set in this order). Sibling-
        // shape pin to
        // `sexp_list_delimiters_composes_from_algebra_constants_in_declaration_order`
        // on the peer `[char; 2]` sub-vocabulary at
        // [`Sexp::LIST_DELIMITERS`].
        assert_eq!(
            QuoteForm::LEADS,
            [
                QuoteForm::QUOTE_LEAD,
                QuoteForm::QUASIQUOTE_LEAD,
                QuoteForm::UNQUOTE_LEAD,
            ],
            "QuoteForm::LEADS composition drifted from the canonical \
             (QUOTE_LEAD, QUASIQUOTE_LEAD, UNQUOTE_LEAD) triple — the \
             distinct-lead-byte sub-vocabulary lift must route through \
             the three typed algebra constants in that order.",
        );
    }

    #[test]
    fn quote_form_leads_has_expected_cardinality() {
        // CARDINALITY PIN: `[char; 3]` at rustc — this assert pins the
        // runtime observable so a refactor that loosens the array's type
        // to `&[char]` (dropping the compile-time arity forcing) fails
        // HERE at the runtime cardinality assertion rather than silently
        // allowing a fourth or absent row. The 3 vs [`QuoteForm::PREFIXES`]'s
        // 4 shape asymmetry IS the structural axis distinguishing the
        // DISTINCT-lead-byte sub-vocabulary from the PER-VARIANT-prefix
        // sub-vocabulary — three-of-four distinct-lead-byte collapse is
        // definitional (only [`QuoteForm::UnquoteSplice`]'s two-char
        // `,@` prefix shares its lead byte with a sibling variant). A
        // regression that grew LEADS to 4 without the shared-lead-byte
        // collapse breaking (i.e. by adding a fourth distinct-lead-byte
        // variant WITHOUT drifting [`QuoteForm::PREFIXES`]'s cardinality
        // to 5 in lockstep) fails at this cardinality pin. Sibling-shape
        // pin to `sexp_list_delimiters_has_expected_cardinality`.
        assert_eq!(
            QuoteForm::LEADS.len(),
            3,
            "QuoteForm::LEADS cardinality drifted from 3 — the distinct-\
             lead-byte sub-vocabulary MUST be exactly three rows because \
             UnquoteSplice shares its lead byte with Unquote by the \
             splice's two-char `,@` prefix construction.",
        );
    }

    #[test]
    fn quote_form_leads_pairwise_distinct() {
        // PAIRWISE DISJOINTNESS: the three distinct-lead-byte rows MUST
        // NOT alias — the closed-set outer [`QuoteForm`] algebra's
        // three-of-four collapse identity depends on Quote / Quasiquote /
        // Unquote owning distinct lead bytes (only UnquoteSplice shares
        // Unquote's lead byte, via the splice's two-char `,@` prefix).
        // A regression that collapsed Quote and Quasiquote onto the same
        // lead byte would silently break the reader's outer dispatch
        // (the tokenizer would ambiguously route both `'foo` and
        // `` `foo `` through the same arm). Sibling-shape pin to
        // `sexp_list_delimiters_pairwise_distinct` on the peer
        // `[char; 2]` sub-vocabulary at [`Sexp::LIST_DELIMITERS`].
        for (i, a) in QuoteForm::LEADS.iter().enumerate() {
            for (j, b) in QuoteForm::LEADS.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "QuoteForm::LEADS rows [{i}] and [{j}] share a byte \
                     ({a:?} == {b:?}) — the distinct-lead-byte contract \
                     across Quote / Quasiquote / Unquote would collapse.",
                );
            }
        }
    }

    #[test]
    fn quote_form_leads_disjoint_from_splice_discriminator() {
        // CROSS-AXIS DISJOINTNESS (splice discriminator): no row of
        // [`QuoteForm::LEADS`] may alias
        // [`QuoteForm::SPLICE_DISCRIMINATOR`] — otherwise the reader's
        // two-char peek-then-consume splice-promotion arm inside
        // [`crate::reader::tokenize`] would ambiguously promote on a
        // sibling lead byte (e.g. if `SPLICE_DISCRIMINATOR` aliased
        // [`QuoteForm::UNQUOTE_LEAD`], a source `,,foo` would silently
        // promote to `UnquoteSplice(,foo)` rather than parsing as
        // `Unquote(Unquote(foo))`). Sibling-shape pin to
        // `sexp_list_delimiters_disjoint_from_str_delimiter`: both close
        // the cross-sub-vocabulary disjointness contract at the ALL-array
        // level rather than as an inline disjunction per consumer.
        for (i, ch) in QuoteForm::LEADS.iter().enumerate() {
            assert_ne!(
                *ch,
                QuoteForm::SPLICE_DISCRIMINATOR,
                "QuoteForm::LEADS[{i}] ({ch:?}) aliases \
                 QuoteForm::SPLICE_DISCRIMINATOR ({:?}) — the reader's \
                 distinct-lead-byte arm would collide with the two-char \
                 splice promotion arm at the same byte.",
                QuoteForm::SPLICE_DISCRIMINATOR,
            );
        }
    }

    #[test]
    fn quote_form_lead_char_routes_through_leads_for_every_variant() {
        // PATH-UNIFORMITY PIN: every [`QuoteForm::lead_char`] projection
        // over the closed set MUST land on a row of [`QuoteForm::LEADS`]
        // — the shared-lead-byte collapse identity (Quote / Quasiquote /
        // Unquote / UnquoteSplice → three distinct lead bytes) binds
        // through the ALL array's `.contains` sweep. A regression that
        // reverted `lead_char`'s arms to inline `char` literals AND
        // drifted one of the four arms without drifting a paired algebra
        // constant fails HERE at the first mismatched variant rather than
        // at a distant reader outer-dispatch drift where a quote-family
        // form silently routes through a bare-atom arm. Sibling-shape
        // pin to
        // `sexp_is_bare_atom_boundary_routes_through_list_delimiters_for_every_row`
        // on the peer `[char; 2]` sub-vocabulary at
        // [`Sexp::LIST_DELIMITERS`], lifted to the four-variant closed
        // set: every one of the four variants collapses onto one of the
        // three LEADS rows.
        for qf in QuoteForm::ALL {
            assert!(
                QuoteForm::LEADS.contains(&qf.lead_char()),
                "QuoteForm::{qf:?}.lead_char() = {:?} is NOT a row of \
                 QuoteForm::LEADS — the shared-lead-byte collapse drifted \
                 from the ALL array's distinct-lead-byte sub-vocabulary.",
                qf.lead_char(),
            );
        }
    }

    #[test]
    fn quote_form_from_lead_char_decodes_every_row_of_leads_to_some() {
        // INVERSE PATH-UNIFORMITY PIN: every row of [`QuoteForm::LEADS`]
        // MUST decode through [`QuoteForm::from_lead_char`] to
        // `Some(_variant_)` (the DEFAULT variant on that lead byte —
        // Unquote on `,`, Quote on `'`, Quasiquote on `` ` ``). A
        // regression that dropped one of the three arms in
        // `from_lead_char`'s match without shrinking [`QuoteForm::LEADS`]
        // in lockstep fails HERE at the first mismatched row rather than
        // as a silent reader outer-dispatch drift where a quote-family
        // lead byte silently falls through to the None arm. This pin
        // closes the round-trip from the DISTINCT-lead-byte axis back
        // through the decode projection at the ALL-array level. Sibling-
        // shape pin to
        // `atom_decode_str_escape_routes_through_self_escape_table_for_every_row`
        // on the peer sub-vocabulary at [`Atom::SELF_ESCAPE_TABLE`].
        for (i, ch) in QuoteForm::LEADS.iter().enumerate() {
            assert!(
                QuoteForm::from_lead_char(*ch).is_some(),
                "QuoteForm::LEADS[{i}] ({ch:?}) decodes to None through \
                 QuoteForm::from_lead_char — the distinct-lead-byte \
                 sub-vocabulary drifted from the decode projection's \
                 non-None arm-set.",
            );
        }
    }

    #[test]
    fn quote_form_leads_matches_dedup_of_prefixes_first_char_set() {
        // CROSS-ARRAY IDENTITY: [`QuoteForm::LEADS`] IS the deduplicated
        // first-char set of [`QuoteForm::PREFIXES`] — the four per-
        // variant prefixes' first chars (`'\''`, `` '`' ``, `','`, `','`)
        // deduplicate onto the three DISTINCT lead bytes exactly matching
        // [`QuoteForm::LEADS`]'s rows. This pin binds the SHAPE-ASYMMETRIC
        // (3 vs 4) relationship between the two ALL arrays: [`QuoteForm::PREFIXES`]
        // enumerates the per-variant prefix-bytes axis; [`QuoteForm::LEADS`]
        // enumerates the DISTINCT lead-byte axis; the two ALL arrays
        // compose through the (first-char, dedup) projection. A regression
        // that drifted EITHER array without drifting the other (e.g. an
        // ELisp-compat port of Quote's prefix to `"#'"` without updating
        // [`QuoteForm::QUOTE_LEAD`]) surfaces here rather than as a
        // silent reader outer-dispatch drift. Sibling-shape pin to
        // `quote_form_per_role_prefixes_route_through_matching_lead_char_for_every_variant`
        // one axis over — that pin binds per-variant; this pin binds
        // per-distinct-lead-byte via the dedup composition. Peer at the
        // ALL-array level to the pre-existing composition tests between
        // NAMED_ESCAPE_TABLE + SELF_ESCAPE_TABLE (which SPAN a total
        // arm-set cardinality; this pin composes a DEDUP arm-set
        // cardinality).
        let mut deduped_first_chars: Vec<char> = QuoteForm::PREFIXES
            .iter()
            .map(|p| {
                p.chars().next().unwrap_or_else(|| {
                    panic!("QuoteForm::PREFIXES entry `{p}` must have at least one char")
                })
            })
            .collect();
        deduped_first_chars.sort_unstable();
        deduped_first_chars.dedup();

        let mut leads_sorted: Vec<char> = QuoteForm::LEADS.to_vec();
        leads_sorted.sort_unstable();

        assert_eq!(
            deduped_first_chars, leads_sorted,
            "QuoteForm::LEADS drifted from the deduplicated first-char \
             set of QuoteForm::PREFIXES — the (per-variant prefix axis) \
             × (distinct-lead-byte axis) shape-asymmetric composition \
             identity is broken.",
        );
    }

    #[test]
    fn quote_form_splice_discriminator_projects_canonical_at_char() {
        // Pin the constant's byte identity so a typo (`'!'`, `'?'`,
        // `'~'`) or accidental redefinition surfaces immediately. The
        // reader's peek arm inside [`crate::reader::tokenize`] AND the
        // splice-promotion table [`QuoteForm::promote_via_next_char`]
        // BOTH bind to this constant; a drift here would silently re-
        // shape every `,@xs` tokenization into a `,` + `@xs` two-token
        // sequence (or into a phantom promotion on a different
        // second-char), and this pin catches the drift at test time.
        assert_eq!(QuoteForm::SPLICE_DISCRIMINATOR, '@');
    }

    #[test]
    fn quote_form_splice_discriminator_distinct_from_every_algebra_marker_char() {
        // CROSS-AXIS DISJOINTNESS CONTRACT: the splice discriminator
        // `@` must NOT alias any other canonical reader-punctuation
        // constant on the substrate — every [`QuoteForm::lead_char`]
        // projection, [`crate::ast::Atom::STR_DELIMITER`],
        // [`crate::ast::Atom::KEYWORD_MARKER`]'s lead byte,
        // [`crate::ast::Sexp::LIST_OPEN`], [`crate::ast::Sexp::LIST_CLOSE`],
        // [`crate::ast::Sexp::COMMENT_LEAD`], and both
        // [`crate::ast::Atom::bool_literal`] spellings' lead bytes.
        // Otherwise the two-char `,@` splice-promotion arm inside the
        // reader would ambiguously route through the splice arm AND a
        // sibling algebra's arm at the outer dispatch — e.g. if
        // `SPLICE_DISCRIMINATOR` aliased [`Sexp::LIST_OPEN`], a source
        // `,(a b)` would ambiguously promote-and-consume the `(` before
        // the list-opening arm ran. Pin the disjointness across every
        // sibling constant so a future rename catches the collision at
        // test time rather than as a silent tokenizer drift.
        assert_ne!(
            QuoteForm::SPLICE_DISCRIMINATOR,
            QuoteForm::Quote.lead_char()
        );
        assert_ne!(
            QuoteForm::SPLICE_DISCRIMINATOR,
            QuoteForm::Quasiquote.lead_char()
        );
        assert_ne!(
            QuoteForm::SPLICE_DISCRIMINATOR,
            QuoteForm::Unquote.lead_char()
        );
        assert_ne!(
            QuoteForm::SPLICE_DISCRIMINATOR,
            QuoteForm::UnquoteSplice.lead_char()
        );
        assert_ne!(QuoteForm::SPLICE_DISCRIMINATOR, Atom::STR_DELIMITER);
        assert_ne!(QuoteForm::SPLICE_DISCRIMINATOR, Sexp::LIST_OPEN);
        assert_ne!(QuoteForm::SPLICE_DISCRIMINATOR, Sexp::LIST_CLOSE);
        assert_ne!(QuoteForm::SPLICE_DISCRIMINATOR, Sexp::COMMENT_LEAD);
        // The KEYWORD_MARKER prefix's canonical LEAD `char` lives at
        // the typed `Atom::KEYWORD_MARKER_LEAD` constant on the closed-
        // set outer [`Atom`] algebra. Pre-lift this slot held an inline
        // `Atom::KEYWORD_MARKER.chars().next().expect(_)` extraction;
        // post-lift the byte lives at ONE named constant that the
        // [`Atom::KEYWORD_MARKER`] `&'static str` projects to (pinned
        // by `atom_keyword_marker_lead_prefixes_keyword_marker`).
        assert_ne!(QuoteForm::SPLICE_DISCRIMINATOR, Atom::KEYWORD_MARKER_LEAD);
        // Both `#t` / `#f` spellings share `Atom::BOOL_LITERAL_LEAD`
        // (`'#'`) as the lead byte. Pre-lift each spelling was
        // extracted via `Atom::bool_literal(b).chars().next().expect(_)`
        // — TWO assertions for the SAME byte by construction. Post-
        // lift both collapse to ONE assertion routing through the
        // typed constant; the structural invariant "both spellings
        // share the lead byte" lives at
        // `atom_bool_literal_lead_prefixes_every_bool_literal_spelling`
        // rather than as a per-spelling boilerplate duplication here.
        assert_ne!(QuoteForm::SPLICE_DISCRIMINATOR, Atom::BOOL_LITERAL_LEAD);
    }

    #[test]
    fn quote_form_promote_via_next_char_only_promotes_unquote_on_splice_discriminator() {
        // Pin the closed-set promotion table: EXACTLY the singleton
        // `(Unquote, SPLICE_DISCRIMINATOR) → Some(UnquoteSplice)` arm
        // triggers; every other `(variant, char)` pairing yields
        // `None`. Sweeps every `QuoteForm::ALL` variant against the
        // splice discriminator AND against a broad rejection set
        // (whitespace, `(`, `)`, `;`, `Atom::STR_DELIMITER`, `a`, `,`,
        // `'`, `` ` ``) so a regression that widens the promotion
        // table (e.g. promotes `Quote` on `@` to a phantom variant,
        // or promotes `Unquote` on `'` after a copy-paste drift)
        // surfaces at test time. Sibling to
        // `quote_form_from_lead_char_decodes_every_distinct_lead_char_to_default_variant`
        // one axis over on the closed-set entry-char algebra — this
        // sweep pins the two-char extension of that one-char decode.
        for qf in QuoteForm::ALL {
            let promoted = qf.promote_via_next_char(QuoteForm::SPLICE_DISCRIMINATOR);
            let expected = if matches!(qf, QuoteForm::Unquote) {
                Some(QuoteForm::UnquoteSplice)
            } else {
                None
            };
            assert_eq!(
                promoted, expected,
                "QuoteForm::{qf:?} — promotion table drifted on SPLICE_DISCRIMINATOR",
            );
            // Every non-discriminator char must reject for every variant.
            for rejection_char in [
                ' ',
                '\n',
                '\t',
                Sexp::LIST_OPEN,
                Sexp::LIST_CLOSE,
                Sexp::COMMENT_LEAD,
                Atom::STR_DELIMITER,
                'a',
                ',',
                '\'',
                '`',
                '#',
                ':',
                '!',
                '?',
                '~',
            ] {
                assert_eq!(
                    qf.promote_via_next_char(rejection_char),
                    None,
                    "QuoteForm::{qf:?} — promotion table leaked on non-\
                     discriminator char {rejection_char:?}",
                );
            }
        }
    }

    #[test]
    fn quote_form_promote_via_next_char_is_const_fn_over_the_closed_set() {
        // Pin the `const fn` posture by binding a `const` array
        // literal of promotions keyed on the closed set. A regression
        // that removed the `const` qualifier (dropping the compile-
        // time evaluability the reader's peek arm AND future static
        // lookup tables key on) fails to compile HERE — the `const`
        // context enforces the qualifier without a test-time
        // assertion. Sibling posture to
        // `quote_form_from_lead_char_is_const_fn_over_the_closed_set`.
        const _QUOTE: Option<QuoteForm> =
            QuoteForm::Quote.promote_via_next_char(QuoteForm::SPLICE_DISCRIMINATOR);
        const _QUASIQUOTE: Option<QuoteForm> =
            QuoteForm::Quasiquote.promote_via_next_char(QuoteForm::SPLICE_DISCRIMINATOR);
        const _UNQUOTE: Option<QuoteForm> =
            QuoteForm::Unquote.promote_via_next_char(QuoteForm::SPLICE_DISCRIMINATOR);
        const _SPLICE: Option<QuoteForm> =
            QuoteForm::UnquoteSplice.promote_via_next_char(QuoteForm::SPLICE_DISCRIMINATOR);
        assert_eq!(_QUOTE, None);
        assert_eq!(_QUASIQUOTE, None);
        assert_eq!(_UNQUOTE, Some(QuoteForm::UnquoteSplice));
        assert_eq!(_SPLICE, None);
    }

    #[test]
    fn quote_form_promote_via_next_char_composes_prefix_from_source_prefix_and_next_char() {
        // COMPOSITION IDENTITY: for every `qf: QuoteForm` and every
        // `c: char`, if `qf.promote_via_next_char(c) == Some(promoted)`
        // then `format!("{}{}", qf.prefix(), c) == promoted.prefix()`.
        // Pin the (variant, next char) → promoted-variant projection
        // agrees with the reader's rendered `Self::prefix` composition,
        // so a regression that drifts one side of the identity
        // surfaces immediately. Sibling to
        // `quote_form_lead_char_is_first_char_of_prefix_for_every_variant`
        // one axis up on the closed-set entry-char algebra.
        for qf in QuoteForm::ALL {
            if let Some(promoted) = qf.promote_via_next_char(QuoteForm::SPLICE_DISCRIMINATOR) {
                let composed = format!("{}{}", qf.prefix(), QuoteForm::SPLICE_DISCRIMINATOR);
                assert_eq!(
                    composed,
                    promoted.prefix(),
                    "QuoteForm::{qf:?} — promotion composition drifted from \
                     promoted prefix ({promoted:?}.prefix() = {:?})",
                    promoted.prefix(),
                );
            }
        }
    }

    #[test]
    fn quote_form_unquote_splice_prefix_composes_from_unquote_prefix_and_splice_discriminator() {
        // STRUCTURAL COMPOSITION LAW: [`QuoteForm::UnquoteSplice`]'s
        // two-char prefix `",@"` decomposes cleanly into
        // [`QuoteForm::Unquote`]'s prefix `","` + the splice
        // discriminator byte `'@'`. Pin the identity directly rather
        // than through the promotion table so a regression that
        // renamed the discriminator without touching the promotion
        // table (or vice versa) surfaces here. This IS the structural
        // identity the reader's peek-then-consume arm depends on: the
        // tokenizer sees `,` (Unquote lead char), peeks `@`
        // (SPLICE_DISCRIMINATOR), and emits UnquoteSplice — the
        // rendered prefix identity closes the read↔write duality.
        let composed = format!(
            "{}{}",
            QuoteForm::Unquote.prefix(),
            QuoteForm::SPLICE_DISCRIMINATOR,
        );
        assert_eq!(
            composed,
            QuoteForm::UnquoteSplice.prefix(),
            "UnquoteSplice.prefix() drifted from Unquote.prefix() + \
             SPLICE_DISCRIMINATOR — the reader's two-char splice \
             promotion identity is broken",
        );
    }

    // ── `QuoteForm::PROMOTIONS` — the closed-set forced-arity array of
    // promotion triples on the substrate's quote-family algebra. Pins
    // the singleton `(Unquote, SPLICE_DISCRIMINATOR, UnquoteSplice)`
    // entry AND its alignment with `promote_via_next_char`'s Some-arm
    // AND the family-wide contract sweeps below. Sibling-shape tests to
    // the `quote_form_hash_discriminators_*` block on the outer-Sexp
    // cache-key axis — that block anchors the `[u8; 4]` byte algebra;
    // this block anchors the `[(Self, char, Self); 1]` promotion
    // algebra one axis over on the same closed set.

    #[test]
    fn quote_form_promotions_has_expected_cardinality() {
        // FORCED-ARITY CONTRACT: [`QuoteForm::PROMOTIONS`]'s
        // cardinality is `1` at the type level — the substrate's
        // current promotion algebra has EXACTLY ONE promotion arm
        // (`(Unquote, SPLICE_DISCRIMINATOR, UnquoteSplice)`). A
        // regression that widened the array without extending
        // [`QuoteForm::promote_via_next_char`]'s match body (or vice
        // versa) fails compilation because the array literal's arity
        // is forced by the `[_; 1]` type annotation. This runtime
        // pin closes the same law at a runtime cardinality check
        // so a callsite that expects the singleton shape without
        // static-arity inference (a dynamic iteration site, an
        // audit-log emitter that reports the promotion-algebra size
        // for observability) reads through ONE substrate primitive
        // rather than through a hand-rolled `1usize` literal.
        assert_eq!(
            QuoteForm::PROMOTIONS.len(),
            1,
            "QuoteForm::PROMOTIONS cardinality drifted from the \
             substrate's singleton promotion algebra — the closed-set \
             array's forced arity is load-bearing on the `(Unquote, \
             SPLICE_DISCRIMINATOR) → UnquoteSplice` singleton identity",
        );
    }

    #[test]
    fn quote_form_promotions_pin_legacy_splice_promotion_triple() {
        // LEGACY-TRIPLE CONTRACT: [`QuoteForm::PROMOTIONS`]'s
        // singleton entry is byte-for-byte `(Self::Unquote,
        // Self::SPLICE_DISCRIMINATOR, Self::UnquoteSplice)`. Pin each
        // column of the triple against its typed source:
        //   * head    == QuoteForm::Unquote           (the `,` variant)
        //   * disc    == QuoteForm::SPLICE_DISCRIMINATOR (`'@'`)
        //   * promoted == QuoteForm::UnquoteSplice     (the `,@` variant)
        // A regression that drifts ONE column of the triple silently
        // redirects the reader's promotion arm to a phantom variant
        // AND fails HERE at the per-column identity check rather
        // than at silent tokenizer drift where every `,@xs` source
        // tokenizes to the wrong closed-set marker.
        assert_eq!(
            QuoteForm::PROMOTIONS[0].0,
            QuoteForm::Unquote,
            "QuoteForm::PROMOTIONS[0].0 (head) drifted from Unquote — \
             the substrate's singleton promotion arm's head variant \
             MUST be Unquote (the only variant whose prefix is the \
             lead byte of a longer variant's prefix)",
        );
        assert_eq!(
            QuoteForm::PROMOTIONS[0].1,
            QuoteForm::SPLICE_DISCRIMINATOR,
            "QuoteForm::PROMOTIONS[0].1 (discriminator) drifted from \
             SPLICE_DISCRIMINATOR — the substrate's singleton \
             promotion arm's discriminator MUST be the byte the \
             reader's peek arm consumes to promote the head variant \
             (the ONE `'@'` byte on the closed-set algebra)",
        );
        assert_eq!(
            QuoteForm::PROMOTIONS[0].2,
            QuoteForm::UnquoteSplice,
            "QuoteForm::PROMOTIONS[0].2 (promoted) drifted from \
             UnquoteSplice — the substrate's singleton promotion \
             arm's promoted variant MUST be UnquoteSplice (the only \
             two-char-prefix variant on the closed-set algebra)",
        );
    }

    #[test]
    fn quote_form_promotions_align_with_promote_via_next_char_for_every_entry() {
        // ALIGNMENT CONTRACT: sweep [`QuoteForm::PROMOTIONS`] and
        // assert that for every `(head, disc, promoted)` entry,
        // `head.promote_via_next_char(disc) == Some(promoted)`. This
        // is the projection method's forward composition law at the
        // closed set — a regression that drifts the promoted-variant
        // column of the constant (or the projection method's Some-arm
        // return literal) surfaces here rather than as a silent
        // tokenizer redirect. Sibling-shape pin to
        // `quote_form_hash_discriminators_align_with_all_by_index`
        // one axis over on the cache-key byte algebra — that pin
        // aligns the `[u8; 4]` array with the projection method's
        // per-variant arm; this pin aligns the `[(Self, char, Self);
        // 1]` array with the projection method's per-triple arm.
        for (head, disc, promoted) in QuoteForm::PROMOTIONS {
            let projected = head.promote_via_next_char(disc);
            assert_eq!(
                projected,
                Some(promoted),
                "QuoteForm::PROMOTIONS[({head:?}, {disc:?}, \
                 {promoted:?})] — `promote_via_next_char` drifted \
                 from the constant's promoted-variant column (got \
                 {projected:?})",
            );
        }
    }

    #[test]
    fn quote_form_promotions_compose_prefix_from_source_prefix_and_discriminator_for_every_entry() {
        // COMPOSITION LAW (rendered-prefix identity): sweep
        // [`QuoteForm::PROMOTIONS`] and assert that for every
        // `(head, disc, promoted)` entry, `format!("{}{}",
        // head.prefix(), disc) == promoted.prefix()`. The
        // (head prefix + discriminator) source-text composition
        // agrees byte-for-byte with the promoted variant's rendered
        // prefix — the reader's peek-then-consume arm's rendered
        // prefix identity closes the read↔write duality across
        // every entry in the promotion algebra.
        //
        // Sibling to the pre-existing
        // `quote_form_promote_via_next_char_composes_prefix_from_source_prefix_and_next_char`
        // which pins the same law through
        // [`QuoteForm::promote_via_next_char`]'s Some-arm rather
        // than through the constant's triple directly — this pin
        // closes the law at the constant, that pin closes it at the
        // projection method. Together the two pins bind the
        // rendered-prefix identity to BOTH the substrate primitive
        // AND the projection method so a regression that drifts
        // ONE side of the identity fails at BOTH pins rather than at
        // silent read/write drift where a reader-tokenized `,@xs`
        // form's rendered prefix disagrees with its typed marker's
        // rendered prefix.
        for (head, disc, promoted) in QuoteForm::PROMOTIONS {
            let composed = format!("{}{}", head.prefix(), disc);
            assert_eq!(
                composed,
                promoted.prefix(),
                "QuoteForm::PROMOTIONS[({head:?}, {disc:?}, \
                 {promoted:?})] — head.prefix() + disc drifted from \
                 promoted.prefix() ({:?})",
                promoted.prefix(),
            );
        }
    }

    #[test]
    fn quote_form_promotions_close_promote_via_next_char_against_every_non_promotion_pair() {
        // REJECTION CONTRACT: sweep [`QuoteForm::ALL`] × (every
        // (head, disc) pair from [`QuoteForm::PROMOTIONS`] plus every
        // rejection discriminator distinct from the promotion set's
        // discriminator column) and assert that every pair NOT in
        // [`QuoteForm::PROMOTIONS`]'s `(head, disc)` projection
        // rejects with `None`. A regression that widened the
        // promotion algebra (e.g. phantom-promoted [`QuoteForm::Quote`]
        // on `'@'` after a copy-paste drift on the match arm's head
        // pattern, OR silently promoted `Unquote` on a non-`@`
        // discriminator after a drift on the match arm's char
        // pattern) fails HERE at the sweep-time rejection assertion
        // rather than at silent tokenizer drift where bare `'@xs`
        // forms degrade to a phantom `UnquoteSplice`-shaped sequence
        // OR bare `,'xs` forms silently promote through the reader.
        //
        // Sibling-shape pin to the pre-existing
        // `quote_form_promote_via_next_char_only_promotes_unquote_on_splice_discriminator`
        // which sweeps every variant against SPLICE_DISCRIMINATOR
        // AND a hand-rolled rejection char set; this pin extends the
        // rejection sweep to compose the rejection set STRUCTURALLY
        // from [`QuoteForm::PROMOTIONS`]'s complement rather than
        // hand-rolling a rejection char literal list at a callsite
        // that would silently drift as the algebra grows.
        //
        // The rejection char set is composed as: every
        // [`QuoteForm::ALL`] variant's [`QuoteForm::lead_char`] (the
        // three quote-family lead bytes `{'\'', '`', ','}`), every
        // char in [`QuoteForm::PROMOTIONS`]'s discriminator column
        // (the ONE `'@'` byte — used to verify that variants NOT in
        // the promotion set's head column reject on the same
        // discriminator), and a hand-rolled sweep of non-quote-family
        // rejection chars (whitespace, structural, reader-punctuation)
        // to cover the closed-set-complement rejection surface.
        let mut discriminators: Vec<char> =
            QuoteForm::ALL.iter().map(|qf| qf.lead_char()).collect();
        for (_, disc, _) in QuoteForm::PROMOTIONS {
            if !discriminators.contains(&disc) {
                discriminators.push(disc);
            }
        }
        for extra in [
            ' ',
            '\n',
            '\t',
            Sexp::LIST_OPEN,
            Sexp::LIST_CLOSE,
            Sexp::COMMENT_LEAD,
            Atom::STR_DELIMITER,
            'a',
            '#',
            ':',
            '!',
            '?',
            '~',
        ] {
            if !discriminators.contains(&extra) {
                discriminators.push(extra);
            }
        }

        let promotion_pairs: Vec<(QuoteForm, char)> = QuoteForm::PROMOTIONS
            .iter()
            .map(|(head, disc, _)| (*head, *disc))
            .collect();

        for head in QuoteForm::ALL {
            for disc in &discriminators {
                let in_promotion_set = promotion_pairs.contains(&(head, *disc));
                let projected = head.promote_via_next_char(*disc);
                if in_promotion_set {
                    // Positive arms are covered by
                    // `quote_form_promotions_align_with_promote_via_next_char_for_every_entry`;
                    // skip here to keep this pin's focus on the
                    // rejection surface exclusively.
                    continue;
                }
                assert_eq!(
                    projected, None,
                    "QuoteForm::{head:?}.promote_via_next_char({disc:?}) \
                     — promotion algebra leaked on a pair NOT in \
                     QuoteForm::PROMOTIONS (got {projected:?}, \
                     expected None)",
                );
            }
        }
    }

    #[test]
    fn quote_form_promote_via_next_char_routes_promoted_variant_through_promotions_constant() {
        // ROUTING CONTRACT: pin that
        // [`QuoteForm::promote_via_next_char`]'s Some-arm return
        // BINDS through [`QuoteForm::PROMOTIONS`]`[0].2` rather than
        // through an inline [`QuoteForm::UnquoteSplice`] literal.
        // Post-lift the projection method's Some-arm reads:
        //   `Some(Self::PROMOTIONS[0].2)`
        // — so a regression that reverts the arm to an inline
        // `Some(Self::UnquoteSplice)` fails HERE at the byte-identity
        // sweep, WHERE the projected value is compared against
        // [`QuoteForm::PROMOTIONS`]`[0].2` directly rather than
        // against an inline literal.
        //
        // Sibling-shape pin to
        // `sexp_shape_hash_discriminator_atomic_arms_route_through_atom_kind_outer_hash_discriminator`
        // (prior-run 39537b2) one axis over on the cache-key byte
        // algebra — that pin binds the shape-level projection's
        // atomic-arm collapse to the typed constant; this pin binds
        // the promotion projection's Some-arm to the typed triple's
        // promoted-variant column. Together the two pins close the
        // "projection routes through the substrate primitive" pattern
        // across the cache-key axis AND the promotion axis on the
        // closed-set algebra.
        let projected = QuoteForm::Unquote.promote_via_next_char(QuoteForm::SPLICE_DISCRIMINATOR);
        assert_eq!(
            projected,
            Some(QuoteForm::PROMOTIONS[0].2),
            "QuoteForm::Unquote.promote_via_next_char(SPLICE_DISCRIMINATOR) \
             — Some-arm return drifted from routing through \
             QuoteForm::PROMOTIONS[0].2 (got {projected:?})",
        );
    }

    #[test]
    fn quote_form_hash_discriminator_pins_legacy_cache_key_bytes() {
        // CACHE-KEY CONTRACT: pre-lift `Hash for Sexp` used the literal
        // byte values 3/4/5/6 for Quote/Quasiquote/Unquote/UnquoteSplice
        // as the per-variant discriminator. The 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 non-quote-family Hash arms use (0=Nil,
        // 1=Atom, 2=List). Pin the four legacy values explicitly so a
        // regression that re-numbers them surfaces immediately — the
        // `QuoteForm` algebra MUST preserve the prior byte mapping
        // bit-for-bit.
        assert_eq!(QuoteForm::Quote.hash_discriminator(), 3);
        assert_eq!(QuoteForm::Quasiquote.hash_discriminator(), 4);
        assert_eq!(QuoteForm::Unquote.hash_discriminator(), 5);
        assert_eq!(QuoteForm::UnquoteSplice.hash_discriminator(), 6);
    }

    // ── `QuoteForm::{QUOTE_HASH_DISCRIMINATOR,
    // QUASIQUOTE_HASH_DISCRIMINATOR, UNQUOTE_HASH_DISCRIMINATOR,
    // UNQUOTE_SPLICE_HASH_DISCRIMINATOR, HASH_DISCRIMINATORS}` —
    // per-role `u8` cache-key byte algebra on the closed-set outer
    // [`QuoteForm`]. Fourth per-role axis on the algebra alongside the
    // reader-prefix (commit a08e61f), diagnostic-label (commit
    // 70be157), and iac-forge canonical-form tag (commit bdd624b)
    // `&'static str` axes — closes the FOUR production
    // byte-vocabularies the closed set carries at ONE `pub(crate)
    // const` per (role, vocabulary) pair plus a family-wide ALL array
    // per vocabulary.

    #[test]
    fn quote_form_hash_discriminators_pin_legacy_cache_key_bytes() {
        // Pin each per-role `pub(crate) const` at its exact canonical
        // `u8` byte. Sibling of
        // `quote_form_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 `{3, 4, 5, 6}` is load-bearing
        // for the outer-`Sexp` `Hash` body's disjointness contract
        // with the reserved bytes `{0, 1, 2}` the non-quote-family
        // arms use — a `4u8` drift to `2u8` would silently collide
        // with `StructuralKind::List`'s cache-key byte and mis-hash
        // every quasi-quote through the list-arm's path.
        assert_eq!(QuoteForm::QUOTE_HASH_DISCRIMINATOR, 3);
        assert_eq!(QuoteForm::QUASIQUOTE_HASH_DISCRIMINATOR, 4);
        assert_eq!(QuoteForm::UNQUOTE_HASH_DISCRIMINATOR, 5);
        assert_eq!(QuoteForm::UNQUOTE_SPLICE_HASH_DISCRIMINATOR, 6);
    }

    #[test]
    fn quote_form_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
        // `3` / `4` / `5` / `6` `u8` literal (or drifts one arm's
        // byte silently). Sibling posture to
        // `quote_form_prefix_routes_through_typed_per_role_constants`
        // on the reader-prefix axis of the SAME closed set.
        for (qf, expected) in [
            (QuoteForm::Quote, QuoteForm::QUOTE_HASH_DISCRIMINATOR),
            (
                QuoteForm::Quasiquote,
                QuoteForm::QUASIQUOTE_HASH_DISCRIMINATOR,
            ),
            (QuoteForm::Unquote, QuoteForm::UNQUOTE_HASH_DISCRIMINATOR),
            (
                QuoteForm::UnquoteSplice,
                QuoteForm::UNQUOTE_SPLICE_HASH_DISCRIMINATOR,
            ),
        ] {
            let actual = qf.hash_discriminator();
            assert_eq!(
                actual, expected,
                "QuoteForm::{qf:?}.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 quote_form_hash_discriminators_has_expected_cardinality() {
        // Cardinality contract: `Self::HASH_DISCRIMINATORS.len() == 4`
        // — pinned at the declaration site by rustc's forced-arity
        // check on `[u8; 4]`. 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
        // `quote_form_prefixes_has_expected_cardinality`,
        // `quote_form_labels_has_expected_cardinality`, and
        // `quote_form_iac_forge_tags_has_expected_cardinality` on the
        // other three per-role axes of the SAME [`QuoteForm`] closed
        // set.
        assert_eq!(
            QuoteForm::HASH_DISCRIMINATORS.len(),
            4,
            "QuoteForm::HASH_DISCRIMINATORS cardinality drifted from \
             4 — the closed homoiconic-prefix domain admits exactly \
             four wrappers by construction; a fifth extension \
             surfaces here"
        );
    }

    #[test]
    fn quote_form_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 `quote_form_prefixes_align_with_all_by_index`
        // on the reader-prefix axis.
        for (i, qf) in QuoteForm::ALL.iter().enumerate() {
            assert_eq!(
                QuoteForm::HASH_DISCRIMINATORS[i],
                qf.hash_discriminator(),
                "QuoteForm::HASH_DISCRIMINATORS[{i}] `{disc}` drifted \
                 from QuoteForm::ALL[{i}] ({qf:?}).hash_discriminator() \
                 `{via_variant}` — the canonical declaration order of \
                 the ALL array and the hash_discriminator projection \
                 must match element-wise",
                disc = QuoteForm::HASH_DISCRIMINATORS[i],
                via_variant = qf.hash_discriminator(),
            );
        }
    }

    #[test]
    fn quote_form_hash_discriminators_pairwise_distinct() {
        // PAIRWISE DISJOINTNESS: every entry of the
        // `HASH_DISCRIMINATORS` array must differ so the outer-`Sexp`
        // `Hash` body cannot route two homoiconic prefixes through
        // the same cache-key byte — a collision would silently mis-
        // hash two structurally-distinct forms 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
        // `quote_form_prefixes_pairwise_distinct`.
        for (i, a) in QuoteForm::HASH_DISCRIMINATORS.iter().enumerate() {
            for (j, b) in QuoteForm::HASH_DISCRIMINATORS.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "QuoteForm::HASH_DISCRIMINATORS[{i}] `{a}` \
                     collides with QuoteForm::HASH_DISCRIMINATORS[{j}] \
                     `{b}` — the outer-Sexp Hash body's cache-key \
                     partition would route two homoiconic prefixes \
                     through the same slot"
                );
            }
        }
    }

    #[test]
    fn quote_form_hash_discriminators_disjoint_from_reserved_outer_sexp_bytes() {
        // CROSS-AXIS DISJOINTNESS CONTRACT: every entry of
        // `Self::HASH_DISCRIMINATORS` must differ from the reserved
        // outer-`Sexp` bytes the non-quote-family arms use — `0u8`
        // for [`crate::error::StructuralKind::Nil`], `1u8` for the
        // [`crate::ast::Sexp::Atom`] outer-carve marker, `2u8` for
        // [`crate::error::StructuralKind::List`]. The three carvings
        // of the outer-`Sexp` cache-key space jointly cover
        // `{0, 1, 2, 3, 4, 5, 6}` with no gaps AND no overlaps; a
        // regression that re-numbers a quote-family discriminator
        // into the reserved region silently mis-hashes every affected
        // form. Pin the disjointness across every reserved byte so a
        // future rename catches the collision at test time rather
        // than as a silent cache-key drift where
        // `Expander::cache` mis-collides live expansions.
        let reserved_non_quote_family_bytes: [u8; 3] = [
            crate::error::StructuralKind::Nil.hash_discriminator(),
            1u8, // Sexp::Atom outer-carve marker (pre-lift inline literal in Hash for Sexp)
            crate::error::StructuralKind::List.hash_discriminator(),
        ];
        for (i, quote_family_byte) in QuoteForm::HASH_DISCRIMINATORS.iter().enumerate() {
            for reserved_byte in reserved_non_quote_family_bytes {
                assert_ne!(
                    *quote_family_byte, reserved_byte,
                    "QuoteForm::HASH_DISCRIMINATORS[{i}] `{quote_family_byte}` \
                     collides with reserved non-quote-family cache-key byte \
                     `{reserved_byte}` — the outer-Sexp Hash body's three-\
                     carving partition is broken"
                );
            }
        }
    }

    #[test]
    fn quote_form_as_unquote_form_projects_two_of_four_subset() {
        // The structural-subset gate: only `{Unquote, UnquoteSplice}`
        // are template-substitution markers; `{Quote, Quasiquote}` are
        // wrappers whose semantic does NOT include substitution. Pin
        // the 2-of-4 partition so the `Sexp::as_unquote` derivation's
        // closed-set arithmetic stays correct.
        assert_eq!(
            QuoteForm::Unquote.as_unquote_form(),
            Some(UnquoteForm::Unquote)
        );
        assert_eq!(
            QuoteForm::UnquoteSplice.as_unquote_form(),
            Some(UnquoteForm::Splice)
        );
        assert_eq!(QuoteForm::Quote.as_unquote_form(), None);
        assert_eq!(QuoteForm::Quasiquote.as_unquote_form(), None);
    }

    #[test]
    fn quote_form_iac_forge_tag_pins_canonical_lisp_tag_strings_for_every_variant() {
        // CROSS-CRATE CANONICAL-FORM CONTRACT: the four canonical
        // iac-forge tags are load-bearing for inter-crate compatibility
        // — `iac_forge::sexpr::SExpr` consumers (BLAKE3 attestation,
        // render cache) key on the canonical 2-element-list shape
        // `(<tag> <inner>)`. A regression that drifts ONE tag silently
        // invalidates every cached canonical form across the substrate
        // AND mis-collides with the legacy `SexpShape::label` projection
        // that uses the shorter `"unquote-splice"` for the diagnostic
        // surface. Pin the four legacy tag values explicitly so a
        // regression that re-spells them surfaces immediately.
        assert_eq!(QuoteForm::Quote.iac_forge_tag(), "quote");
        assert_eq!(QuoteForm::Quasiquote.iac_forge_tag(), "quasiquote");
        assert_eq!(QuoteForm::Unquote.iac_forge_tag(), "unquote");
        assert_eq!(QuoteForm::UnquoteSplice.iac_forge_tag(), "unquote-splicing");
    }

    // ── `QuoteForm::{QUOTE_IAC_FORGE_TAG, QUASIQUOTE_IAC_FORGE_TAG,
    // UNQUOTE_IAC_FORGE_TAG, UNQUOTE_SPLICE_IAC_FORGE_TAG,
    // IAC_FORGE_TAGS}` — per-role `&'static str` iac-forge canonical-
    // form tag algebra on the closed-set outer [`QuoteForm`]. Peer of
    // the reader-prefix axis's [`QuoteForm::{QUOTE_PREFIX,
    // QUASIQUOTE_PREFIX, UNQUOTE_PREFIX, UNQUOTE_SPLICE_PREFIX,
    // PREFIXES}`] block above — the same closed set carries TWO
    // orthogonal byte vocabularies (the Lisp reader prefixes the
    // tokenizer classifies on, the iac-forge canonical-form tags the
    // cross-crate attestation layer round-trips through), each now
    // pinned at a per-role `pub const` plus a paired ALL array.
    #[test]
    fn quote_form_per_role_iac_forge_tags_pin_canonical_bytes() {
        // Pin each per-role `pub const` at its exact canonical byte
        // sequence. Sweeping via a per-variant pair rather than four
        // hand-rolled `assert_eq!(QuoteForm::X_IAC_FORGE_TAG, "x")`
        // asserts (a) that each constant IS the load-bearing byte
        // string, and (b) that the pairing between the const and the
        // spelling is enforced at rustc's constant-folding-level so a
        // future rename of the const surfaces here as a spelling drift
        // rather than as a silent canonical-form regression.
        for (label, actual, expected) in [
            (
                "QUOTE_IAC_FORGE_TAG",
                QuoteForm::QUOTE_IAC_FORGE_TAG,
                "quote",
            ),
            (
                "QUASIQUOTE_IAC_FORGE_TAG",
                QuoteForm::QUASIQUOTE_IAC_FORGE_TAG,
                "quasiquote",
            ),
            (
                "UNQUOTE_IAC_FORGE_TAG",
                QuoteForm::UNQUOTE_IAC_FORGE_TAG,
                "unquote",
            ),
            (
                "UNQUOTE_SPLICE_IAC_FORGE_TAG",
                QuoteForm::UNQUOTE_SPLICE_IAC_FORGE_TAG,
                "unquote-splicing",
            ),
        ] {
            assert_eq!(
                actual, expected,
                "QuoteForm::{label} drifted from canonical `{expected}` bytes"
            );
        }
    }

    #[test]
    fn quote_form_iac_forge_tag_routes_through_typed_per_role_constants() {
        // PATH-UNIFORMITY: `Self::iac_forge_tag(self)` returns the
        // per-role `pub const` byte-for-byte per variant, catching a
        // regression that reverts ONE arm to an inline `"quote"` /
        // `"quasiquote"` / `"unquote"` / `"unquote-splicing"` string
        // literal (or drifts one arm's bytes silently). Sibling posture
        // to `quote_form_prefix_routes_through_typed_per_role_constants`
        // on the reader-prefix axis of the SAME closed set.
        for (qf, expected) in [
            (QuoteForm::Quote, QuoteForm::QUOTE_IAC_FORGE_TAG),
            (QuoteForm::Quasiquote, QuoteForm::QUASIQUOTE_IAC_FORGE_TAG),
            (QuoteForm::Unquote, QuoteForm::UNQUOTE_IAC_FORGE_TAG),
            (
                QuoteForm::UnquoteSplice,
                QuoteForm::UNQUOTE_SPLICE_IAC_FORGE_TAG,
            ),
        ] {
            let actual = qf.iac_forge_tag();
            assert_eq!(
                actual, expected,
                "QuoteForm::{qf:?}.iac_forge_tag() `{actual}` drifted from \
                 per-role constant `{expected}` — the arm must route \
                 through the typed constant rather than an inline literal",
            );
        }
    }

    #[test]
    fn quote_form_iac_forge_tags_has_expected_cardinality() {
        // Cardinality contract: `Self::IAC_FORGE_TAGS.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
        // `quote_form_prefixes_has_expected_cardinality` on the peer
        // reader-prefix axis.
        assert_eq!(
            QuoteForm::IAC_FORGE_TAGS.len(),
            4,
            "QuoteForm::IAC_FORGE_TAGS cardinality drifted from 4 — the \
             closed homoiconic-prefix domain admits exactly four \
             wrappers by construction; a fifth extension surfaces here"
        );
    }

    #[test]
    fn quote_form_iac_forge_tags_align_with_all_by_index() {
        // ALIGNMENT CONTRACT: `Self::IAC_FORGE_TAGS[i] ==
        // Self::ALL[i].iac_forge_tag()` element-wise. Pins that the
        // typed variant ALL and the `&'static str` IAC_FORGE_TAGS ALL
        // stay in lockstep under any reorder — a regression that
        // reorders ONE array without reordering the other silently
        // misaligns every `zip(ALL, IAC_FORGE_TAGS)` consumer (cross-
        // crate attestation renderers, LSP canonical-form completion
        // providers, metric-label emitters, coverage reporters).
        // Sibling posture to `quote_form_prefixes_align_with_all_by_index`
        // on the peer reader-prefix axis.
        for (i, qf) in QuoteForm::ALL.iter().enumerate() {
            assert_eq!(
                QuoteForm::IAC_FORGE_TAGS[i],
                qf.iac_forge_tag(),
                "QuoteForm::IAC_FORGE_TAGS[{i}] `{tag}` drifted from \
                 QuoteForm::ALL[{i}] ({qf:?}).iac_forge_tag() `{via_variant}` \
                 — the canonical declaration order of the ALL array \
                 and the iac-forge tag projection must match element-wise",
                tag = QuoteForm::IAC_FORGE_TAGS[i],
                via_variant = qf.iac_forge_tag(),
            );
        }
    }

    #[test]
    fn quote_form_iac_forge_tags_pairwise_distinct() {
        // PAIRWISE DISJOINTNESS: every entry of the `IAC_FORGE_TAGS`
        // array must differ so the cross-crate canonical-form decoder
        // (any future `IAC_FORGE_TAGS.iter().find(|t| *t == head)`
        // sweep, any BLAKE3 attestation key comparison) cannot route
        // two homoiconic prefixes through the same tag arm. Family-wide
        // sweep over `IAC_FORGE_TAGS × IAC_FORGE_TAGS` — supersedes any
        // per-pair pin and picks up new tags mechanically. Sibling
        // posture to `quote_form_prefixes_pairwise_distinct` on the
        // peer reader-prefix axis.
        for (i, a) in QuoteForm::IAC_FORGE_TAGS.iter().enumerate() {
            for (j, b) in QuoteForm::IAC_FORGE_TAGS.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "QuoteForm::IAC_FORGE_TAGS[{i}] `{a}` collides with \
                     QuoteForm::IAC_FORGE_TAGS[{j}] `{b}` — the \
                     canonical-form decoder's cascade would route two \
                     homoiconic prefixes through the same tag arm"
                );
            }
        }
    }

    #[test]
    fn quote_form_iac_forge_tags_diverge_from_prefixes_pairwise() {
        // AXIS-ORTHOGONALITY: `IAC_FORGE_TAGS` (the cross-crate
        // canonical-form axis) and `PREFIXES` (the Lisp reader-prefix
        // axis) span two distinct byte vocabularies on the SAME closed
        // set. Every per-variant pair must disagree: the canonical
        // tags are word-length identifiers (`"quote"`, `"quasiquote"`,
        // `"unquote"`, `"unquote-splicing"`) while the reader prefixes
        // are punctuation (`"'"`, `` "`" ``, `","`, `",@"`). A
        // regression that collapsed the two axes (a hypothetical
        // consolidation PR that reused `iac_forge_tag()`'s bytes at
        // the reader prefix site, or vice versa) would silently break
        // either the source-code round-trip (readers no longer see
        // `"'"`) OR the canonical-form round-trip (attestation keys
        // no longer see `"quote"`). Sweep every variant's per-axis
        // pair — supersedes any per-variant pin and picks up new
        // prefix/tag pairs mechanically.
        for (i, qf) in QuoteForm::ALL.iter().enumerate() {
            let prefix = QuoteForm::PREFIXES[i];
            let tag = QuoteForm::IAC_FORGE_TAGS[i];
            assert_ne!(
                prefix, tag,
                "QuoteForm::{qf:?} — reader prefix `{prefix}` collides \
                 with iac-forge tag `{tag}`; the two axes must span \
                 distinct byte vocabularies on the closed set",
            );
        }
    }

    #[test]
    fn quote_form_iac_forge_tag_diverges_from_sexp_shape_label_for_unquote_splice() {
        // BOUNDARY-DISTINCT CONTRACT: the iac-forge canonical tag for
        // `UnquoteSplice` is `"unquote-splicing"` (Common Lisp idiom,
        // load-bearing for canonical-form round-trip with the iac-forge
        // ecosystem), distinct from `SexpShape::label`'s shorter
        // `"unquote-splice"` (the substrate's diagnostic label idiom).
        // The two projections key the SAME closed-set on TWO distinct
        // boundaries — pinning the divergence here documents the
        // intent: a future "consolidation" PR that homogenizes them
        // would silently break either the iac-forge canonical-form
        // round-trip OR the operator-facing diagnostic surface. The
        // three other variants (Quote, Quasiquote, Unquote) DO match
        // across both projections — pin that path-uniformity too so a
        // regression that drifts one of the three matched arms surfaces
        // immediately. Sibling-arm sweep so the (variant, tag) AND
        // (variant, label) pairings stay load-bearing under reordering
        // refactors.
        use crate::error::SexpShape;
        assert_eq!(
            QuoteForm::Quote.iac_forge_tag(),
            SexpShape::Quote.label(),
            "quote tag/label agreement"
        );
        assert_eq!(
            QuoteForm::Quasiquote.iac_forge_tag(),
            SexpShape::Quasiquote.label(),
            "quasiquote tag/label agreement"
        );
        assert_eq!(
            QuoteForm::Unquote.iac_forge_tag(),
            SexpShape::Unquote.label(),
            "unquote tag/label agreement"
        );
        // The intentional divergence — load-bearing for the iac-forge
        // canonical form vs the substrate's diagnostic label.
        assert_eq!(QuoteForm::UnquoteSplice.iac_forge_tag(), "unquote-splicing");
        assert_eq!(SexpShape::UnquoteSplice.label(), "unquote-splice");
        assert_ne!(
            QuoteForm::UnquoteSplice.iac_forge_tag(),
            SexpShape::UnquoteSplice.label(),
            "the two projections must disagree at UnquoteSplice — the CL canonical \
             form requires '-splicing' while the substrate's diagnostic label uses \
             the shorter '-splice'; consolidating them would break either side",
        );
    }

    #[test]
    fn quote_form_from_iac_forge_tag_decodes_each_canonical_tag_to_its_variant() {
        // TYPED INVERSE CONTRACT: the four canonical CL tag literals
        // `"quote"` / `"quasiquote"` / `"unquote"` / `"unquote-splicing"`
        // decode through `QuoteForm::from_iac_forge_tag` to their exact
        // `QuoteForm` variant — the inbound iac-forge canonical-form
        // decode surface's per-arm truth table. Sibling posture to
        // `quote_form_iac_forge_tag_pins_canonical_lisp_tag_strings_for_every_variant`
        // on the OUTBOUND projection axis: that pin binds each variant to
        // its canonical tag; THIS pin binds each canonical tag to its
        // variant, closing the (outbound, inbound) roundtrip pair at ONE
        // typed method on the algebra rather than at TWO surfaces the
        // consumer would have to hand-roll independently.
        //
        // A regression that drifts ONE arm's inbound decode (a future
        // refactor that inlines the four-arm sweep and drops the
        // `"quasiquote"` arm, a byte-drifted rename that leaves the
        // outbound `iac_forge_tag()` unchanged but breaks the inverse)
        // fails-loudly here on the affected arm before any downstream
        // iac-forge canonical-form consumer surfaces the drift.
        assert_eq!(
            QuoteForm::from_iac_forge_tag("quote"),
            Some(QuoteForm::Quote),
        );
        assert_eq!(
            QuoteForm::from_iac_forge_tag("quasiquote"),
            Some(QuoteForm::Quasiquote),
        );
        assert_eq!(
            QuoteForm::from_iac_forge_tag("unquote"),
            Some(QuoteForm::Unquote),
        );
        assert_eq!(
            QuoteForm::from_iac_forge_tag("unquote-splicing"),
            Some(QuoteForm::UnquoteSplice),
        );
    }

    #[test]
    fn quote_form_from_iac_forge_tag_round_trips_through_iac_forge_tag_for_every_variant() {
        // TYPED ROUNDTRIP CONTRACT: for every `qf` in `QuoteForm::ALL`,
        // `QuoteForm::from_iac_forge_tag(qf.iac_forge_tag()) == Some(qf)`
        // — the composition of the outbound projection with the inbound
        // inverse decoder yields the identity on the closed four-arm
        // domain. Sibling posture to
        // `quote_form_lead_char_round_trips_through_from_lead_char_for_every_variant`
        // one axis over on the reader-lead-char inverse decoder — both
        // pin the (forward, inverse) composition-identity at the closed
        // set's canonical carrier variants without relying on the
        // per-arm inbound truth table above (which pins the arm-by-arm
        // decoder mapping; this pin binds the closed-set-wide roundtrip
        // property that emerges from the arm mapping).
        //
        // A regression that breaks ONE variant's roundtrip (a future
        // refactor that drops `QuoteForm::Unquote` from `Self::ALL`
        // silently while leaving the outbound `iac_forge_tag()` arm
        // intact, an inbound decoder that returns `Some(Self::Quote)`
        // for an unrelated variant's tag) fails-loudly here through the
        // closed-set sweep, catching the drift on the affected variant.
        for &qf in QuoteForm::ALL.iter() {
            let outbound = qf.iac_forge_tag();
            let inbound = QuoteForm::from_iac_forge_tag(outbound);
            assert_eq!(
                inbound,
                Some(qf),
                "QuoteForm::{qf:?} — outbound iac_forge_tag `{outbound}` \
                 failed to round-trip through from_iac_forge_tag",
            );
        }
    }

    #[test]
    fn quote_form_from_iac_forge_tag_rejects_empty_input() {
        // EMPTY-INPUT REJECTION: the empty string `""` is structurally
        // outside the four-arm canonical CL tag closed set — no variant
        // projects to `""` through `iac_forge_tag`, so the inverse
        // decode rejects cleanly with `None`. Pins the empty-input
        // boundary case operators hit when a canonical-form field is
        // absent or blank but the decode is reached anyway (a
        // deserialization codepath that reads an empty tag slot, an
        // LSP quick-fix that surfaces an empty completion buffer).
        // Sibling posture to `parse_label_rejects_empty_input` on the
        // closed-set trait's parse-rejection axis one vocabulary over
        // (reader-punctuation) — both pin the empty-input rejection so
        // no future implementor can drift the decoder's empty-input
        // behavior accidentally.
        assert_eq!(QuoteForm::from_iac_forge_tag(""), None);
    }

    #[test]
    fn quote_form_from_iac_forge_tag_is_case_sensitive() {
        // CASE-SENSITIVE CONTRACT: the four canonical CL tag literals
        // are the exact byte sequences the iac-forge canonical form
        // renders; case drift between the caller's input and the
        // canonical literal is a REJECTION, not a normalization. Pin
        // the case-sensitive contract across (a) an all-uppercase
        // drift (`"QUOTE"`), (b) a title-case drift (`"Quote"`), and
        // (c) an internal-uppercase drift on the multi-word tag
        // (`"Unquote-Splicing"`, `"unquote-Splicing"`) — the three
        // representative case-drift shapes future operator input
        // could reach.
        //
        // A regression that relaxes the decode to case-insensitive (an
        // overzealous normalization pass, an `eq_ignore_ascii_case`
        // introduction) silently subsumes the substrate-wide
        // case-sensitive convention that binds the iac-forge
        // canonical-form bytes to the SexpShape diagnostic-label bytes'
        // path-uniformity (the two vocabularies share three of four
        // arms byte-for-byte and disagree at UnquoteSplice — any
        // future case-insensitive relaxation on ONE axis would silently
        // bifurcate the two vocabularies' convention).
        assert_eq!(QuoteForm::from_iac_forge_tag("QUOTE"), None);
        assert_eq!(QuoteForm::from_iac_forge_tag("Quote"), None);
        assert_eq!(QuoteForm::from_iac_forge_tag("Unquote-Splicing"), None);
        assert_eq!(QuoteForm::from_iac_forge_tag("unquote-Splicing"), None);
    }

    #[test]
    fn quote_form_from_iac_forge_tag_rejects_substrate_diagnostic_label_bytes() {
        // AXIS-BOUNDARY CONTRACT: the SHORTER substrate diagnostic
        // label `"unquote-splice"` (which `SexpShape::UnquoteSplice.label()`
        // renders) MUST reject through the iac-forge canonical-form
        // decoder — the CL canonical form requires the LONGER
        // `"unquote-splicing"` per the intentional divergence pinned by
        // `quote_form_iac_forge_tag_diverges_from_sexp_shape_label_for_unquote_splice`.
        // The two vocabularies are ORTHOGONAL axes on the SAME closed
        // four-arm outer set; a decoder keyed on the iac-forge axis
        // MUST reject an input on the diagnostic-label axis, or the
        // (canonical-form, diagnostic-label) axis-orthogonality
        // collapses silently.
        //
        // A regression that accepts the shorter substrate diagnostic
        // label at the iac-forge inbound decode (a hypothetical
        // "consolidation" that merges the two vocabularies at the
        // decoder boundary, a future decoder that walks BOTH
        // `SexpShape::LABELS` AND `Self::IAC_FORGE_TAGS`) would
        // silently bifurcate every iac-forge round-trip consumer:
        // the outbound `iac_forge_tag()` still renders
        // `"unquote-splicing"`, but the inbound decode accepts BOTH
        // spellings — a canonical form emitted with the shorter
        // substrate diagnostic label would re-decode as
        // `QuoteForm::UnquoteSplice` even though it was never a valid
        // iac-forge canonical form to begin with. Pin the rejection
        // explicitly so the axis boundary stays enforced at the
        // decoder itself, not just at the outbound projection.
        assert_eq!(QuoteForm::from_iac_forge_tag("unquote-splice"), None);
    }

    #[test]
    fn quote_form_from_iac_forge_tag_rejects_non_canonical_tag_strings() {
        // GENERAL-REJECTION CONTRACT: inputs outside the four-arm
        // canonical CL tag image reject cleanly with `None`. Pins a
        // representative sweep across (a) arbitrary non-tag words that
        // share no substring with the canonical vocabulary
        // (`"hello"`, `"foo"`), (b) reader-punctuation bytes that
        // belong to the ORTHOGONAL `Self::PREFIXES` axis and MUST
        // route through `FromStr` (not this decoder) — the vocabulary
        // boundary the axis-orthogonality contract carries, (c) the
        // SexpShape diagnostic labels for non-quote-family arms
        // (`"symbol"`, `"list"`) which project to `None` through
        // `SexpShape::iac_forge_tag` and therefore MUST reject here
        // too.
        //
        // A regression that accepts a reader-punctuation byte here (a
        // future consolidated decoder that walks BOTH the prefix
        // vocabulary AND the iac-forge-tag vocabulary) would silently
        // subsume the [`FromStr`] surface's exclusive claim to the
        // reader-punctuation axis, breaking every consumer that binds
        // decoder identity to vocabulary axis. Pin the rejections
        // explicitly so the vocabulary axis stays enforced at the
        // decoder boundary itself, not just at the outbound projection.
        for input in [
            "hello", "foo",
            // Reader-punctuation vocabulary — belongs to
            // `Self::PREFIXES` / `Self::FromStr`, MUST reject here.
            "'", "`", ",", ",@",
            // SexpShape labels for non-quote-family shapes — no
            // iac-forge tag projection at these variants, MUST reject.
            "symbol", "list", "nil",
        ] {
            assert_eq!(
                QuoteForm::from_iac_forge_tag(input),
                None,
                "QuoteForm::from_iac_forge_tag({input:?}) accepted a \
                 non-canonical iac-forge tag input — the decoder must \
                 reject every string outside the four-arm canonical CL \
                 tag image",
            );
        }
    }

    #[test]
    fn quote_form_from_iac_forge_tag_composes_through_iac_forge_tags_array() {
        // COMPOSITION-LAW CONTRACT: sweeping the family-wide
        // `Self::IAC_FORGE_TAGS` array through `from_iac_forge_tag`
        // yields the parallel `Self::ALL` array element-wise —
        // `from_iac_forge_tag(Self::IAC_FORGE_TAGS[i]) ==
        // Some(Self::ALL[i])` for every `i in 0..4`. The composition
        // binds the two family-wide forced-arity arrays through the
        // typed inverse decoder at ONE typed sweep on the algebra,
        // matching the alignment law
        // `quote_form_iac_forge_tags_align_with_all_by_index` on the
        // outbound projection sibling.
        //
        // Enforces the (typed variant, canonical tag) forward-and-
        // back closure at the array level: a regression that drifts
        // ONE array's contents against the other (a future refactor
        // that reorders `Self::IAC_FORGE_TAGS` without reordering
        // `Self::ALL`, a rename that breaks the alignment) fails-
        // loudly here through the composition sweep before any
        // downstream `zip(ALL, IAC_FORGE_TAGS)` consumer with an
        // inbound decoder in hand surfaces the misalignment.
        for (i, &tag) in QuoteForm::IAC_FORGE_TAGS.iter().enumerate() {
            let decoded = QuoteForm::from_iac_forge_tag(tag);
            let expected = QuoteForm::ALL[i];
            assert_eq!(
                decoded,
                Some(expected),
                "QuoteForm::from_iac_forge_tag(IAC_FORGE_TAGS[{i}] = {tag:?}) \
                 decoded to {decoded:?}, expected Some({expected:?}) \
                 (the composition of IAC_FORGE_TAGS with from_iac_forge_tag \
                 must yield ALL element-wise)",
            );
        }
    }

    #[test]
    fn quote_form_from_iac_forge_tag_is_injective_on_canonical_domain() {
        // INJECTIVITY CONTRACT: distinct canonical CL tags in
        // `Self::IAC_FORGE_TAGS` decode to distinct typed variants
        // through `from_iac_forge_tag` — the inverse decoder is
        // injective on the closed four-arm canonical-tag domain.
        // Sibling posture to the outbound
        // `quote_form_iac_forge_tags_pairwise_distinct` on the same
        // closed set: that pin asserts the four canonical-tag literals
        // are pairwise distinct; THIS pin asserts the DECODED variants
        // are also pairwise distinct — the pair together enforces
        // BOTH sides of the two-way injectivity contract that the
        // (typed variant, canonical tag) bijection carries on the
        // closed set.
        //
        // A regression that decodes two distinct canonical tags to
        // the same typed variant (a future refactor that collapses
        // `Quasiquote` and `Quote` decode arms silently, an off-by-
        // one in the linear sweep that returns the wrong variant for
        // ONE tag) fails-loudly here at the decoded-set cardinality
        // check before any downstream consumer surfaces the decoded-
        // side collapse.
        let decoded: Vec<QuoteForm> = QuoteForm::IAC_FORGE_TAGS
            .iter()
            .filter_map(|tag| QuoteForm::from_iac_forge_tag(tag))
            .collect();
        assert_eq!(
            decoded.len(),
            QuoteForm::ALL.len(),
            "QuoteForm::from_iac_forge_tag failed to decode one or more \
             canonical tags — the composition of IAC_FORGE_TAGS with \
             from_iac_forge_tag lost {} arms (expected {} — the closed \
             set's cardinality)",
            QuoteForm::ALL.len() - decoded.len(),
            QuoteForm::ALL.len(),
        );
        for i in 0..decoded.len() {
            for j in (i + 1)..decoded.len() {
                assert_ne!(
                    decoded[i], decoded[j],
                    "QuoteForm::from_iac_forge_tag is not injective on the \
                     canonical-tag domain — decoded[{i}] ({:?}) and \
                     decoded[{j}] ({:?}) collide",
                    decoded[i], decoded[j],
                );
            }
        }
    }

    #[test]
    fn quote_form_sexp_shape_pins_canonical_shape_identity_for_every_variant() {
        // CLOSED-SET SHAPE-PROJECTION CONTRACT: each `QuoteForm` variant
        // projects to its matching `SexpShape` variant — load-bearing for
        // the (Sexp variant, SexpShape variant) pairing the substrate's
        // outer-shape projection `domain::sexp_shape` routes through.
        // Sibling-arm sweep so the four pairings stay load-bearing under
        // reordering refactors. A regression that drifts ONE arm (e.g.
        // routes `QuoteForm::Quote` to `SexpShape::Quasiquote`) surfaces
        // here immediately rather than as a silent operator-facing
        // diagnostic drift at every `LispError::TypeMismatch.got` slot
        // for a quote-family witness.
        use crate::error::SexpShape;
        assert_eq!(QuoteForm::Quote.sexp_shape(), SexpShape::Quote);
        assert_eq!(QuoteForm::Quasiquote.sexp_shape(), SexpShape::Quasiquote);
        assert_eq!(QuoteForm::Unquote.sexp_shape(), SexpShape::Unquote);
        assert_eq!(
            QuoteForm::UnquoteSplice.sexp_shape(),
            SexpShape::UnquoteSplice
        );
    }

    #[test]
    fn quote_form_sexp_shape_composes_with_label_for_canonical_short_diagnostic_string() {
        // COMPOSITION-LAW CONTRACT: `qf.sexp_shape().label()` is the
        // canonical short diagnostic string for the quote-family marker
        // — `"quote"`, `"quasiquote"`, `"unquote"`, `"unquote-splice"`.
        // The composition law binds the substrate's typed marker
        // (`QuoteForm`) to its diagnostic surface (`SexpShape::label`)
        // through ONE algebra so a future change to either projection's
        // label (e.g. a substrate-wide rename of `"unquote-splice"` to
        // `"splice"`) rides through the typed composition rather than
        // requiring an inline match at every diagnostic-construction
        // site that previously hand-paired the marker with its label.
        // Pin the short labels here — DISTINCT from the iac-forge tag's
        // `"unquote-splicing"` (load-bearing for the boundary distinction
        // already pinned by
        // `quote_form_iac_forge_tag_diverges_from_sexp_shape_label_for_unquote_splice`).
        assert_eq!(QuoteForm::Quote.sexp_shape().label(), "quote");
        assert_eq!(QuoteForm::Quasiquote.sexp_shape().label(), "quasiquote");
        assert_eq!(QuoteForm::Unquote.sexp_shape().label(), "unquote");
        assert_eq!(
            QuoteForm::UnquoteSplice.sexp_shape().label(),
            "unquote-splice"
        );
    }

    #[test]
    fn quote_form_label_projects_each_variant_to_canonical_diagnostic_label() {
        // PER-ARM CONTRACT: pin the outer-`QuoteForm` `Self::label`
        // projection produces the FOUR canonical short diagnostic labels
        // byte-for-byte across every reachable quote-family variant.
        // Pre-lift the outer-`QuoteForm` diagnostic-label projection had
        // no typed primitive on the marker algebra — a consumer with a
        // `QuoteForm` in hand wanting the canonical short label had to
        // spell the two-step composition `qf.sexp_shape().label()` at
        // every callsite (a shape pinned as a load-bearing composition
        // law by `quote_form_sexp_shape_composes_with_label_for_canonical_short_diagnostic_string`
        // one arm above), OR go through `qf.wrap(inner).type_name()`
        // which wraps and projects for no runtime purpose. Post-lift the
        // FOUR arms bind at ONE typed projection on the outer-`QuoteForm`
        // algebra that routes through `SexpShape::label` — the
        // (QuoteForm variant, label string) pairing binds at ONE typed
        // algebra composition spanning THREE typed layers (`QuoteForm`
        // → `SexpShape` → `&'static str`).
        //
        // Sibling-shape pin to
        // `atom_label_projects_each_variant_to_canonical_diagnostic_label`
        // one algebra layer down (outer-`Atom` label pin) and
        // `sexp_type_name_covers_every_variant` one algebra layer up
        // (outer-`Sexp` type_name pin). A regression that drifts ONE
        // arm's mapping (e.g. renaming `"unquote-splice"` to `"splice"`
        // inline here, dropping the `Unquote → "unquote"` boundary
        // rename) fails-loudly at THIS test AND the sibling
        // `SexpShape::label` per-arm pin.
        assert_eq!(QuoteForm::Quote.label(), "quote");
        assert_eq!(QuoteForm::Quasiquote.label(), "quasiquote");
        assert_eq!(QuoteForm::Unquote.label(), "unquote");
        assert_eq!(QuoteForm::UnquoteSplice.label(), "unquote-splice");
    }

    #[test]
    fn quote_form_label_composes_through_sexp_shape_label_for_every_variant() {
        // COMPOSITION-LAW CONTRACT: `qf.label() == qf.sexp_shape().label()`
        // for every reachable quote-family marker — the outer-`QuoteForm`
        // label projection is structurally derived through `Self::sexp_shape`
        // + `SexpShape::label` rather than through a parallel four-arm
        // inline match on the outer-`QuoteForm` algebra. Pin the
        // composition law so a future refactor that re-inlines the four
        // quote-family literals here (and gains its own drift surface
        // separate from the `SexpShape::label` canonical site) surfaces
        // immediately. The pointer-equality check pins the composition
        // produces the SAME `&'static str` (not just a byte-equal copy)
        // for every variant — proof the routing hits ONE static literal
        // site (`SexpShape::label` via `QuoteForm::sexp_shape().label()`)
        // rather than a parallel inline table on the outer-`QuoteForm`
        // algebra.
        //
        // Sibling-shape pin to
        // `atom_label_composes_through_kind_label_for_every_variant` on
        // the outer-`Atom` value / `AtomKind` marker pair and
        // `sexp_type_name_method_composes_through_shape_label_for_every_outer_shape`
        // on the outer-`Sexp` value / `SexpShape` marker pair. The three
        // routing pins jointly enforce the (outer-value, canonical label)
        // pairing stays a full three-layer typed composition on every
        // typed-value algebra rather than degrading to a per-layer inline
        // literal table.
        for qf in QuoteForm::ALL {
            let via_label = qf.label();
            let via_composition = qf.sexp_shape().label();
            assert_eq!(
                via_label, via_composition,
                "QuoteForm::label() must route through self.sexp_shape().label() \
                 for {qf:?} — drift here means the lift was reverted to inline arms",
            );
            assert!(
                std::ptr::eq(via_label.as_ptr(), via_composition.as_ptr()),
                "QuoteForm::label() must return the SAME `&'static str` as \
                 self.sexp_shape().label() for {qf:?} — pointer drift means \
                 the lift composes through a parallel literal table rather \
                 than routing into the canonical SexpShape::label site",
            );
        }
    }

    #[test]
    fn quote_form_label_agrees_with_sexp_type_name_at_every_quote_form_arm() {
        // CROSS-ALGEBRA AGREEMENT CONTRACT: for every quote-family marker
        // `qf` and every inner body `inner`, `qf.label() ==
        // qf.wrap(inner.clone()).type_name()`. The agreement is a TYPED
        // CONSEQUENCE of the two typed compositions —
        // `qf.wrap(inner).type_name()` routes through `Sexp::shape()`'s
        // quote-family arms which compose with `SexpShape::label`
        // byte-for-byte with `qf.sexp_shape().label()` (which itself IS
        // the body of `qf.label()`). A regression that drifts either side
        // of the cross-algebra bridge (an outer-`QuoteForm` label
        // re-inlined onto a different literal, an outer-`Sexp` quote-arm
        // re-routed through a stale shape projection, a
        // `QuoteForm::sexp_shape` arm that swaps two markers) fails-
        // loudly here rather than as a silent operator-facing diagnostic
        // drift at every consumer that pattern-matches on the outer-
        // `Sexp` label vs the outer-`QuoteForm` label independently.
        //
        // Sibling posture to
        // `atom_label_agrees_with_sexp_type_name_at_every_atom_arm` on
        // the atomic-payload carving — that pin binds the outer-value-
        // level vocabulary containment (`Atom::label ==
        // Sexp::Atom(_).type_name()`), this pin binds the same
        // containment on the quote-family carving (`QuoteForm::label ==
        // QuoteForm::wrap(_).type_name()`) so the THREE-layer typed
        // composition on the outer-`QuoteForm` algebra and the FOUR-
        // layer typed composition on the outer-`Sexp` algebra agree at
        // their common quote-family arms.
        let inner = Sexp::symbol("x");
        for qf in QuoteForm::ALL {
            let via_quote_form = qf.label();
            let via_sexp = qf.wrap(inner.clone()).type_name();
            assert_eq!(
                via_quote_form, via_sexp,
                "QuoteForm::label() must agree with QuoteForm::wrap(_).type_name() \
                 for {qf:?} — cross-algebra label drift at the quote-family arms \
                 would fracture the typed diagnostic vocabulary between the \
                 outer-QuoteForm and outer-Sexp algebras",
            );
            assert!(
                std::ptr::eq(via_quote_form.as_ptr(), via_sexp.as_ptr()),
                "QuoteForm::label() must return the SAME `&'static str` as \
                 QuoteForm::wrap(_).type_name() for {qf:?} — pointer drift means \
                 one algebra layer re-inlined the literal rather than routing \
                 into the canonical `SexpShape::label` site",
            );
        }
    }

    #[test]
    fn quote_form_label_diverges_from_iac_forge_tag_for_unquote_splice() {
        // BOUNDARY-DISTINCT CONTRACT: at the `UnquoteSplice` arm,
        // `qf.label() == "unquote-splice"` (the substrate's diagnostic
        // label idiom) while `qf.iac_forge_tag() == "unquote-splicing"`
        // (the Common-Lisp canonical form, load-bearing for canonical-
        // form round-trip with the iac-forge ecosystem). The two
        // projections key the SAME closed-set on TWO distinct boundaries
        // — pinning the divergence on the NEW typed peer documents the
        // intent: a future "consolidation" PR that homogenizes `label`
        // and `iac_forge_tag` at the `UnquoteSplice` arm would silently
        // break either the iac-forge canonical-form round-trip OR the
        // operator-facing diagnostic surface. Sibling-arm posture to
        // `quote_form_iac_forge_tag_diverges_from_sexp_shape_label_for_unquote_splice`
        // which pinned the divergence at the `qf.sexp_shape().label()`
        // composition; this pin lifts the divergence contract onto the
        // NEW `QuoteForm::label` typed peer. The three other variants
        // (Quote, Quasiquote, Unquote) DO match across both projections
        // — pin that path-uniformity too so a regression that drifts one
        // of the three matched arms surfaces immediately.
        assert_eq!(
            QuoteForm::Quote.iac_forge_tag(),
            QuoteForm::Quote.label(),
            "quote tag/label agreement",
        );
        assert_eq!(
            QuoteForm::Quasiquote.iac_forge_tag(),
            QuoteForm::Quasiquote.label(),
            "quasiquote tag/label agreement",
        );
        assert_eq!(
            QuoteForm::Unquote.iac_forge_tag(),
            QuoteForm::Unquote.label(),
            "unquote tag/label agreement",
        );
        // The intentional divergence — load-bearing for the iac-forge
        // canonical form vs the substrate's diagnostic label.
        assert_eq!(QuoteForm::UnquoteSplice.iac_forge_tag(), "unquote-splicing");
        assert_eq!(QuoteForm::UnquoteSplice.label(), "unquote-splice");
        assert_ne!(
            QuoteForm::UnquoteSplice.iac_forge_tag(),
            QuoteForm::UnquoteSplice.label(),
            "the two projections must disagree at UnquoteSplice — the CL canonical \
             form requires '-splicing' while the substrate's diagnostic label uses \
             the shorter '-splice'; consolidating them would break either side",
        );
    }

    #[test]
    fn quote_form_per_role_labels_alias_sexp_shape_per_role_labels_byte_for_byte() {
        // ALIAS CONTRACT: pin every one of the four per-role
        // `pub const QuoteForm::*_LABEL` aliases equals the corresponding
        // `pub const SexpShape::*_LABEL` byte-for-byte — so the QuoteForm
        // ⊂ SexpShape marker-vocabulary containment routes through the
        // typed `pub const QuoteForm::V_LABEL: &'static str =
        // SexpShape::V_LABEL` alias chain rather than through two
        // independent literal-discipline sites. A regression that renames
        // the SexpShape side without updating the QuoteForm alias
        // pointing at it fails-loudly here with the exact axis identified
        // (QUOTE / QUASIQUOTE / UNQUOTE / UNQUOTE_SPLICE); a regression
        // that re-inlines the QuoteForm constant to a fresh literal still
        // passes this pin but loses the alias-chain typing (which is what
        // `quote_form_label_arms_route_through_per_role_labels_for_every_variant`
        // + `quote_form_labels_align_with_all_by_index` catch in
        // combination).
        //
        // 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 and
        // `structural_kind_per_role_labels_alias_sexp_shape_per_role_labels_byte_for_byte`
        // on the peer 2-of-12 structural-residual carving — this pin
        // closes the fourth and final SexpShape sub-carving's alias-chain
        // contract at the exact same shape.
        assert_eq!(QuoteForm::QUOTE_LABEL, SexpShape::QUOTE_LABEL);
        assert_eq!(QuoteForm::QUASIQUOTE_LABEL, SexpShape::QUASIQUOTE_LABEL);
        assert_eq!(QuoteForm::UNQUOTE_LABEL, SexpShape::UNQUOTE_LABEL);
        assert_eq!(
            QuoteForm::UNQUOTE_SPLICE_LABEL,
            SexpShape::UNQUOTE_SPLICE_LABEL,
        );
    }

    #[test]
    fn quote_form_label_arms_route_through_per_role_labels_for_every_variant() {
        // PATH-UNIFORMITY: `QuoteForm::V.label()` MUST equal the per-role
        // `pub const QuoteForm::V_LABEL` for every `v: QuoteForm`. Pre-
        // lift the four quote-family marker labels were reachable through
        // `QuoteForm::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
        // `QuoteForm::*_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`
        // and
        // `structural_kind_label_arms_route_through_per_role_labels_for_every_variant`
        // — those pin the peer 6-of-12 and 2-of-12 sub-carvings; this pin
        // binds the QuoteForm 4-of-12 subset algebra's per-role aliases
        // against `QuoteForm::label`'s composition-routed arms so the
        // four quote-family marker labels project through ONE aliased
        // typed source of truth per role rather than through per-consumer
        // inline literals.
        assert_eq!(QuoteForm::Quote.label(), QuoteForm::QUOTE_LABEL);
        assert_eq!(QuoteForm::Quasiquote.label(), QuoteForm::QUASIQUOTE_LABEL);
        assert_eq!(QuoteForm::Unquote.label(), QuoteForm::UNQUOTE_LABEL);
        assert_eq!(
            QuoteForm::UnquoteSplice.label(),
            QuoteForm::UNQUOTE_SPLICE_LABEL,
        );
    }

    #[test]
    fn quote_form_labels_has_expected_cardinality() {
        // Cardinality pin: `LABELS.len() == 4` matches `ALL.len()` so a
        // refactor that loosens the type to `&'static [&'static str]`
        // fails HERE (the `[_; 4]` 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 — four quote-
        // family markers, matching the four-arm carving of the parent
        // `SexpShape::LABELS` (the quote-family subset of the twelve
        // canonical outer-shape labels).
        assert_eq!(QuoteForm::LABELS.len(), 4);
        assert_eq!(QuoteForm::LABELS.len(), QuoteForm::ALL.len());
    }

    #[test]
    fn quote_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. The declaration-order
        // pin makes a family-wide consumer that walks the ALL / LABELS
        // pair in lockstep (an LSP completion bar keyed on
        // `QuoteForm::LABELS`, a Sekiban metric emitter labeling
        // `tatara_lisp_quote_family_label_total{label}` 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!(QuoteForm::LABELS.len(), QuoteForm::ALL.len());
        for (i, qf) in QuoteForm::ALL.iter().enumerate() {
            assert_eq!(
                QuoteForm::LABELS[i],
                qf.label(),
                "QuoteForm::LABELS[{i}] `{lbl}` drifted from \
                 QuoteForm::ALL[{i}].label() `{via_variant}` — the \
                 canonical ALL ordering and the LABELS ordering must \
                 match element-wise",
                lbl = QuoteForm::LABELS[i],
                via_variant = qf.label(),
            );
        }
    }

    #[test]
    fn quote_form_labels_pairwise_distinct() {
        // 4x4 pairwise sweep so a collision between any two labels
        // (which would silently degrade two distinct quote-family
        // markers to the SAME diagnostic bytes and violate the closed-
        // set FromStr round-trip through `SexpShape::from_str`) fails-
        // loudly at the exact pair. Distinctness is already enforced
        // structurally at the parent superset by
        // `sexp_shape_labels_pairwise_distinct` (the twelve-variant
        // sweep), but this pin is a secondary guard focused on the per-
        // role `pub const` surface of the QuoteForm 4-of-12 subset
        // directly rather than the runtime projection through
        // `SexpShape::label`.
        for (i, a) in QuoteForm::LABELS.iter().enumerate() {
            for (j, b) in QuoteForm::LABELS.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "QuoteForm::LABELS[{i}] ({a:?}) collides with \
                     QuoteForm::LABELS[{j}] ({b:?}) — two distinct \
                     quote-family markers cannot share diagnostic bytes",
                );
            }
        }
    }

    #[test]
    fn quote_form_labels_match_sexp_shape_labels_element_wise_via_alias_chain() {
        // CROSS-AXIS PIN: `QuoteForm::LABELS[i] ==
        // QuoteForm::ALL[i].sexp_shape().label()` for every index. Closes
        // the alias-chain identity at the family-wide array level:
        // LABELS is NOT a fresh literal table but the projection of ALL
        // through the composition, materialized once at declaration time
        // through the four per-role aliases. A regression that re-inlines
        // LABELS to fresh literals (or that re-inlines each per-role
        // constant off the aliased `SexpShape::*_LABEL` source of truth)
        // still passes the pairwise-distinct + cardinality + alignment
        // pins but drifts the alias chain — this pin catches that drift.
        //
        // Sibling-shape pin to
        // `atom_kind_labels_match_sexp_shape_labels_element_wise_via_alias_chain`
        // and
        // `structural_kind_labels_match_sexp_shape_labels_element_wise_via_alias_chain`
        // — those pin the peer 6-of-12 and 2-of-12 sub-carvings' alias
        // chains through their `SexpShape` parents; this pin closes the
        // fourth and final SexpShape sub-carving's alias-chain identity
        // at the same shape.
        assert_eq!(QuoteForm::LABELS.len(), QuoteForm::ALL.len());
        for (i, qf) in QuoteForm::ALL.iter().enumerate() {
            let via_composition = qf.sexp_shape().label();
            assert_eq!(
                QuoteForm::LABELS[i],
                via_composition,
                "QuoteForm::LABELS[{i}] `{lbl}` drifted from \
                 QuoteForm::ALL[{i}].sexp_shape().label() `{via}` — \
                 the alias-chain composition law `LABELS[i] == \
                 ALL[i].sexp_shape().label()` binds the family-wide \
                 array to the composition through sexp_shape + \
                 SexpShape::label; a drift here means the per-role \
                 aliases were re-inlined off their SexpShape source of \
                 truth",
                lbl = QuoteForm::LABELS[i],
                via = via_composition,
            );
        }
    }

    #[test]
    fn quote_form_sexp_shape_paired_with_as_quote_form_preserves_pre_lift_pairing_for_every_sexp() {
        // PATH-UNIFORMITY CONTRACT: the (Sexp variant, SexpShape variant)
        // pairing the pre-lift `sexp_shape` arms encoded inline is now
        // structurally derived via
        // `s.as_quote_form().map(|(qf, _)| qf.sexp_shape())` for every
        // quote-family `Sexp` shape. Pin the derivation against the
        // pre-lift pairing across all four quote-family wrapper variants
        // so a regression that drifts ONE side of the typed algebra
        // (e.g. a `QuoteForm::Quote → SexpShape::Quasiquote` typo, or a
        // `Sexp::as_quote_form` arm that swaps two markers) surfaces
        // immediately. Non-quote-family shapes project to `None` from
        // `as_quote_form`, which the assertion arm skips — the typed
        // closed-set partition is load-bearing for the early-return
        // shape of the lifted `domain::sexp_shape`.
        use crate::error::SexpShape;
        let cases: &[(&str, Sexp, SexpShape)] = &[
            (
                "quote",
                Sexp::Quote(Box::new(Sexp::symbol("x"))),
                SexpShape::Quote,
            ),
            (
                "quasiquote",
                Sexp::Quasiquote(Box::new(Sexp::symbol("x"))),
                SexpShape::Quasiquote,
            ),
            (
                "unquote",
                Sexp::Unquote(Box::new(Sexp::symbol("x"))),
                SexpShape::Unquote,
            ),
            (
                "unquote-splice",
                Sexp::UnquoteSplice(Box::new(Sexp::symbol("xs"))),
                SexpShape::UnquoteSplice,
            ),
        ];
        for (label, sexp, expected_shape) in cases {
            let (qf, _) = sexp
                .as_quote_form()
                .unwrap_or_else(|| panic!("{label} must project through as_quote_form"));
            assert_eq!(
                qf.sexp_shape(),
                *expected_shape,
                "{label} drifted from typed (QuoteForm, SexpShape) pairing"
            );
        }
    }

    #[test]
    fn as_unquote_derives_from_as_quote_form_composed_with_subset_gate() {
        // Path-uniformity: `Sexp::as_unquote` is now derived from
        // `as_quote_form().and_then(|(qf, inner)| qf.as_unquote_form()
        // .map(|uf| (uf, inner)))`. Pin that the derived semantic
        // agrees with the pre-lift arm-based one across the closed
        // Sexp variant set — every shape's projection through
        // `as_unquote` must equal the manual composition through
        // `as_quote_form` + `QuoteForm::as_unquote_form`. A regression
        // that drifts ONE projection's posture from the composition
        // becomes a typed test failure.
        let shapes: Vec<(&str, Sexp)> = vec![
            ("nil", Sexp::Nil),
            ("symbol", Sexp::symbol("x")),
            ("keyword", Sexp::keyword("k")),
            ("string", Sexp::string("s")),
            ("int", Sexp::int(7)),
            ("float", Sexp::float(2.5)),
            ("bool", Sexp::boolean(true)),
            ("empty list", Sexp::List(vec![])),
            ("non-empty list", Sexp::List(vec![Sexp::symbol("op")])),
            ("quote", Sexp::Quote(Box::new(Sexp::symbol("x")))),
            ("quasiquote", Sexp::Quasiquote(Box::new(Sexp::symbol("x")))),
            ("unquote", Sexp::Unquote(Box::new(Sexp::symbol("x")))),
            (
                "unquote-splice",
                Sexp::UnquoteSplice(Box::new(Sexp::symbol("xs"))),
            ),
        ];
        for (label, sexp) in &shapes {
            let via_direct = sexp.as_unquote();
            let via_composed = sexp
                .as_quote_form()
                .and_then(|(qf, inner)| qf.as_unquote_form().map(|uf| (uf, inner)));
            assert_eq!(
                via_direct, via_composed,
                "as_unquote drifted from composed as_quote_form+as_unquote_form at {label}"
            );
        }
    }

    #[test]
    fn hash_for_sexp_structural_arms_route_through_structural_kind_hash_discriminator() {
        // CACHE-KEY CONTRACT (Hash side, structural axis): pin that
        // the lifted `Hash for Sexp` impl produces byte-identical
        // hashes for the two structural-residual arms (`Sexp::Nil`,
        // `Sexp::List(_)`) as the pre-lift implementation, routing
        // through `StructuralKind::hash_discriminator` so the
        // (Sexp variant, cache-key byte) pairing is structurally
        // bound to the algebra rather than threaded through inline
        // `0u8` / `2u8` literals. We compute the expected hash via a
        // SECOND hasher that manually drives the pre-lift `<discr>
        // .hash(h); <rest>.hash(h)` sequence, then compare. A
        // regression that drifts the discriminator (e.g. renumbers
        // `StructuralKind::List` to `1u8` and collides with the
        // atomic-carve outer marker byte) OR re-orders the (discr,
        // rest) sequence surfaces here as a hash-value mismatch.
        // Sibling arm-sweep to
        // `hash_for_sexp_preserves_legacy_quote_family_discriminator_bytes`
        // on the quote-family axis (four wrapper variants) — the
        // three closed-set carvings' hash arms all route through
        // ONE typed method per carving, and this pin binds the
        // structural-residual arm's post-lift shape against the
        // pre-lift byte-stream.
        use crate::error::StructuralKind;
        use std::collections::hash_map::DefaultHasher;
        use std::hash::{Hash, Hasher};
        // (label, sexp, expected-first-discr-byte, extra-hash-sequence
        // closure that drives the residual hash body after the
        // discriminator byte)
        #[allow(clippy::type_complexity)]
        let cases: [(&str, Sexp, u8, Box<dyn Fn(&mut DefaultHasher)>); 2] = [
            ("nil", Sexp::Nil, 0u8, Box::new(|_h: &mut DefaultHasher| {})),
            (
                "list",
                Sexp::List(vec![Sexp::symbol("a"), Sexp::int(1)]),
                2u8,
                Box::new(|h: &mut DefaultHasher| {
                    let items = vec![Sexp::symbol("a"), Sexp::int(1)];
                    items.len().hash(h);
                    for i in &items {
                        i.hash(h);
                    }
                }),
            ),
        ];
        for (label, sexp, expected_discr, extra) in &cases {
            let mut via_impl = DefaultHasher::new();
            sexp.hash(&mut via_impl);

            let mut via_legacy = DefaultHasher::new();
            expected_discr.hash(&mut via_legacy);
            extra(&mut via_legacy);

            assert_eq!(
                via_impl.finish(),
                via_legacy.finish(),
                "Hash for Sexp drifted from legacy (discr={expected_discr}, rest) sequence at {label}",
            );
        }
        // Composition pin: pointer-independent structural equality —
        // the discriminator byte value MUST agree between the typed
        // projection and the pre-lift literal, so a regression that
        // re-inlines the two arm literals as a parallel match-table
        // (`Sexp::Nil => 0u8`, `Sexp::List(_) => 2u8`) still passes
        // the hash-value sweep above but drifts if the future
        // `StructuralKind::hash_discriminator` is re-numbered — this
        // pin binds the composition IDENTITY (not just the value
        // equality) between the outer `Hash for Sexp` body and the
        // typed algebra.
        assert_eq!(StructuralKind::Nil.hash_discriminator(), 0u8);
        assert_eq!(StructuralKind::List.hash_discriminator(), 2u8);
    }

    #[test]
    fn hash_for_sexp_preserves_legacy_quote_family_discriminator_bytes() {
        // CACHE-KEY CONTRACT (Hash side): pin that the lifted
        // `Hash for Sexp` impl produces byte-identical hashes for the
        // four quote-family variants as the pre-lift implementation.
        // We compute the expected hash via a SECOND hasher that
        // manually drives the pre-lift `<discr>.hash(h); inner.hash(h)`
        // sequence, then compare. A regression that drifts the
        // discriminator OR re-orders the (discr, inner) sequence
        // surfaces here as a hash-value mismatch.
        use std::collections::hash_map::DefaultHasher;
        let inner = Sexp::symbol("payload");
        for (label, sexp, expected_discr) in [
            ("quote", Sexp::Quote(Box::new(inner.clone())), 3u8),
            ("quasiquote", Sexp::Quasiquote(Box::new(inner.clone())), 4u8),
            ("unquote", Sexp::Unquote(Box::new(inner.clone())), 5u8),
            (
                "unquote-splice",
                Sexp::UnquoteSplice(Box::new(inner.clone())),
                6u8,
            ),
        ] {
            let mut via_impl = DefaultHasher::new();
            sexp.hash(&mut via_impl);

            let mut via_legacy = DefaultHasher::new();
            expected_discr.hash(&mut via_legacy);
            inner.hash(&mut via_legacy);

            assert_eq!(
                via_impl.finish(),
                via_legacy.finish(),
                "Hash for Sexp drifted from legacy (discr={expected_discr}, inner) sequence at {label}"
            );
        }
    }

    #[test]
    fn sexp_hash_discriminator_pins_legacy_outer_cache_key_bytes() {
        // CACHE-KEY CONTRACT: pre-lift `Hash for Sexp` used the literal
        // byte values 0/1/2 for Nil/Atom/List AND delegated 3/4/5/6 for
        // Quote/Quasiquote/Unquote/UnquoteSplice through
        // `QuoteForm::hash_discriminator`. The macro-expansion cache
        // (`Expander::cache`) keys on Hash; ANY change to a discriminator
        // byte silently invalidates every cached expansion across the
        // substrate. Pin the seven legacy values explicitly so a
        // regression that re-numbers them surfaces immediately — the
        // outer-`Sexp` algebra MUST preserve the prior byte mapping bit-
        // for-bit. Sibling posture to
        // `atom_kind_hash_discriminator_pins_legacy_atom_cache_key_bytes`
        // and `quote_form_hash_discriminator_pins_legacy_cache_key_bytes`
        // on the two sub-carvings.
        assert_eq!(Sexp::Nil.hash_discriminator(), 0);
        assert_eq!(Sexp::symbol("x").hash_discriminator(), 1);
        assert_eq!(Sexp::keyword("k").hash_discriminator(), 1);
        assert_eq!(Sexp::string("s").hash_discriminator(), 1);
        assert_eq!(Sexp::int(7).hash_discriminator(), 1);
        assert_eq!(Sexp::float(2.5).hash_discriminator(), 1);
        assert_eq!(Sexp::boolean(true).hash_discriminator(), 1);
        assert_eq!(Sexp::List(vec![]).hash_discriminator(), 2);
        assert_eq!(Sexp::Quote(Box::new(Sexp::Nil)).hash_discriminator(), 3);
        assert_eq!(
            Sexp::Quasiquote(Box::new(Sexp::Nil)).hash_discriminator(),
            4
        );
        assert_eq!(Sexp::Unquote(Box::new(Sexp::Nil)).hash_discriminator(), 5);
        assert_eq!(
            Sexp::UnquoteSplice(Box::new(Sexp::Nil)).hash_discriminator(),
            6
        );
    }

    #[test]
    fn sexp_hash_discriminator_bytes_partition_zero_through_six_injectively() {
        // Closed-set injectivity across the seven outer-`Sexp` variants:
        // the seven discriminator bytes MUST partition `{0, 1, 2, 3, 4,
        // 5, 6}` injectively so two distinct outer variants never
        // conflate their outer cache-key byte — a violation here means
        // the cache could conflate e.g. `Sexp::List(vec![])` and
        // `Sexp::Quote(Box::new(Sexp::Nil))` at the outer discriminator
        // slot. Uses ONE seed per outer-variant sweep. Sibling pin to
        // `atom_kind_hash_discriminator_bytes_are_pairwise_disjoint` (six-
        // arm partition of `{0..=5}` nested inside the Atom outer byte
        // `1`) and `quote_form_hash_discriminator_bytes_are_pairwise_
        // disjoint` (four-arm partition of `{3..=6}` surfaced through
        // this outer method's quote-family arms). Together the three
        // partitions jointly cover the outer-Sexp discriminator space
        // `{0..=6}` — the joint partition contract is pinned by
        // `sexp_hash_discriminator_partitions_the_full_outer_discriminator_space_zero_through_six`
        // below.
        let bytes: Vec<u8> = [
            Sexp::Nil,
            Sexp::symbol("x"),
            Sexp::List(vec![]),
            Sexp::Quote(Box::new(Sexp::Nil)),
            Sexp::Quasiquote(Box::new(Sexp::Nil)),
            Sexp::Unquote(Box::new(Sexp::Nil)),
            Sexp::UnquoteSplice(Box::new(Sexp::Nil)),
        ]
        .iter()
        .map(Sexp::hash_discriminator)
        .collect();
        let mut sorted = bytes.clone();
        sorted.sort_unstable();
        let mut deduped = sorted.clone();
        deduped.dedup();
        assert_eq!(
            sorted, deduped,
            "Sexp hash discriminator bytes must be pairwise disjoint across the seven outer variants"
        );
        assert_eq!(sorted, vec![0, 1, 2, 3, 4, 5, 6]);
    }

    #[test]
    fn sexp_hash_discriminator_partitions_the_full_outer_discriminator_space_zero_through_six() {
        // JOINT PARTITION CONTRACT: the outer-`Sexp` discriminator byte
        // space `{0..=6}` is jointly covered by the three carvings' typed
        // discriminator methods — pinning the joint contract makes the
        // prefix-uniqueness invariant a compile-time-verified theorem
        // rather than a per-carving isolated pin.
        //
        // Sexp-outer: `{0, 1, 2, 3, 4, 5, 6}` via `Sexp::hash_discriminator`
        //   (the outer arm-partition method; the entire outer space).
        // AtomKind: `{0, 1, 2, 3, 4, 5}` via `AtomKind::hash_discriminator`
        //   (nested inside the Atom outer byte `1`; NOT part of the outer
        //   partition, but pinned here to document the sub-carving space).
        // QuoteForm: `{3, 4, 5, 6}` via `QuoteForm::hash_discriminator`
        //   (surfaced through the four quote-family arms of the outer
        //   method; MUST equal the outer sweep's `{3..=6}` slice).
        //
        // A regression that drifts the outer method's quote-family arms
        // from the delegated `QuoteForm::hash_discriminator` bytes (e.g.
        // routes `Sexp::Quote(_)` to `7u8` inline) fails-loudly here.
        // Sibling posture to
        // `structural_kind_hash_discriminator_disjoint_from_atom_outer_carve_byte_and_quote_form_hash_discriminator_partition`
        // on the sub-carving axis — this pin binds the OUTER joint
        // partition; that pin would bind a hypothetical structural sub-
        // carving's disjointness.
        let outer_seeds: Vec<Sexp> = vec![
            Sexp::Nil,
            Sexp::symbol("x"),
            Sexp::List(vec![]),
            Sexp::Quote(Box::new(Sexp::Nil)),
            Sexp::Quasiquote(Box::new(Sexp::Nil)),
            Sexp::Unquote(Box::new(Sexp::Nil)),
            Sexp::UnquoteSplice(Box::new(Sexp::Nil)),
        ];
        let outer_bytes: std::collections::BTreeSet<u8> =
            outer_seeds.iter().map(Sexp::hash_discriminator).collect();
        let expected: std::collections::BTreeSet<u8> = (0u8..=6u8).collect();
        assert_eq!(
            outer_bytes, expected,
            "Sexp::hash_discriminator must cover exactly the outer discriminator space {{0..=6}}"
        );

        let quote_bytes: std::collections::BTreeSet<u8> = QuoteForm::ALL
            .iter()
            .map(|qf| qf.hash_discriminator())
            .collect();
        let quote_slice: std::collections::BTreeSet<u8> = (3u8..=6u8).collect();
        assert_eq!(
            quote_bytes, quote_slice,
            "QuoteForm::hash_discriminator must cover {{3..=6}} — the quote-family slice of the outer Sexp partition"
        );
        assert!(
            quote_bytes.is_subset(&outer_bytes),
            "QuoteForm::hash_discriminator bytes must be a subset of Sexp::hash_discriminator's outer partition"
        );
    }

    #[test]
    fn sexp_hash_discriminator_atom_arm_collapses_over_every_atom_kind() {
        // OUTER-CARVING CONTRACT (atomic arm): every `AtomKind` variant
        // projects through `Sexp::Atom` 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
        // (`AtomKind::hash_discriminator`'s `{0..=5}`) nested INSIDE
        // `Atom::hash` — NOT surfaced through this method. Pin the six-
        // way collapse so a regression that drifts ONE atom kind's outer
        // routing (e.g. routes `Sexp::Atom(Atom::Int(_))` to `7u8`
        // inline) surfaces here immediately. Sibling posture to
        // `sexp_hash_discriminator_quote_arm_delegates_to_quote_form_
        // hash_discriminator` on the quote-family arm — that arm
        // DELEGATES to `QuoteForm::hash_discriminator` for `{3..=6}`;
        // this arm COLLAPSES to a single outer byte `1`.
        for (kind, sexp) in [
            (AtomKind::Symbol, Sexp::symbol("s")),
            (AtomKind::Keyword, Sexp::keyword("k")),
            (AtomKind::Str, Sexp::string("t")),
            (AtomKind::Int, Sexp::int(7)),
            (AtomKind::Float, Sexp::float(2.5)),
            (AtomKind::Bool, Sexp::boolean(true)),
        ] {
            assert_eq!(
                sexp.hash_discriminator(),
                1,
                "Sexp::Atom({kind:?}) must collapse to outer byte 1"
            );
        }
    }

    #[test]
    fn sexp_hash_discriminator_quote_arm_delegates_to_quote_form_hash_discriminator() {
        // OUTER-CARVING CONTRACT (quote-family arm): every `QuoteForm`
        // variant projects through `QuoteForm::wrap` to a `Sexp::Quote_*`
        // whose `hash_discriminator` equals `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
        // `Sexp::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.
        for qf in QuoteForm::ALL {
            let sexp = qf.wrap(Sexp::Nil);
            assert_eq!(
                sexp.hash_discriminator(),
                qf.hash_discriminator(),
                "Sexp {qf:?}-arm must delegate to QuoteForm::hash_discriminator"
            );
        }
    }

    #[test]
    fn hash_for_sexp_routes_outer_discriminator_through_sexp_hash_discriminator() {
        // ROUTING-LAW CONTRACT: pin the outer-`Sexp` routing IDENTITY —
        // for every reachable outer-variant shape, `Hash for Sexp`
        // produces byte-identical output to a hand-driven
        // `<sexp.hash_discriminator()>.hash(h); <inner-payload-hash>`
        // sequence. Binds the composition IDENTITY (not just value
        // equality) between the outer Hash body and the typed algebra
        // method — a regression that re-inlines the three literals
        // (`0u8` / `1u8` / `2u8`) at the outer arms still drifts
        // detectably if the future `Sexp::hash_discriminator` is
        // re-numbered. Sibling posture to
        // `hash_for_sexp_preserves_legacy_quote_family_discriminator_bytes`
        // — that pin binds the quote-family arms against the pre-lift
        // literal bytes; this pin binds ALL SEVEN outer arms against the
        // post-lift typed method.
        use std::collections::hash_map::DefaultHasher;
        let payload = Sexp::symbol("payload");
        let seeds: Vec<(&str, Sexp)> = vec![
            ("nil", Sexp::Nil),
            ("atom-symbol", Sexp::symbol("s")),
            ("atom-int", Sexp::int(7)),
            ("atom-float", Sexp::float(2.5)),
            ("atom-bool", Sexp::boolean(true)),
            ("empty list", Sexp::List(vec![])),
            (
                "non-empty list",
                Sexp::List(vec![Sexp::symbol("op"), Sexp::int(1)]),
            ),
            ("quote", Sexp::Quote(Box::new(payload.clone()))),
            ("quasiquote", Sexp::Quasiquote(Box::new(payload.clone()))),
            ("unquote", Sexp::Unquote(Box::new(payload.clone()))),
            (
                "unquote-splice",
                Sexp::UnquoteSplice(Box::new(payload.clone())),
            ),
        ];
        for (label, sexp) in seeds {
            let mut via_impl = DefaultHasher::new();
            sexp.hash(&mut via_impl);

            let mut via_lifted = DefaultHasher::new();
            sexp.hash_discriminator().hash(&mut via_lifted);
            match &sexp {
                Sexp::Nil => {}
                Sexp::Atom(a) => a.hash(&mut via_lifted),
                Sexp::List(items) => {
                    items.len().hash(&mut via_lifted);
                    for i in items {
                        i.hash(&mut via_lifted);
                    }
                }
                Sexp::Quote(_)
                | Sexp::Quasiquote(_)
                | Sexp::Unquote(_)
                | Sexp::UnquoteSplice(_) => {
                    let (_, inner) = sexp.expect_quote_form();
                    inner.hash(&mut via_lifted);
                }
            }

            assert_eq!(
                via_impl.finish(),
                via_lifted.finish(),
                "Hash for Sexp drifted from routed-through-hash_discriminator sequence at {label}"
            );
        }
    }

    #[test]
    fn sexp_hash_discriminator_routes_through_shape_hash_discriminator_via_composition() {
        // COMPOSITION-IDENTITY CONTRACT (five-layer post-lift): pin the
        // outer-`Sexp` cache-key routing IDENTITY through the new shape-
        // level algebra layer — for every reachable outer-variant shape,
        // `Sexp::hash_discriminator` MUST agree byte-for-byte with
        // `self.shape().hash_discriminator()`. Post-lift the outer
        // method's body is EXACTLY `self.shape().hash_discriminator()`,
        // and this pin binds the routing identity across every reachable
        // shape so a regression that re-inlines the seven arm literals
        // (e.g. reverts to an inline match returning `0u8`/`1u8`/`2u8`
        // and the four quote-family sub-carving delegations) still
        // drifts detectably if the future `SexpShape::hash_discriminator`
        // is re-numbered — the composition identity is what closes the
        // outer-`Sexp` cache-key algebra at five typed layers (outer →
        // shape → three sub-carvings). Sibling posture to
        // `hash_for_sexp_routes_outer_discriminator_through_sexp_hash_discriminator`
        // — that pin binds the `Hash for Sexp` body against the outer
        // method; this pin binds the outer method against the shape-
        // level method.
        let payload = Sexp::symbol("payload");
        let seeds: Vec<(&str, Sexp)> = vec![
            ("nil", Sexp::Nil),
            ("atom-symbol", Sexp::symbol("s")),
            ("atom-keyword", Sexp::keyword("k")),
            ("atom-string", Sexp::string("t")),
            ("atom-int", Sexp::int(7)),
            ("atom-float", Sexp::float(2.5)),
            ("atom-bool", Sexp::boolean(true)),
            ("empty list", Sexp::List(vec![])),
            (
                "non-empty list",
                Sexp::List(vec![Sexp::symbol("op"), Sexp::int(1)]),
            ),
            ("quote", Sexp::Quote(Box::new(payload.clone()))),
            ("quasiquote", Sexp::Quasiquote(Box::new(payload.clone()))),
            ("unquote", Sexp::Unquote(Box::new(payload.clone()))),
            (
                "unquote-splice",
                Sexp::UnquoteSplice(Box::new(payload.clone())),
            ),
        ];
        for (label, sexp) in seeds {
            let outer = sexp.hash_discriminator();
            let via_shape = sexp.shape().hash_discriminator();
            assert_eq!(
                outer, via_shape,
                "Sexp::hash_discriminator at {label} drifted from self.shape().hash_discriminator() — the five-layer typed cache-key composition is broken",
            );
        }
    }

    #[test]
    fn sexp_iac_forge_tag_routes_through_shape_iac_forge_tag_via_composition() {
        // COMPOSITION-IDENTITY CONTRACT (outer-value peer): pin the
        // outer-`Sexp` cross-crate canonical-form tag routing IDENTITY
        // through the pre-existing shape-level projection — for every
        // reachable outer-variant shape, `Sexp::iac_forge_tag` MUST agree
        // arm-for-arm with `self.shape().iac_forge_tag()`. Post-lift the
        // outer method's body is EXACTLY `self.shape().iac_forge_tag()`,
        // and this pin binds the routing identity across every reachable
        // shape so a regression that re-inlines a parallel four-arm
        // match on the outer `Self::Quote | Self::Quasiquote | ...` set
        // returning literal tag strings inline still drifts detectably
        // if the shape-level projection's tag composition is re-numbered
        // — the composition identity is what closes the outer-`Sexp`
        // cross-crate canonical-form tag surface at four typed layers
        // (outer → shape → carving → sub-carving-tag). Sibling posture
        // to `sexp_hash_discriminator_routes_through_shape_hash_discriminator_via_composition`
        // — that pin binds the outer method against the shape-level
        // method on the cache-key byte axis; this pin binds the outer
        // method against the shape-level method on the cross-crate
        // canonical-form tag axis.
        let payload = Sexp::symbol("payload");
        let seeds: Vec<(&str, Sexp)> = vec![
            ("nil", Sexp::Nil),
            ("atom-symbol", Sexp::symbol("s")),
            ("atom-keyword", Sexp::keyword("k")),
            ("atom-string", Sexp::string("t")),
            ("atom-int", Sexp::int(7)),
            ("atom-float", Sexp::float(2.5)),
            ("atom-bool", Sexp::boolean(true)),
            ("empty list", Sexp::List(vec![])),
            (
                "non-empty list",
                Sexp::List(vec![Sexp::symbol("op"), Sexp::int(1)]),
            ),
            ("quote", Sexp::Quote(Box::new(payload.clone()))),
            ("quasiquote", Sexp::Quasiquote(Box::new(payload.clone()))),
            ("unquote", Sexp::Unquote(Box::new(payload.clone()))),
            (
                "unquote-splice",
                Sexp::UnquoteSplice(Box::new(payload.clone())),
            ),
        ];
        for (label, sexp) in seeds {
            let outer = sexp.iac_forge_tag();
            let via_shape = sexp.shape().iac_forge_tag();
            assert_eq!(
                outer, via_shape,
                "Sexp::iac_forge_tag at {label} drifted from self.shape().iac_forge_tag() — the four-layer typed cross-crate canonical-form tag composition is broken",
            );
        }
    }

    #[test]
    fn sexp_iac_forge_tag_pins_canonical_cl_tags_for_every_quote_family_arm() {
        // CANONICAL-TAG CONTRACT (outer-value peer): the outer-value
        // `Sexp::iac_forge_tag` MUST project each of the four homoiconic
        // prefix-wrapper arms to the SAME canonical Common-Lisp tag
        // string `crate::error::SexpShape::iac_forge_tag` projects at the
        // shape-level (and `crate::ast::QuoteForm::iac_forge_tag` at the
        // sub-carving level) — `Sexp::Quote → Some("quote")`,
        // `Sexp::Quasiquote → Some("quasiquote")`, `Sexp::Unquote →
        // Some("unquote")`, `Sexp::UnquoteSplice → Some("unquote-
        // splicing")`. A regression that inlines a byte-drifted spelling
        // here (e.g. `Sexp::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
        // `sexp_shape_iac_forge_tag_pins_canonical_cl_tags_for_every_quote_family_arm`
        // one algebra level down — that pin binds the shape-level
        // projection's canonical tag surface; this pin binds the outer-
        // value projection's canonical tag surface across the closed
        // four-arm quote-family sweep on the outer `Sexp` algebra.
        let inner = Sexp::symbol("payload");
        assert_eq!(
            Sexp::Quote(Box::new(inner.clone())).iac_forge_tag(),
            Some("quote"),
        );
        assert_eq!(
            Sexp::Quasiquote(Box::new(inner.clone())).iac_forge_tag(),
            Some("quasiquote"),
        );
        assert_eq!(
            Sexp::Unquote(Box::new(inner.clone())).iac_forge_tag(),
            Some("unquote"),
        );
        assert_eq!(
            Sexp::UnquoteSplice(Box::new(inner)).iac_forge_tag(),
            Some("unquote-splicing"),
        );
    }

    #[test]
    fn sexp_iac_forge_tag_returns_none_on_every_non_quote_family_variant() {
        // PARTIAL-PROJECTION KERNEL CONTRACT (outer-value peer): every
        // `Sexp` variant OUTSIDE the four-arm quote-family carving MUST
        // project through `Sexp::iac_forge_tag` to `None` — the three-
        // arm outer kernel `{Nil, Atom, List}` (which corresponds to the
        // eight-shape kernel at the shape-level projection through the
        // six-atomic-arms → outer `Atom` collapse of `Self::shape`). Pin
        // representative seeds for each kernel arm — `Nil`, one atom per
        // `AtomKind`, one empty + one non-empty list — so a regression
        // that surfaces a bogus tag for a non-quote-family arm (e.g.
        // `Sexp::List → Some("list")` conflating the outer-shape
        // diagnostic label with the quote-family canonical form) fails-
        // loudly here. Sibling posture to
        // `sexp_shape_iac_forge_tag_returns_none_on_every_non_quote_family_shape`
        // one algebra level down — that pin binds the shape-level
        // projection's kernel; this pin binds the outer-value
        // projection's kernel on the three-arm outer partition.
        assert_eq!(Sexp::Nil.iac_forge_tag(), None);
        assert_eq!(Sexp::symbol("s").iac_forge_tag(), None);
        assert_eq!(Sexp::keyword("k").iac_forge_tag(), None);
        assert_eq!(Sexp::string("t").iac_forge_tag(), None);
        assert_eq!(Sexp::int(7).iac_forge_tag(), None);
        assert_eq!(Sexp::float(2.5).iac_forge_tag(), None);
        assert_eq!(Sexp::boolean(true).iac_forge_tag(), None);
        assert_eq!(Sexp::List(vec![]).iac_forge_tag(), None);
        assert_eq!(
            Sexp::List(vec![Sexp::symbol("op"), Sexp::int(1)]).iac_forge_tag(),
            None,
        );
    }

    #[test]
    fn sexp_iac_forge_tag_partitions_quote_family_and_kernel_disjointly() {
        // IMAGE-PARTITION CONTRACT (outer-value peer): sweeping a
        // representative seed per outer `Sexp` variant through
        // `Sexp::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 outer three-arm non-quote-
        // family kernel (all `None` — `Nil` + one atom per `AtomKind` +
        // one list). The image's `is_some()` count MUST be four
        // (surjective onto the four-tag closed set), the kernel's
        // `is_none()` count MUST cover every non-quote-family seed, and
        // the total sweep sums to the thirteen-seed representative sweep
        // covering all seven outer variants (six `Atom` payloads +
        // `Nil` + one `List` + four quote-family arms). 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
        // `sexp_shape_iac_forge_tag_partitions_quote_family_and_kernel_disjointly`
        // one algebra level down — that pin binds the shape-level
        // image-partition on the twelve-shape closed sweep; this pin
        // binds the outer-value image-partition on the representative
        // outer-variant sweep.
        let payload = Sexp::symbol("payload");
        let seeds: Vec<Sexp> = vec![
            Sexp::Nil,
            Sexp::symbol("s"),
            Sexp::keyword("k"),
            Sexp::string("t"),
            Sexp::int(7),
            Sexp::float(2.5),
            Sexp::boolean(true),
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("op"), Sexp::int(1)]),
            Sexp::Quote(Box::new(payload.clone())),
            Sexp::Quasiquote(Box::new(payload.clone())),
            Sexp::Unquote(Box::new(payload.clone())),
            Sexp::UnquoteSplice(Box::new(payload.clone())),
        ];
        let tag_image: std::collections::BTreeSet<&'static str> =
            seeds.iter().filter_map(Sexp::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,
            "Sexp::iac_forge_tag image must exactly cover the four canonical CL quote-family tags",
        );
        let some_count = seeds
            .iter()
            .filter(|sexp| sexp.iac_forge_tag().is_some())
            .count();
        assert_eq!(
            some_count, 4,
            "Sexp::iac_forge_tag must return `Some(_)` on exactly the four-arm quote-family carving",
        );
        let none_count = seeds
            .iter()
            .filter(|sexp| sexp.iac_forge_tag().is_none())
            .count();
        assert_eq!(
            none_count,
            seeds.len() - 4,
            "Sexp::iac_forge_tag must return `None` on every seed outside the four-arm quote-family carving",
        );
        assert_eq!(
            some_count + none_count,
            seeds.len(),
            "Sexp::iac_forge_tag's image + kernel must partition the representative outer-variant sweep exactly",
        );
    }

    #[test]
    fn sexp_prefix_routes_through_shape_prefix_via_composition() {
        // COMPOSITION-IDENTITY CONTRACT (outer-value peer): pin the
        // outer-`Sexp` reader-punctuation surface routing IDENTITY
        // through the pre-existing shape-level projection — for every
        // reachable outer-variant shape, `Sexp::prefix` MUST agree arm-
        // for-arm with `self.shape().prefix()`. Post-lift the outer
        // method's body is EXACTLY `self.shape().prefix()`, and this
        // pin binds the routing identity across every reachable shape so
        // a regression that re-inlines a parallel four-arm match on the
        // outer `Self::Quote | Self::Quasiquote | ...` set returning
        // literal reader-punctuation strings inline still drifts
        // detectably if the shape-level projection's prefix composition
        // is re-numbered — the composition identity is what closes the
        // outer-`Sexp` reader-punctuation surface at four typed layers
        // (outer → shape → carving → sub-carving-prefix). Sibling
        // posture to
        // `sexp_iac_forge_tag_routes_through_shape_iac_forge_tag_via_composition`
        // one vocabulary axis over — that pin binds the outer method
        // against the shape-level method on the cross-crate canonical-
        // form tag axis; this pin binds the outer method against the
        // shape-level method on the reader-punctuation axis.
        let payload = Sexp::symbol("payload");
        let seeds: Vec<(&str, Sexp)> = vec![
            ("nil", Sexp::Nil),
            ("atom-symbol", Sexp::symbol("s")),
            ("atom-keyword", Sexp::keyword("k")),
            ("atom-string", Sexp::string("t")),
            ("atom-int", Sexp::int(7)),
            ("atom-float", Sexp::float(2.5)),
            ("atom-bool", Sexp::boolean(true)),
            ("empty list", Sexp::List(vec![])),
            (
                "non-empty list",
                Sexp::List(vec![Sexp::symbol("op"), Sexp::int(1)]),
            ),
            ("quote", Sexp::Quote(Box::new(payload.clone()))),
            ("quasiquote", Sexp::Quasiquote(Box::new(payload.clone()))),
            ("unquote", Sexp::Unquote(Box::new(payload.clone()))),
            (
                "unquote-splice",
                Sexp::UnquoteSplice(Box::new(payload.clone())),
            ),
        ];
        for (label, sexp) in seeds {
            let outer = sexp.prefix();
            let via_shape = sexp.shape().prefix();
            assert_eq!(
                outer, via_shape,
                "Sexp::prefix at {label} drifted from self.shape().prefix() — the four-layer typed reader-punctuation composition is broken",
            );
        }
    }

    #[test]
    fn sexp_prefix_pins_canonical_reader_prefixes_for_every_quote_family_arm() {
        // CANONICAL-PREFIX CONTRACT (outer-value peer): the outer-value
        // `Sexp::prefix` MUST project each of the four homoiconic
        // prefix-wrapper arms to the SAME canonical reader-punctuation
        // string `crate::error::SexpShape::prefix` projects at the
        // shape-level (and `crate::ast::QuoteForm::prefix` at the sub-
        // carving level) — `Sexp::Quote → Some("'")`,
        // `Sexp::Quasiquote → Some("`")`, `Sexp::Unquote → Some(",")`,
        // `Sexp::UnquoteSplice → Some(",@")`. A regression that inlines
        // a byte-drifted spelling here (e.g. `Sexp::UnquoteSplice →
        // Some(", @")` inserting a spurious space, or `Sexp::Quote →
        // Some("`")` swapping arms between Quote and Quasiquote)
        // silently breaks the `Display for Sexp` round-trip against the
        // reader's prefix dispatch. Sibling posture to
        // `sexp_shape_prefix_pins_canonical_reader_prefixes_for_every_quote_family_arm`
        // one algebra level down — that pin binds the shape-level
        // projection's canonical reader-punctuation surface; this pin
        // binds the outer-value projection's canonical reader-
        // punctuation surface across the closed four-arm quote-family
        // sweep on the outer `Sexp` algebra.
        let inner = Sexp::symbol("payload");
        assert_eq!(Sexp::Quote(Box::new(inner.clone())).prefix(), Some("'"),);
        assert_eq!(
            Sexp::Quasiquote(Box::new(inner.clone())).prefix(),
            Some("`"),
        );
        assert_eq!(Sexp::Unquote(Box::new(inner.clone())).prefix(), Some(","),);
        assert_eq!(Sexp::UnquoteSplice(Box::new(inner)).prefix(), Some(",@"),);
    }

    #[test]
    fn sexp_prefix_returns_none_on_every_non_quote_family_variant() {
        // PARTIAL-PROJECTION KERNEL CONTRACT (outer-value peer): every
        // `Sexp` variant OUTSIDE the four-arm quote-family carving MUST
        // project through `Sexp::prefix` to `None` — the three-arm
        // outer kernel `{Nil, Atom, List}` (which corresponds to the
        // eight-shape kernel at the shape-level projection through the
        // six-atomic-arms → outer `Atom` collapse of `Self::shape`).
        // Pin representative seeds for each kernel arm — `Nil`, one
        // atom per `AtomKind`, one empty + one non-empty list — so a
        // regression that surfaces a bogus prefix for a non-quote-
        // family arm (e.g. `Sexp::List → Some("(")` conflating the
        // outer-shape structural delimiter with the quote-family
        // reader-punctuation) fails-loudly here. Sibling posture to
        // `sexp_shape_prefix_returns_none_on_every_non_quote_family_shape`
        // one algebra level down — that pin binds the shape-level
        // projection's kernel; this pin binds the outer-value
        // projection's kernel on the three-arm outer partition.
        assert_eq!(Sexp::Nil.prefix(), None);
        assert_eq!(Sexp::symbol("s").prefix(), None);
        assert_eq!(Sexp::keyword("k").prefix(), None);
        assert_eq!(Sexp::string("t").prefix(), None);
        assert_eq!(Sexp::int(7).prefix(), None);
        assert_eq!(Sexp::float(2.5).prefix(), None);
        assert_eq!(Sexp::boolean(true).prefix(), None);
        assert_eq!(Sexp::List(vec![]).prefix(), None);
        assert_eq!(
            Sexp::List(vec![Sexp::symbol("op"), Sexp::int(1)]).prefix(),
            None,
        );
    }

    #[test]
    fn sexp_prefix_partitions_quote_family_and_kernel_disjointly() {
        // IMAGE-PARTITION CONTRACT (outer-value peer): sweeping a
        // representative seed per outer `Sexp` variant through
        // `Sexp::prefix` MUST partition into EXACTLY the four-arm
        // quote-family image (four distinct canonical reader-punctuation
        // strings — the pre-image of `Some(_)`) AND the outer three-arm
        // non-quote-family kernel (all `None` — `Nil` + one atom per
        // `AtomKind` + one list). The image's `is_some()` count MUST be
        // four (surjective onto the four-prefix closed set), the
        // kernel's `is_none()` count MUST cover every non-quote-family
        // seed, and the total sweep sums to the thirteen-seed
        // representative sweep covering all seven outer variants (six
        // `Atom` payloads + `Nil` + one `List` + four quote-family
        // arms). 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-round-trip or Display consumer would
        // surface the drift. Sibling posture to
        // `sexp_shape_prefix_partitions_quote_family_and_kernel_disjointly`
        // one algebra level down — that pin binds the shape-level
        // image-partition on the twelve-shape closed sweep; this pin
        // binds the outer-value image-partition on the representative
        // outer-variant sweep.
        let payload = Sexp::symbol("payload");
        let seeds: Vec<Sexp> = vec![
            Sexp::Nil,
            Sexp::symbol("s"),
            Sexp::keyword("k"),
            Sexp::string("t"),
            Sexp::int(7),
            Sexp::float(2.5),
            Sexp::boolean(true),
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("op"), Sexp::int(1)]),
            Sexp::Quote(Box::new(payload.clone())),
            Sexp::Quasiquote(Box::new(payload.clone())),
            Sexp::Unquote(Box::new(payload.clone())),
            Sexp::UnquoteSplice(Box::new(payload.clone())),
        ];
        let prefix_image: std::collections::BTreeSet<&'static str> =
            seeds.iter().filter_map(Sexp::prefix).collect();
        let expected_prefix_image: std::collections::BTreeSet<&'static str> =
            ["'", "`", ",", ",@"].into_iter().collect();
        assert_eq!(
            prefix_image, expected_prefix_image,
            "Sexp::prefix image must exactly cover the four canonical reader-punctuation quote-family prefixes",
        );
        let some_count = seeds.iter().filter(|sexp| sexp.prefix().is_some()).count();
        assert_eq!(
            some_count, 4,
            "Sexp::prefix must return `Some(_)` on exactly the four-arm quote-family carving",
        );
        let none_count = seeds.iter().filter(|sexp| sexp.prefix().is_none()).count();
        assert_eq!(
            none_count,
            seeds.len() - 4,
            "Sexp::prefix must return `None` on every seed outside the four-arm quote-family carving",
        );
        assert_eq!(
            some_count + none_count,
            seeds.len(),
            "Sexp::prefix's image + kernel must partition the representative outer-variant sweep exactly",
        );
    }

    #[test]
    fn display_for_sexp_renders_each_quote_family_variant_with_canonical_prefix() {
        // Pin the post-lift Display rendering: every wrapper variant
        // renders as `<prefix><inner>` with the prefix sourced from
        // `QuoteForm::prefix`. A regression that drifts the prefix
        // arm-routing (e.g. routes Quote through `` ` `` instead of
        // `'`) fails loudly here. The literal `inner` rendering is
        // the symbol `foo` so the prefix is the only diff between
        // arms — pin path-uniformity across the closed set.
        let inner = Sexp::symbol("foo");
        assert_eq!(Sexp::Quote(Box::new(inner.clone())).to_string(), "'foo");
        assert_eq!(
            Sexp::Quasiquote(Box::new(inner.clone())).to_string(),
            "`foo"
        );
        assert_eq!(Sexp::Unquote(Box::new(inner.clone())).to_string(), ",foo");
        assert_eq!(Sexp::UnquoteSplice(Box::new(inner)).to_string(), ",@foo");
    }

    #[test]
    fn display_for_sexp_round_trips_each_quote_family_variant_through_reader() {
        // ROUND-TRIP CONTRACT: every wrapper variant's Display →
        // reader path produces the matching `Sexp::*` variant. The
        // reader's prefix-dispatch (in `reader::parse`) consumes the
        // canonical `'` / `` ` `` / `,` / `,@` tokens and produces
        // the corresponding wrapper; the Display impl emits the same
        // tokens via `QuoteForm::prefix`. Pin the round-trip
        // end-to-end so a regression that drifts the prefix on
        // either side (Display or reader) fails loudly here. Sibling
        // posture to `fmt_float_round_trips_integral_float_through
        // _reader_as_float` — the Float round-trip pin at the
        // Display→read boundary; this test pins the four
        // quote-family round-trips at the same boundary.
        let inner_body = Sexp::symbol("payload");

        let quote = Sexp::Quote(Box::new(inner_body.clone()));
        let forms = crate::reader::read(&quote.to_string()).expect("quote must round-trip");
        assert_eq!(forms.len(), 1);
        assert_eq!(forms[0], quote);

        let quasiquote = Sexp::Quasiquote(Box::new(inner_body.clone()));
        let forms =
            crate::reader::read(&quasiquote.to_string()).expect("quasiquote must round-trip");
        assert_eq!(forms.len(), 1);
        assert_eq!(forms[0], quasiquote);

        let unquote = Sexp::Unquote(Box::new(inner_body.clone()));
        let forms = crate::reader::read(&unquote.to_string()).expect("unquote must round-trip");
        assert_eq!(forms.len(), 1);
        assert_eq!(forms[0], unquote);

        let splice = Sexp::UnquoteSplice(Box::new(inner_body));
        let forms =
            crate::reader::read(&splice.to_string()).expect("unquote-splice must round-trip");
        assert_eq!(forms.len(), 1);
        assert_eq!(forms[0], splice);
    }

    #[test]
    fn quote_form_wrap_projects_each_typed_marker_into_matching_sexp_wrapper() {
        // CLOSED-SET CONSTRUCTOR CONTRACT: pin that `QuoteForm::wrap` is
        // the structural inverse of `Sexp::as_quote_form` at the
        // marker→wrapper boundary. Every variant of the closed-set
        // `QuoteForm` algebra projects to its matching `Sexp::*` wrapper
        // applied to the supplied inner — `Quote → Sexp::Quote`,
        // `Quasiquote → Sexp::Quasiquote`, `Unquote → Sexp::Unquote`,
        // `UnquoteSplice → Sexp::UnquoteSplice`. A regression that swaps
        // two arms (e.g. `Self::Quote → Sexp::Quasiquote`) type-checks
        // but silently corrupts every consumer that constructs a quote-
        // family Sexp through the projection — fails loudly here.
        // Sibling-arm sweep so the (marker, constructor) pair stays
        // load-bearing under reordering refactors.
        let inner = Sexp::symbol("payload");
        assert_eq!(
            QuoteForm::Quote.wrap(inner.clone()),
            Sexp::Quote(Box::new(inner.clone()))
        );
        assert_eq!(
            QuoteForm::Quasiquote.wrap(inner.clone()),
            Sexp::Quasiquote(Box::new(inner.clone()))
        );
        assert_eq!(
            QuoteForm::Unquote.wrap(inner.clone()),
            Sexp::Unquote(Box::new(inner.clone()))
        );
        assert_eq!(
            QuoteForm::UnquoteSplice.wrap(inner.clone()),
            Sexp::UnquoteSplice(Box::new(inner))
        );
    }

    #[test]
    fn quote_form_wrap_round_trips_through_as_quote_form_for_every_variant() {
        // ROUND-TRIP CONTRACT: pin the structural identity
        // `qf.wrap(inner.clone()).as_quote_form() == Some((qf, &inner))`
        // for every variant of the closed-set `QuoteForm` algebra. This
        // is the canonical law binding the marker→wrapper projection
        // (`wrap`) to its wrapper→marker dual (`as_quote_form`) on the
        // substrate's `Sexp` algebra. A regression that drifts the
        // (marker, constructor) pair on EITHER side — `wrap` routing
        // `Quote` to `Sexp::Quasiquote`, OR `as_quote_form` routing
        // `Sexp::Quote(_)` to `QuoteForm::Quasiquote` — surfaces as a
        // round-trip mismatch here. Sweep all four variants so the
        // round-trip stays load-bearing across the closed set. Same
        // posture as the `display_for_sexp_round_trips_each_quote_family
        // _variant_through_reader` round-trip pin at the Display→read
        // boundary; this test pins the round-trip at the marker→Sexp
        // projection boundary.
        let inner_body = Sexp::symbol("payload");
        for qf in [
            QuoteForm::Quote,
            QuoteForm::Quasiquote,
            QuoteForm::Unquote,
            QuoteForm::UnquoteSplice,
        ] {
            let wrapped = qf.wrap(inner_body.clone());
            let projected = wrapped
                .as_quote_form()
                .expect("wrap output must project back through as_quote_form");
            assert_eq!(
                projected.0, qf,
                "wrap→as_quote_form drifted at marker for variant {qf:?}"
            );
            assert_eq!(
                projected.1, &inner_body,
                "wrap→as_quote_form drifted at inner body for variant {qf:?}"
            );
        }
    }

    #[test]
    fn quote_form_all_is_unique_and_complete() {
        // CLOSED-SET TRUTH-TABLE: pin that `QuoteForm::ALL` carries
        // exactly the four reachable quote-family wrappers — no duplicates,
        // byte-equal coverage of `{Quote, Quasiquote, Unquote, UnquoteSplice}`.
        // The `[Self; 4]` array-literal arity already binds the count at
        // compile time; this test pins the *identity* of each slot so a
        // future re-ordering refactor (e.g. swapping `Unquote` and
        // `UnquoteSplice` positions) that leaves the cardinality intact
        // still fails loudly. Sibling discipline to
        // `unquote_form_all_is_unique_and_complete` (the 2-of-4 subset
        // sibling) and `atom_kind_all_is_unique_and_complete` (the peer
        // atomic-payload axis).
        //
        // The `iter+map+collect+sort_unstable` quadruple this test inlined
        // pre-lift now binds at `<QuoteForm 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::<QuoteForm>()` (the workspace-wide
        // testkit), so this test reduces to the per-implementor unique
        // payload (the four reader-punctuation literals in lexicographic
        // order — the load-bearing per-enum ground truth the substrate-wide
        // sort lift does NOT subsume).
        assert_eq!(QuoteForm::ALL.len(), 4);
        assert_eq!(
            <QuoteForm as tatara_closed_set::ClosedSet>::sorted_labels(),
            vec!["'", ",", ",@", "`"],
            "QuoteForm::ALL must cover every reachable homoiconic prefix-wrapper"
        );
    }

    #[test]
    fn quote_form_display_matches_prefix_for_every_variant() {
        // DISPLAY-EQUALS-PREFIX CONTRACT: pin that
        // `<QuoteForm as fmt::Display>::fmt` projects through
        // `QuoteForm::prefix` byte-for-byte for every variant in
        // `QuoteForm::ALL`. The Display impl is the canonical rendering
        // surface a future diagnostic annotation (`#[error("... {prefix}")]`
        // shape) threads through; pinning the equality here means a
        // regression that drifts EITHER the Display arm OR the `prefix`
        // arm independently surfaces at this test rather than silently
        // bifurcating the operator-facing rendered marker. Sibling
        // discipline to `unquote_form_display_renders_canonical_marker_
        // for_each_variant` (the 2-of-4 subset sibling) and
        // `atom_kind_display_matches_label_for_every_variant` (the peer
        // atomic-payload axis).
        for qf in QuoteForm::ALL {
            assert_eq!(
                qf.to_string(),
                qf.prefix(),
                "Display rendering for {qf:?} diverged from prefix() projection"
            );
        }
    }

    #[test]
    fn quote_form_prefix_round_trips_through_from_str() {
        // BIDIRECTIONAL ROUND-TRIP: pin the structural identity
        // `qf.prefix().parse() == Ok(qf)` for every variant in
        // `QuoteForm::ALL`. This is the canonical law binding the
        // marker→string projection (`prefix`) to its string→marker dual
        // (`FromStr`). A regression that drifts EITHER side — `prefix`
        // routing `Quote` to `` "`" ``, OR `FromStr` decoding `"'"` to
        // `Quasiquote` — surfaces as a round-trip mismatch here. Sweep
        // all four variants so the round-trip stays load-bearing across
        // the closed set. Same posture as the
        // `unquote_form_marker_round_trips_through_from_str` sibling on
        // the 2-of-4 template-substitution subset axis and
        // `atom_kind_label_round_trips_through_from_str` on the peer
        // atomic-payload axis.
        for qf in QuoteForm::ALL {
            let prefix = qf.prefix();
            let decoded: QuoteForm = prefix
                .parse()
                .expect("canonical prefix must decode through FromStr");
            assert_eq!(
                decoded, qf,
                "FromStr ↔ prefix round-trip drifted for variant {qf:?} (prefix {prefix:?})"
            );
        }
    }

    #[test]
    fn unknown_quote_form_carries_offending_input_verbatim() {
        // TYPED PARSE-FAILURE CONTRACT: pin the exact rendered shape of
        // `UnknownQuoteForm`'s `#[error(...)]` annotation AND the
        // verbatim `.0` field projection — no normalization, no case-
        // folding, no whitespace trimming. The error is part of the
        // substrate-wide `Unknown*` parse-rejection family
        // (`UnknownSexpShape`, `UnknownAtomKind`, `UnknownUnquoteForm`,
        // `UnknownRequestorKind`, `UnknownReceiptKind`, `UnknownPhase`,
        // `UnknownConditionKind`, `UnknownTeardownPolicy`, …) and the
        // joint rendered shape (`"unknown <thing>: {0}"`) is the
        // operator-facing diagnostic idiom every member preserves. A
        // regression that case-folds, trims, or strips the offending
        // input would silently rewrite an operator's literal value at
        // the diagnostic boundary — fails loudly here.
        let offending = "not-a-quote-prefix";
        let err: UnknownQuoteForm = offending
            .parse::<QuoteForm>()
            .expect_err("non-canonical input must reject through FromStr");
        assert_eq!(
            err.0, offending,
            "offending input was not preserved verbatim"
        );
        assert_eq!(
            err.to_string(),
            "unknown quote form: not-a-quote-prefix",
            "Display rendering diverged from the substrate-wide Unknown* idiom"
        );
    }

    #[test]
    fn quote_form_is_well_formed_closed_set() {
        // Structural contract: QuoteForm's four 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
        // (`AllocationPhase`, `RequestorKind`, `ProcessPhase`,
        // `ConditionKind`, `WorkloadKind`, …). The substrate-level
        // assertion runs on the auto-derived `impl ClosedSet for
        // QuoteForm` emitted by `#[derive(tatara_closed_set::DeriveClosedSet)]`
        // — a regression that drifts the derive's `make_unknown`
        // delegation, the `via = "prefix"` projection
        // (`"'" / "`" / "," / ",@"`), 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::<QuoteForm>();
    }

    #[test]
    fn quote_form_from_str_rejects_sexp_shape_labels_on_homoiconic_prefix_axis() {
        // CROSS-AXIS DISJOINTNESS: pin that `QuoteForm::FromStr` decodes
        // the homoiconic punctuation markers `'` / `` ` `` / `,` / `,@`
        // but rejects the `SexpShape` structural-identity vocabulary
        // (`"quote"` / `"quasiquote"` / `"unquote"` / `"unquote-splice"`)
        // AND the `iac_forge_tag` cross-crate canonical-form vocabulary
        // (`"quote"` / `"quasiquote"` / `"unquote"` / `"unquote-splicing"`).
        // The three closed sets project the SAME four `Sexp::*` quote-
        // family constructors on DISTINCT axes — a regression that
        // conflated them would let `"quote".parse::<QuoteForm>()` succeed
        // (silently bifurcating the diagnostic surface) or
        // `"'".parse::<SexpShape>()` succeed (silently colliding the
        // punctuation and structural-identity vocabularies). Sibling
        // discipline to `unquote_form_from_str_rejects_sexp_shape_labels_
        // on_template_marker_axis` (the 2-of-4 subset's matching
        // cross-axis pin).
        use crate::error::SexpShape;
        for shape in [
            SexpShape::Quote,
            SexpShape::Quasiquote,
            SexpShape::Unquote,
            SexpShape::UnquoteSplice,
        ] {
            let label = shape.label();
            assert!(
                label.parse::<QuoteForm>().is_err(),
                "SexpShape label {label:?} unexpectedly decoded through QuoteForm::FromStr — cross-axis vocabulary collision"
            );
        }
        for qf in QuoteForm::ALL {
            let tag = qf.iac_forge_tag();
            assert!(
                tag.parse::<QuoteForm>().is_err(),
                "iac_forge_tag {tag:?} unexpectedly decoded through QuoteForm::FromStr — cross-axis vocabulary collision"
            );
        }
    }

    #[test]
    fn quote_form_from_str_extends_unquote_form_from_str_on_the_2_of_4_subset() {
        // SUBSET-CONTAINMENT CONTRACT: pin that every successful
        // `UnquoteForm::FromStr` input is ALSO a successful
        // `QuoteForm::FromStr` input, AND the resulting variants project
        // to each other through `QuoteForm::as_unquote_form` (the 2-of-4
        // subset gate). This binds the two homoiconic-prefix axes
        // (`UnquoteForm`'s 2-of-2 template-substitution subset and
        // `QuoteForm`'s full 4-of-4 quote-family) at the FromStr
        // boundary: a regression that drifts EITHER FromStr's vocabulary
        // from the other (e.g. `UnquoteForm::FromStr` adding a spelling
        // `","` rejects in `QuoteForm::FromStr` would surface) fails
        // loudly here. Composition law: for every `uf` in
        // `UnquoteForm::ALL`, `uf.marker().parse::<QuoteForm>()` is
        // `Ok(qf)` where `qf.as_unquote_form() == Some(uf)`.
        use crate::error::UnquoteForm;
        for uf in UnquoteForm::ALL {
            let marker = uf.marker();
            let qf: QuoteForm = marker.parse().unwrap_or_else(|_| {
                panic!(
                    "UnquoteForm marker {marker:?} for {uf:?} did not decode through QuoteForm::FromStr — 2-of-4 subset containment violated"
                )
            });
            assert_eq!(
                qf.as_unquote_form(),
                Some(uf),
                "QuoteForm decoded from {marker:?} did not project back to UnquoteForm::{uf:?} via as_unquote_form"
            );
        }
    }

    #[test]
    fn quote_form_wrap_derives_each_arm_to_its_pre_lift_box_new_form() {
        // PATH-UNIFORMITY CONTRACT: pin that `QuoteForm::wrap` is
        // observably equivalent to the pre-lift four-arm reader pattern
        // `Sexp::<Variant>(Box::new(inner))` across every variant of the
        // closed set. The reader's pre-lift parse arms each constructed
        // their corresponding wrapper inline; post-lift the parse routes
        // through `QuoteForm::wrap`. A regression that drifts the
        // projection's allocation posture (e.g. wraps in an extra layer,
        // or skips the `Box::new`) fails loudly here. Companion to the
        // `wrap` projection test above — that test pins the (marker,
        // constructor) pairing; this test pins the structural shape of
        // each wrap output bit-for-bit against the pre-lift inline form.
        let inner = Sexp::List(vec![Sexp::symbol("inner"), Sexp::int(7)]);
        for (qf, expected) in [
            (QuoteForm::Quote, Sexp::Quote(Box::new(inner.clone()))),
            (
                QuoteForm::Quasiquote,
                Sexp::Quasiquote(Box::new(inner.clone())),
            ),
            (QuoteForm::Unquote, Sexp::Unquote(Box::new(inner.clone()))),
            (
                QuoteForm::UnquoteSplice,
                Sexp::UnquoteSplice(Box::new(inner.clone())),
            ),
        ] {
            assert_eq!(
                qf.wrap(inner.clone()),
                expected,
                "wrap drifted from pre-lift Sexp::<Variant>(Box::new(inner)) form for {qf:?}"
            );
        }
    }

    #[test]
    fn fmt_float_leaves_int_display_unchanged() {
        // Path-uniformity sibling: `Atom::Int` Display is unaffected by
        // the `fmt_float` introduction — the helper is wired only into
        // the `Atom::Float` arm of the Display match. A regression that
        // accidentally routes `Atom::Int` through `fmt_float` would
        // render `"1.0"` here and break every consumer that authored an
        // int kwarg expecting the bare-integer rendering.
        assert_eq!(Sexp::int(1).to_string(), "1");
        assert_eq!(Sexp::int(0).to_string(), "0");
        assert_eq!(Sexp::int(-42).to_string(), "-42");
    }

    // ── AtomKind + Atom::kind: closed-set atomic-payload projection ─────
    //
    // `AtomKind` is the closed-set typed discriminator for `Atom`'s six
    // payload variants — `Symbol`, `Keyword`, `Str`, `Int`, `Float`,
    // `Bool`. It is the atomic-payload peer of `QuoteForm` (the four
    // homoiconic prefix wrappers), and the two closed sets together
    // carve every non-Nil non-List arm of `SexpShape`'s twelve-variant
    // closed set via their typed `sexp_shape` projections. Lifting the
    // (Atom variant, byte-discriminator, canonical-label,
    // SexpShape variant) quadruple onto ONE typed algebra collapses:
    //   - `Hash for Atom`'s six byte literals (0/1/2/3/4/5) onto
    //     `AtomKind::hash_discriminator` via `self.kind()` — ONE arm
    //     at the discriminator site;
    //   - `domain::sexp_shape`'s six `Atom::X(_) → SexpShape::X` arms
    //     onto `a.kind().sexp_shape()` — ONE arm at the projection
    //     site;
    //   - any future LSP / REPL / metric-aggregator consumer that
    //     needs to round-trip a rendered diagnostic label back into
    //     the typed discriminator onto `AtomKind::FromStr` — ONE
    //     decode site keyed on `AtomKind::ALL` + `AtomKind::label`.
    //
    // Tests below pin:
    //   (a) `Atom::kind` projects every Atom variant to its typed
    //       discriminator, regardless of inner payload contents;
    //   (b) `AtomKind::ALL` enumerates every variant EXACTLY ONCE;
    //   (c) `AtomKind::label` returns the canonical
    //       lowercase / kebab string for every variant — byte-for-byte
    //       identical to the corresponding `SexpShape::label`;
    //   (d) `Display for AtomKind` delegates to `label`;
    //   (e) `AtomKind::hash_discriminator` returns the same byte
    //       values the pre-lift `Hash for Atom` arms emitted
    //       (0/1/2/3/4/5) — pin the cache-key contract so a
    //       regression that drifts a discriminator silently
    //       invalidates every cached macro expansion fails loudly
    //       here;
    //   (f) `AtomKind::sexp_shape` projects every variant to the
    //       matching `SexpShape` — the typed pairing the
    //       `domain::sexp_shape` collapse relies on;
    //   (g) `AtomKind::FromStr` round-trips every variant through its
    //       label; rejects non-canonical capitalizations, empty input,
    //       and the non-atom `SexpShape` labels (`"nil"`, `"list"`,
    //       `"quote"`, `"quasiquote"`, `"unquote"`, `"unquote-splice"`);
    //   (h) `UnknownAtomKind` carries the offending input verbatim and
    //       renders the `#[error(...)]` annotation byte-exactly;
    //   (i) `Hash for Atom` produces byte-identical hashes for every
    //       atomic variant as the pre-lift implementation — pin the
    //       cache-key contract end-to-end so the post-lift routing
    //       through `AtomKind::hash_discriminator` cannot drift the
    //       cache;
    //   (j) the cross-projection composition law
    //       `crate::domain::sexp_shape(&Sexp::Atom(a)) ==
    //       a.kind().sexp_shape()` holds for every atomic kind.

    #[test]
    fn atom_kind_projects_each_atom_variant_to_typed_marker() {
        // The structural identity `Atom::kind` establishes:
        // `Symbol(_) → AtomKind::Symbol`, `Keyword(_) →
        // AtomKind::Keyword`, etc. Pin every arm with a representative
        // payload + an empty / boundary payload so a regression that
        // matches on the payload rather than the variant identity
        // (e.g. a typo that routes `Str("")` to a different marker
        // than `Str("nonempty")`) surfaces immediately.
        assert_eq!(Atom::Symbol("foo".into()).kind(), AtomKind::Symbol);
        assert_eq!(Atom::Symbol(String::new()).kind(), AtomKind::Symbol);
        assert_eq!(Atom::Keyword("k".into()).kind(), AtomKind::Keyword);
        assert_eq!(Atom::Str("s".into()).kind(), AtomKind::Str);
        assert_eq!(Atom::Str(String::new()).kind(), AtomKind::Str);
        assert_eq!(Atom::Int(0).kind(), AtomKind::Int);
        assert_eq!(Atom::Int(i64::MIN).kind(), AtomKind::Int);
        assert_eq!(Atom::Int(i64::MAX).kind(), AtomKind::Int);
        assert_eq!(Atom::Float(0.0).kind(), AtomKind::Float);
        assert_eq!(Atom::Float(f64::NAN).kind(), AtomKind::Float);
        assert_eq!(Atom::Float(f64::INFINITY).kind(), AtomKind::Float);
        assert_eq!(Atom::Bool(true).kind(), AtomKind::Bool);
        assert_eq!(Atom::Bool(false).kind(), AtomKind::Bool);
    }

    #[test]
    fn atom_kind_all_is_unique_and_complete() {
        // Closed-set posture: `ALL` enumerates every reachable variant
        // EXACTLY ONCE — no duplicates, no omissions. The `[Self; 6]`
        // 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`, `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 `<AtomKind 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::<AtomKind>()`, so this test
        // reduces to the per-implementor unique payload (the six diagnostic
        // labels in lexicographic order).
        assert_eq!(AtomKind::ALL.len(), 6);
        assert_eq!(
            <AtomKind as tatara_closed_set::ClosedSet>::sorted_labels(),
            vec!["bool", "float", "int", "keyword", "string", "symbol"],
            "AtomKind::ALL must cover every reachable Atom payload kind"
        );
    }

    #[test]
    fn atom_kind_label_renders_canonical_string_for_every_variant() {
        // Pin every variant's canonical `&'static str` projection — a
        // regression that drifts any label (typo `"sym"` for
        // `"symbol"`, swap of `"int"` ↔ `"float"`, capitalization
        // drift `"String"` for `"string"`, or the `Str → "string"`
        // boundary rename being reversed to a literal `"str"`) fails-
        // loudly here. The six labels are byte-for-byte identical to
        // the corresponding `SexpShape::label` arms so the typed
        // diagnostic vocabulary stays unified across the AtomKind ⊂
        // SexpShape containment.
        assert_eq!(AtomKind::Symbol.label(), "symbol");
        assert_eq!(AtomKind::Keyword.label(), "keyword");
        assert_eq!(AtomKind::Str.label(), "string");
        assert_eq!(AtomKind::Int.label(), "int");
        assert_eq!(AtomKind::Float.label(), "float");
        assert_eq!(AtomKind::Bool.label(), "bool");
    }

    #[test]
    fn atom_kind_label_agrees_with_sexp_shape_label_for_every_atom_arm() {
        // CROSS-PROJECTION VOCABULARY CONTRACT: each `AtomKind`
        // variant's `label()` is byte-for-byte identical to the
        // corresponding `SexpShape` variant's `label()` (after the
        // `Str → String` typed-variant rename which is intentional
        // — the wire vocabulary is `"string"` on both axes). Pin the
        // six-way agreement so a future label rename on EITHER side
        // (a SexpShape `"string"` → `"str"` drift, or an AtomKind
        // `"int"` → `"i64"` drift) fails-loudly here, NOT silently
        // at every cross-axis consumer. The pairing is load-bearing
        // for the typed-projection composition
        // `AtomKind::sexp_shape().label() == AtomKind::label()`.
        //
        // Post-lift this contract is structurally true by composition
        // (`AtomKind::label`'s body IS `self.sexp_shape().label()`),
        // so the cross-axis sweep is a tautology — the regression
        // surface lives at `SexpShape::label`'s atomic arms now,
        // pinned by `atom_kind_label_renders_canonical_string_for_every_variant`
        // (which keys the same six literals through the composition).
        // The sweep stays in place as a structural invariant pin in
        // case a future implementor reverses the lift and re-inlines
        // the per-variant arms here — drift between the two sites
        // would re-emerge and this test catches it.
        for kind in AtomKind::ALL {
            assert_eq!(
                kind.label(),
                kind.sexp_shape().label(),
                "label vocabulary drift between AtomKind::{kind:?} \
                 and its SexpShape projection",
            );
        }
    }

    #[test]
    fn atom_kind_label_routes_through_sexp_shape_label_via_sexp_shape_projection() {
        // ROUTING-PIN CONTRACT: post-lift `AtomKind::label`'s body
        // composes `Self::sexp_shape()` with `SexpShape::label()`
        // verbatim — no inline per-arm literal table. The composition
        // law `AtomKind::label(k) == AtomKind::sexp_shape(k).label()`
        // is structurally true for every `k: AtomKind`; pinning the
        // routing means a regression that re-inlines the six atomic-
        // arm literals here surfaces as a drift between the inline
        // copy and the `SexpShape::label` canonical site rather than
        // surviving silently.
        //
        // Six representative cases — one per variant — walked through
        // the composition manually and through the direct projection,
        // then byte-compared. A drift in EITHER half of the composition
        // (a typo in `Self::sexp_shape`'s match arms swapping
        // `Self::Int → SexpShape::Float`, OR a typo in `SexpShape::label`
        // dropping the `Int → "int"` arm) fails this assertion AND every
        // sibling per-arm assertion in
        // `atom_kind_label_renders_canonical_string_for_every_variant`
        // — but THIS test names the routing axis explicitly so a
        // regression to inline-literal-arms shows up as a failure of
        // the routing pin alongside the per-arm pin.
        //
        // Sibling-lift posture to the prior-run routing pins:
        // `sexp_to_json_object_arm_routes_through_is_kwargs_list_method`
        // (commit 4a11f5b) pins `Sexp::to_json`'s kwargs gate through
        // the lifted predicate. This pin extends the same posture to
        // `AtomKind::label`'s structural routing through the
        // `Self::sexp_shape() ∘ SexpShape::label` composition.
        //
        // Theory anchor: THEORY.md §V.1 — knowable platform; the
        // label-projection routing is a NAMED structural contract
        // pinned alongside the per-arm vocabulary contract, so
        // operators reading the test surface see BOTH the load-bearing
        // identity AND the load-bearing composition. THEORY.md §VI.1
        // — generation over composition; the label projection emerges
        // from the typed pairing rather than per-arm literal discipline,
        // and the routing pin enforces the lift stays in effect.
        for kind in AtomKind::ALL {
            let via_label = kind.label();
            let via_composition = kind.sexp_shape().label();
            assert_eq!(
                via_label, via_composition,
                "AtomKind::{kind:?}::label() must route through \
                 Self::sexp_shape().label() — drift here means the \
                 lift was reverted to inline arms",
            );
            // The pointer-equality check pins the composition produces
            // the SAME `&'static str` (not just a byte-equal copy) for
            // every variant — proof the routing hits ONE static literal
            // site (`SexpShape::label`) rather than a parallel inline
            // table.
            assert!(
                std::ptr::eq(via_label.as_ptr(), via_composition.as_ptr()),
                "AtomKind::{kind:?}::label() must return the SAME \
                 `&'static str` as Self::sexp_shape().label() — \
                 pointer drift means the lift composes through a \
                 parallel literal table rather than routing into the \
                 canonical SexpShape::label site",
            );
        }
    }

    #[test]
    fn atom_kind_display_matches_label_for_every_variant() {
        // Pin Display-equals-label: any future
        // `#[error("... got {got}")]` annotation that threads through
        // this projection 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 any future diagnostic surface;
        // this test pins the contract. Sibling posture to
        // `sexp_shape_display_matches_label_for_every_variant` in
        // `error.rs`.
        assert_eq!(format!("{}", AtomKind::Symbol), "symbol");
        assert_eq!(format!("{}", AtomKind::Keyword), "keyword");
        assert_eq!(format!("{}", AtomKind::Str), "string");
        assert_eq!(format!("{}", AtomKind::Int), "int");
        assert_eq!(format!("{}", AtomKind::Float), "float");
        assert_eq!(format!("{}", AtomKind::Bool), "bool");
    }

    #[test]
    fn atom_kind_hash_discriminator_pins_legacy_atom_cache_key_bytes() {
        // CACHE-KEY CONTRACT: pre-lift `Hash for Atom` used the literal
        // byte values 0/1/2/3/4/5 for Symbol/Keyword/Str/Int/Float/Bool
        // as the per-variant discriminator. The macro-expansion cache
        // (`Expander::cache`) keys on Hash; ANY change to a
        // discriminator byte silently invalidates every cached
        // expansion across the substrate. Pin the six legacy values
        // explicitly so a regression that re-numbers them surfaces
        // immediately — the `AtomKind` algebra MUST preserve the prior
        // byte mapping bit-for-bit. Sibling posture to
        // `quote_form_hash_discriminator_pins_legacy_cache_key_bytes`
        // on the quote-family axis.
        assert_eq!(AtomKind::Symbol.hash_discriminator(), 0);
        assert_eq!(AtomKind::Keyword.hash_discriminator(), 1);
        assert_eq!(AtomKind::Str.hash_discriminator(), 2);
        assert_eq!(AtomKind::Int.hash_discriminator(), 3);
        assert_eq!(AtomKind::Float.hash_discriminator(), 4);
        assert_eq!(AtomKind::Bool.hash_discriminator(), 5);
    }

    #[test]
    fn atom_kind_hash_discriminator_bytes_are_pairwise_disjoint() {
        // Closed-set injectivity: the six discriminator bytes must
        // partition `{0, 1, 2, 3, 4, 5}` injectively so two distinct
        // `Atom` variants never produce the SAME hash discriminator —
        // a violation here means the cache could conflate two atomic
        // kinds with identical payloads (`Symbol("x")` and `Str("x")`
        // would silently share a cache slot). Sibling pin to
        // `atom_kind_all_is_unique_and_complete` on the label axis.
        let bytes: Vec<u8> = AtomKind::ALL
            .iter()
            .map(|k| k.hash_discriminator())
            .collect();
        let mut sorted = bytes.clone();
        sorted.sort_unstable();
        let mut deduped = sorted.clone();
        deduped.dedup();
        assert_eq!(
            sorted, deduped,
            "AtomKind hash discriminator bytes must be pairwise disjoint"
        );
        assert_eq!(sorted, vec![0, 1, 2, 3, 4, 5]);
    }

    // ── `AtomKind::{SYMBOL_HASH_DISCRIMINATOR,
    // KEYWORD_HASH_DISCRIMINATOR, STR_HASH_DISCRIMINATOR,
    // INT_HASH_DISCRIMINATOR, FLOAT_HASH_DISCRIMINATOR,
    // BOOL_HASH_DISCRIMINATOR, HASH_DISCRIMINATORS}` — per-role `u8`
    // cache-key byte algebra on the closed-set atomic-payload
    // [`AtomKind`]. Second per-role axis on the algebra alongside the
    // diagnostic-label (commit fc126b8) `&'static str` axis — direct
    // sibling of the prior-run
    // [`crate::error::QuoteForm::HASH_DISCRIMINATORS`] lift (commit
    // cb9b026) on the quote-family sub-carving of the same outer-Sexp
    // Hash body.
    //
    // The two families partition their respective cache-key spaces
    // independently: `AtomKind` at `{0..=5}` NESTED inside
    // `Sexp::Atom`'s outer `1u8` byte (`Hash for Atom` runs on the
    // `Atom` type, not `Sexp`), `QuoteForm` at `{3..=6}` at the outer
    // `Sexp` cache-key space itself. Post-lift ALL FOUR closed-set
    // carvings that participate in `Hash for Sexp` / `Hash for Atom`
    // (`AtomKind` here, `QuoteForm` prior-run, `StructuralKind` still
    // inline `{0, 2}`, outer-`SexpShape` composed through the three
    // carvings) name their canonical bytes on the typed algebra rather
    // than at scattered inline literals.

    #[test]
    fn atom_kind_hash_discriminators_pin_legacy_cache_key_bytes() {
        // Pin each per-role `pub(crate) const` at its exact canonical
        // `u8` byte. Sibling of
        // `atom_kind_hash_discriminator_pins_legacy_atom_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..=5}` is load-bearing for
        // `Hash for Atom`'s injectivity contract — a `2u8` drift to
        // `0u8` would silently collide `AtomKind::Str` with
        // `AtomKind::Symbol`'s cache-key byte and mis-hash every
        // `Str(x)` through the `Symbol(x)` arm's cache slot.
        assert_eq!(AtomKind::SYMBOL_HASH_DISCRIMINATOR, 0);
        assert_eq!(AtomKind::KEYWORD_HASH_DISCRIMINATOR, 1);
        assert_eq!(AtomKind::STR_HASH_DISCRIMINATOR, 2);
        assert_eq!(AtomKind::INT_HASH_DISCRIMINATOR, 3);
        assert_eq!(AtomKind::FLOAT_HASH_DISCRIMINATOR, 4);
        assert_eq!(AtomKind::BOOL_HASH_DISCRIMINATOR, 5);
    }

    #[test]
    fn atom_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` / `1` / `2` / `3` / `4` / `5` `u8` literal (or drifts one
        // arm's byte silently). Sibling posture 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 [
            (AtomKind::Symbol, AtomKind::SYMBOL_HASH_DISCRIMINATOR),
            (AtomKind::Keyword, AtomKind::KEYWORD_HASH_DISCRIMINATOR),
            (AtomKind::Str, AtomKind::STR_HASH_DISCRIMINATOR),
            (AtomKind::Int, AtomKind::INT_HASH_DISCRIMINATOR),
            (AtomKind::Float, AtomKind::FLOAT_HASH_DISCRIMINATOR),
            (AtomKind::Bool, AtomKind::BOOL_HASH_DISCRIMINATOR),
        ] {
            let actual = kind.hash_discriminator();
            assert_eq!(
                actual, expected,
                "AtomKind::{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 atom_kind_hash_discriminators_has_expected_cardinality() {
        // Cardinality contract: `Self::HASH_DISCRIMINATORS.len() == 6`
        // — pinned at the declaration site by rustc's forced-arity
        // check on `[u8; 6]`. 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
        // `atom_kind_labels_has_expected_cardinality` on the diagnostic
        // label axis of the SAME closed set, and to
        // `quote_form_hash_discriminators_has_expected_cardinality`
        // on the quote-family sub-carving's cache-key-byte peer.
        assert_eq!(
            AtomKind::HASH_DISCRIMINATORS.len(),
            6,
            "AtomKind::HASH_DISCRIMINATORS cardinality drifted from 6 \
             — the closed atomic-payload domain admits exactly six \
             kinds by construction; a seventh extension surfaces here"
        );
    }

    #[test]
    fn atom_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 `atom_kind_labels_align_with_all_by_index`
        // on the diagnostic label axis of the SAME closed set.
        for (i, kind) in AtomKind::ALL.iter().enumerate() {
            assert_eq!(
                AtomKind::HASH_DISCRIMINATORS[i],
                kind.hash_discriminator(),
                "AtomKind::HASH_DISCRIMINATORS[{i}] `{disc}` drifted \
                 from AtomKind::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 = AtomKind::HASH_DISCRIMINATORS[i],
                via_variant = kind.hash_discriminator(),
            );
        }
    }

    #[test]
    fn atom_kind_hash_discriminators_pairwise_distinct() {
        // PAIRWISE DISJOINTNESS: every entry of the
        // `HASH_DISCRIMINATORS` array must differ so the nested `Atom`
        // Hash body cannot route two atomic-payload variants through
        // the same cache-key byte — a collision would silently mis-
        // hash two structurally-distinct atoms (`Symbol("x")` and
        // `Str("x")`) 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
        // `atom_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 AtomKind::HASH_DISCRIMINATORS.iter().enumerate() {
            for (j, b) in AtomKind::HASH_DISCRIMINATORS.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "AtomKind::HASH_DISCRIMINATORS[{i}] `{a}` collides \
                     with AtomKind::HASH_DISCRIMINATORS[{j}] `{b}` — \
                     the nested Atom Hash body's cache-key partition \
                     would route two atomic-payload variants through \
                     the same slot"
                );
            }
        }
    }

    #[test]
    fn atom_kind_outer_hash_discriminator_pins_legacy_atomic_carve_outer_marker_byte() {
        // Pin `AtomKind::OUTER_HASH_DISCRIMINATOR` at its exact canonical
        // `u8` byte — the outer-Sexp cache-key byte at which ALL SIX
        // atomic-payload shapes collapse when hashed at the outer
        // `Hash for Sexp` level. Pre-lift the same byte lived at four
        // sites: the inline `1u8` literal at
        // `SexpShape::hash_discriminator`'s six-arm atomic collapse (in
        // error.rs), the inline `1u8` literal at
        // `sexp_shape_hash_discriminator_atomic_arms_collapse_to_outer_atom_marker`'s
        // assertion body, the inline `1u8` literal at
        // `sexp_shape_hash_discriminator_partitions_by_three_way_carving_disjointly`'s
        // `expected_atomic` fixture, PLUS a duplicated local `const
        // ATOM_OUTER_CARVE_BYTE: u8 = 1` inside
        // `structural_kind_hash_discriminator_disjoint_from_atom_outer_carve_byte_and_quote_form_hash_discriminator_partition`.
        // Post-lift the byte binds at ONE `pub(crate) const` on the
        // closed-set `AtomKind` algebra; every downstream consumer
        // (the shape-level projection's atomic collapse arm, the two
        // three-way carving pins in error.rs, the joint-partition
        // disjointness pin in error.rs, a future `tatara-check`
        // predicate on the outer-Sexp cache-key partition) picks up
        // the same canonical byte from ONE source of truth. Sibling
        // posture to `atom_kind_hash_discriminators_pin_legacy_cache_key_bytes`
        // (which pins the six NESTED INNER `{0..=5}` bytes on the
        // per-atom-kind inner algebra) — this pin closes the (nested,
        // outer) pairing on the same `AtomKind` algebra by naming the
        // outer-Sexp marker byte alongside the nested inner carve.
        // The cache-key partition is load-bearing for the outer
        // `Hash for Sexp` prefix-uniqueness contract — a `1u8` drift
        // to `0u8` would silently collide the atomic-carve outer
        // marker with `StructuralKind::Nil`'s outer byte (`0`) and
        // mis-hash every `Sexp::Atom(_)` through the `Sexp::Nil`
        // arm's cache slot; a drift to `2u8` would collide with
        // `StructuralKind::List`'s outer byte and mis-hash through
        // the `Sexp::List(_)` arm's slot; a drift to `3u8` /
        // `4u8` / `5u8` / `6u8` would collide with the quote-family
        // carve's four bytes.
        assert_eq!(AtomKind::OUTER_HASH_DISCRIMINATOR, 1);
    }

    #[test]
    fn atom_kind_outer_hash_discriminator_disjoint_from_inner_hash_discriminators_at_outer_sexp_level(
    ) {
        // OUTER-vs-INNER SEPARATION: the outer-Sexp cache-key algebra
        // uses TWO distinct byte spaces at TWO hash-sequence positions
        // for the atomic-carve: `AtomKind::OUTER_HASH_DISCRIMINATOR`
        // (`1u8` at the outer `Hash for Sexp` position) AND the
        // NESTED INNER `AtomKind::HASH_DISCRIMINATORS` bytes (`{0..=5}`
        // at the inner `Hash for Atom` position). The two byte spaces
        // OVERLAP numerically (both contain `1u8`) but do NOT collide
        // at the cache because they live at DIFFERENT hash-sequence
        // positions in the composed `(outer_discriminator,
        // inner_discriminator, inner_payload)` triple. Pin the outer
        // scalar's byte at `AtomKind::OUTER_HASH_DISCRIMINATOR` and
        // the inner set at `AtomKind::HASH_DISCRIMINATORS` so a future
        // refactor that conflates the two axes (e.g. drops the outer
        // marker byte at `Hash for Sexp`'s Atom arm and expects the
        // inner byte to distinguish outer-Sexp variants directly)
        // surfaces at THIS test as a documentation-of-intent failure.
        // The check is intentionally structural: it asserts the outer
        // scalar is IN the same numeric range as the inner set (both
        // are `u8`, both live within `{0..=6}` on the outer cache-key
        // partition) BUT that the outer scalar sits at position 1
        // where the inner byte space would otherwise have
        // `AtomKind::KEYWORD_HASH_DISCRIMINATOR` collide. That
        // numeric-collision without cache-collision is the
        // load-bearing property this lift documents: the two axes are
        // typed distinct because they live at typed distinct
        // positions in the composed hash sequence, even though their
        // byte spaces overlap.
        assert!(
            AtomKind::HASH_DISCRIMINATORS.contains(&AtomKind::OUTER_HASH_DISCRIMINATOR),
            "the outer-carve marker byte `{outer}` MUST lie within the \
             inner cache-key partition `{inner:?}` — the two axes' \
             byte spaces overlap by design (the outer distinguishes \
             `Sexp::Atom(_)` from every other outer-Sexp variant at \
             the outer hash position; the inner distinguishes the six \
             atomic-payload variants at the nested inner hash \
             position). If this contains check fails, the outer \
             scalar has drifted OUTSIDE the inner partition and the \
             (outer, inner) numeric-overlap-without-cache-collision \
             property this lift documents no longer holds — which \
             would in turn mean either the outer byte drifted out of \
             `{{0..=5}}` (compile the substrate against the resulting \
             outer-Sexp partition to find the drift) or the inner \
             partition shrank below `{{0..=5}}` (`atom_kind_hash_discriminators_align_with_all_by_index` \
             fails-loudly first).",
            outer = AtomKind::OUTER_HASH_DISCRIMINATOR,
            inner = AtomKind::HASH_DISCRIMINATORS,
        );
    }

    #[test]
    fn atom_kind_sexp_shape_pins_canonical_shape_identity_for_every_variant() {
        // CLOSED-SET SHAPE-PROJECTION CONTRACT: each `AtomKind` variant
        // projects to its matching `SexpShape` variant — load-bearing
        // for the (Atom variant, SexpShape variant) pairing the
        // substrate's outer-shape projection `domain::sexp_shape` routes
        // through. Sibling-arm sweep so the six pairings stay
        // load-bearing under reordering refactors. A regression that
        // drifts ONE arm (e.g. routes `AtomKind::Int` to
        // `SexpShape::Float`) surfaces here immediately rather than as
        // a silent operator-facing diagnostic drift at every
        // `LispError::TypeMismatch.got` slot for an atomic witness.
        // Sibling posture to
        // `quote_form_sexp_shape_pins_canonical_shape_identity_for_every_variant`.
        assert_eq!(AtomKind::Symbol.sexp_shape(), SexpShape::Symbol);
        assert_eq!(AtomKind::Keyword.sexp_shape(), SexpShape::Keyword);
        assert_eq!(AtomKind::Str.sexp_shape(), SexpShape::String);
        assert_eq!(AtomKind::Int.sexp_shape(), SexpShape::Int);
        assert_eq!(AtomKind::Float.sexp_shape(), SexpShape::Float);
        assert_eq!(AtomKind::Bool.sexp_shape(), SexpShape::Bool);
    }

    #[test]
    fn atom_kind_per_role_shapes_pin_canonical_sexp_shape_variants() {
        // PER-ROLE ALIAS CONTRACT: each `AtomKind::*_SHAPE` per-role
        // `pub const` binds byte-for-byte to its canonical `SexpShape`
        // variant on the AtomKind ⊂ SexpShape carving. Pin so a
        // regression that swaps ONE alias (e.g. re-aims `STR_SHAPE`
        // at `SexpShape::Symbol`) 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 `atom_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!(AtomKind::SYMBOL_SHAPE, SexpShape::Symbol);
        assert_eq!(AtomKind::KEYWORD_SHAPE, SexpShape::Keyword);
        assert_eq!(AtomKind::STR_SHAPE, SexpShape::String);
        assert_eq!(AtomKind::INT_SHAPE, SexpShape::Int);
        assert_eq!(AtomKind::FLOAT_SHAPE, SexpShape::Float);
        assert_eq!(AtomKind::BOOL_SHAPE, SexpShape::Bool);
    }

    #[test]
    fn atom_kind_shapes_has_expected_cardinality() {
        // CLOSED-SET CARDINALITY CONTRACT: `AtomKind::SHAPES` carries
        // exactly SIX entries — one per variant in the closed-set
        // atomic-payload carving. Runtime companion to the `[SexpShape;
        // 6]` 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; 6]` type check
        // at rustc time; this runtime pin catches a silent shrink or
        // duplicate-arm coalesce. Sibling posture to
        // `atom_kind_labels_has_expected_cardinality` and
        // `atom_kind_hash_discriminators_has_expected_cardinality` on
        // the other two per-role axes of the SAME closed set.
        assert_eq!(AtomKind::SHAPES.len(), 6);
        assert_eq!(AtomKind::SHAPES.len(), AtomKind::ALL.len());
    }

    #[test]
    fn atom_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
        // atomic variant to its canonical outer-shape identity
        // (LSP completion, `tatara-check` predicate over the
        // atomic ⊂ outer partition, Sekiban audit-trail metric
        // jointly labeled by the embed target). Sibling posture to
        // `atom_kind_labels_align_with_all_by_index` and
        // `atom_kind_hash_discriminators_align_with_all_by_index` on
        // the other two per-role axes of the SAME closed set.
        for (i, kind) in AtomKind::ALL.iter().enumerate() {
            assert_eq!(
                AtomKind::SHAPES[i],
                kind.sexp_shape(),
                "AtomKind::SHAPES[{i}] `{shape:?}` drifted from \
                 AtomKind::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 = AtomKind::SHAPES[i],
                via_variant = kind.sexp_shape(),
            );
        }
    }

    #[test]
    fn atom_kind_shapes_align_with_all_by_index_through_as_atom_kind() {
        // ROUND-TRIP CONTRACT: `Self::SHAPES[i].as_atom_kind() ==
        // Some(Self::ALL[i])` element-wise. Pins the embed / project
        // section of the (`AtomKind::sexp_shape`,
        // `SexpShape::as_atom_kind`) `Iso(AtomKind, AtomShape ⊂
        // 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_atom_kind` arms silently breaks the (embed, project)
        // section — this pin catches both directions at ONCE.
        // Sibling posture to the pre-existing per-variant round-trip
        // sweep `atom_kind_sexp_shape_round_trips_through_sexp_shape_as_atom_kind`
        // (which sweeps through the projection method); this sweep
        // pins the round-trip through the SHAPES array directly so a
        // regression on ANY of the three surfaces (per-role alias,
        // family-wide array, projection method) fails-loudly at the
        // array-indexed sweep.
        for (i, kind) in AtomKind::ALL.iter().enumerate() {
            assert_eq!(
                AtomKind::SHAPES[i].as_atom_kind(),
                Some(*kind),
                "AtomKind::SHAPES[{i}] `{shape:?}`.as_atom_kind() = \
                 {actual:?} drifted from Some(AtomKind::ALL[{i}]) = \
                 Some({expected:?}) — the (SHAPES entry, ALL variant) \
                 round-trip through the peer inverse SexpShape::as_atom_kind \
                 must hold element-wise",
                shape = AtomKind::SHAPES[i],
                actual = AtomKind::SHAPES[i].as_atom_kind(),
                expected = kind,
            );
        }
    }

    #[test]
    fn atom_kind_sexp_shape_routes_through_typed_per_role_constants() {
        // ROUTING CONTRACT: `AtomKind::sexp_shape()`'s six 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 six literals here (and
        // gains its own drift surface separate from the canonical
        // per-role alias site) surfaces immediately at variant
        // equality. Sibling posture to
        // `atom_kind_label_arms_route_through_per_role_labels_for_every_variant`
        // and `atom_kind_hash_discriminator_routes_through_typed_per_role_constants`
        // on the other two per-role axes of the SAME closed set.
        assert_eq!(AtomKind::Symbol.sexp_shape(), AtomKind::SYMBOL_SHAPE);
        assert_eq!(AtomKind::Keyword.sexp_shape(), AtomKind::KEYWORD_SHAPE);
        assert_eq!(AtomKind::Str.sexp_shape(), AtomKind::STR_SHAPE);
        assert_eq!(AtomKind::Int.sexp_shape(), AtomKind::INT_SHAPE);
        assert_eq!(AtomKind::Float.sexp_shape(), AtomKind::FLOAT_SHAPE);
        assert_eq!(AtomKind::Bool.sexp_shape(), AtomKind::BOOL_SHAPE);
    }

    #[test]
    fn atom_kind_shapes_pairwise_distinct() {
        // PAIRWISE DISJOINTNESS: every entry of the `SHAPES` array
        // must differ so the (AtomKind variant, SexpShape embed
        // target) mapping stays injective — a collision would silently
        // route two distinct AtomKind variants through the SAME
        // outer-shape identity, breaking the AtomKind ⊂ SexpShape
        // 6-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_labels_pairwise_distinct` and
        // `atom_kind_hash_discriminators_pairwise_distinct` on the
        // other two per-role axes of the SAME closed set.
        for (i, a) in AtomKind::SHAPES.iter().enumerate() {
            for (j, b) in AtomKind::SHAPES.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "AtomKind::SHAPES[{i}] `{a:?}` collides with \
                     AtomKind::SHAPES[{j}] `{b:?}` — the AtomKind ⊂ \
                     SexpShape 6-of-12 carving would route two atomic \
                     variants through the same outer-shape identity"
                );
            }
        }
    }

    #[test]
    fn quote_form_per_role_shapes_pin_canonical_sexp_shape_variants() {
        // PER-ROLE ALIAS CONTRACT: each `QuoteForm::*_SHAPE` per-role
        // `pub const` binds byte-for-byte to its canonical `SexpShape`
        // variant on the QuoteForm ⊂ SexpShape 4-of-12 carving. Pin
        // so a regression that swaps ONE alias (e.g. re-aims
        // `UNQUOTE_SPLICE_SHAPE` at `SexpShape::Unquote`) 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
        // `quote_form_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!(QuoteForm::QUOTE_SHAPE, SexpShape::Quote);
        assert_eq!(QuoteForm::QUASIQUOTE_SHAPE, SexpShape::Quasiquote);
        assert_eq!(QuoteForm::UNQUOTE_SHAPE, SexpShape::Unquote);
        assert_eq!(QuoteForm::UNQUOTE_SPLICE_SHAPE, SexpShape::UnquoteSplice);
    }

    #[test]
    fn quote_form_shapes_has_expected_cardinality() {
        // CLOSED-SET CARDINALITY CONTRACT: `QuoteForm::SHAPES` carries
        // exactly FOUR entries — one per variant in the closed-set
        // quote-family carving. Runtime companion to the `[SexpShape;
        // 4]` 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; 4]` type check
        // at rustc time; this runtime pin catches a silent shrink or
        // duplicate-arm coalesce. Sibling posture to
        // `quote_form_labels_has_expected_cardinality` /
        // `quote_form_prefixes_has_expected_cardinality` /
        // `quote_form_iac_forge_tags_has_expected_cardinality` /
        // `quote_form_hash_discriminators_has_expected_cardinality` on
        // the other four per-role axes of the SAME closed set.
        assert_eq!(QuoteForm::SHAPES.len(), 4);
        assert_eq!(QuoteForm::SHAPES.len(), QuoteForm::ALL.len());
    }

    #[test]
    fn quote_form_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
        // quote-family variant to its canonical outer-shape identity
        // (LSP completion, `tatara-check` predicate over the quote-
        // family ⊂ outer partition, Sekiban audit-trail metric jointly
        // labeled by the embed target). Sibling posture to
        // `quote_form_labels_align_with_all_by_index` /
        // `quote_form_prefixes_align_with_all_by_index` on the other
        // per-role axes of the SAME closed set.
        for (i, form) in QuoteForm::ALL.iter().enumerate() {
            assert_eq!(
                QuoteForm::SHAPES[i],
                form.sexp_shape(),
                "QuoteForm::SHAPES[{i}] `{shape:?}` drifted from \
                 QuoteForm::ALL[{i}] ({form:?}).sexp_shape() \
                 `{via_variant:?}` — the canonical declaration order \
                 of the ALL array and the sexp_shape projection must \
                 match element-wise",
                shape = QuoteForm::SHAPES[i],
                via_variant = form.sexp_shape(),
            );
        }
    }

    #[test]
    fn quote_form_shapes_align_with_all_by_index_through_as_quote_form() {
        // ROUND-TRIP CONTRACT: `Self::SHAPES[i].as_quote_form() ==
        // Some(Self::ALL[i])` element-wise. Pins the embed / project
        // section of the (`QuoteForm::sexp_shape`,
        // `SexpShape::as_quote_form`) `Iso(QuoteForm, QuoteShape ⊂
        // 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_quote_form` 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.
        for (i, form) in QuoteForm::ALL.iter().enumerate() {
            assert_eq!(
                QuoteForm::SHAPES[i].as_quote_form(),
                Some(*form),
                "QuoteForm::SHAPES[{i}] `{shape:?}`.as_quote_form() = \
                 {actual:?} drifted from Some(QuoteForm::ALL[{i}]) = \
                 Some({expected:?}) — the (SHAPES entry, ALL variant) \
                 round-trip through the peer inverse SexpShape::as_quote_form \
                 must hold element-wise",
                shape = QuoteForm::SHAPES[i],
                actual = QuoteForm::SHAPES[i].as_quote_form(),
                expected = form,
            );
        }
    }

    #[test]
    fn quote_form_sexp_shape_routes_through_typed_per_role_constants() {
        // ROUTING CONTRACT: `QuoteForm::sexp_shape()`'s four 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 four literals here (and gains its own
        // drift surface separate from the canonical per-role alias
        // site) surfaces immediately at variant equality. Sibling
        // posture to
        // `quote_form_label_composes_through_sexp_shape_label_for_every_variant`
        // (which pins label routing through sexp_shape().label()) and
        // `atom_kind_sexp_shape_routes_through_typed_per_role_constants`
        // on the peer 6-of-12 atomic-payload carving.
        assert_eq!(QuoteForm::Quote.sexp_shape(), QuoteForm::QUOTE_SHAPE);
        assert_eq!(
            QuoteForm::Quasiquote.sexp_shape(),
            QuoteForm::QUASIQUOTE_SHAPE
        );
        assert_eq!(QuoteForm::Unquote.sexp_shape(), QuoteForm::UNQUOTE_SHAPE);
        assert_eq!(
            QuoteForm::UnquoteSplice.sexp_shape(),
            QuoteForm::UNQUOTE_SPLICE_SHAPE
        );
    }

    #[test]
    fn quote_form_shapes_pairwise_distinct() {
        // PAIRWISE DISJOINTNESS: every entry of the `SHAPES` array
        // must differ so the (QuoteForm variant, SexpShape embed
        // target) mapping stays injective — a collision would silently
        // route two distinct QuoteForm variants through the SAME
        // outer-shape identity, breaking the QuoteForm ⊂ SexpShape
        // 4-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` on the peer 6-of-12
        // atomic-payload carving.
        for (i, a) in QuoteForm::SHAPES.iter().enumerate() {
            for (j, b) in QuoteForm::SHAPES.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "QuoteForm::SHAPES[{i}] `{a:?}` collides with \
                     QuoteForm::SHAPES[{j}] `{b:?}` — the QuoteForm ⊂ \
                     SexpShape 4-of-12 carving would route two quote-\
                     family variants through the same outer-shape identity"
                );
            }
        }
    }

    #[test]
    fn atom_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 diagnostic literal can drift apart — pinning it
        // here means they cannot. Sibling posture to
        // `sexp_shape_label_round_trips_through_from_str`.
        for kind in AtomKind::ALL {
            let parsed: AtomKind = 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 unknown_atom_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: UnknownAtomKind = "Symbol".parse::<AtomKind>().expect_err(
            "capitalized `Symbol` must NOT decode — labels are byte-equal case-sensitive",
        );
        assert_eq!(err.0, "Symbol");
        assert_eq!(format!("{err}"), "unknown atom kind: Symbol");

        let err: UnknownAtomKind = "str"
            .parse::<AtomKind>()
            .expect_err("`str` is not a canonical AtomKind label — `string` is");
        assert_eq!(err.0, "str");
        assert_eq!(format!("{err}"), "unknown atom kind: str");

        let err: UnknownAtomKind = ""
            .parse::<AtomKind>()
            .expect_err("empty input must NOT decode to an AtomKind");
        assert_eq!(err.0, "");
        assert_eq!(format!("{err}"), "unknown atom kind: ");
    }

    #[test]
    fn atom_kind_from_str_rejects_non_atom_sexp_shape_labels() {
        // CROSS-AXIS GUARD: `SexpShape::label()`'s vocabulary is the
        // SUPERSET of `AtomKind::label()`'s — every AtomKind label
        // decodes successfully through SexpShape's FromStr to the
        // matching SexpShape variant (because the typed projections
        // agree), but the SIX non-atom SexpShape labels (`"nil"`,
        // `"list"`, `"quote"`, `"quasiquote"`, `"unquote"`,
        // `"unquote-splice"`) MUST reject through AtomKind's FromStr
        // — they have no atomic-kind preimage. A FromStr that
        // silently accepted `"list"` as an AtomKind would corrupt
        // the typed identity downstream of any future diagnostic
        // round-trip. Pin BOTH directions: the six atom labels
        // decode successfully (and to the matching `AtomKind`
        // variant), the six non-atom labels reject.
        assert_eq!("symbol".parse::<AtomKind>().unwrap(), AtomKind::Symbol);
        assert_eq!("keyword".parse::<AtomKind>().unwrap(), AtomKind::Keyword);
        assert_eq!("string".parse::<AtomKind>().unwrap(), AtomKind::Str);
        assert_eq!("int".parse::<AtomKind>().unwrap(), AtomKind::Int);
        assert_eq!("float".parse::<AtomKind>().unwrap(), AtomKind::Float);
        assert_eq!("bool".parse::<AtomKind>().unwrap(), AtomKind::Bool);

        // Non-atom SexpShape labels (the six structural shapes
        // OUTSIDE the AtomKind closed set) must reject.
        for label in [
            "nil",
            "list",
            "quote",
            "quasiquote",
            "unquote",
            "unquote-splice",
        ] {
            assert!(
                label.parse::<AtomKind>().is_err(),
                "non-atom SexpShape label {label:?} must NOT decode to an AtomKind",
            );
        }

        // Sanity: typed peers' labels (`UnquoteForm::marker`'s
        // `,` / `,@` punctuation, `ExpectedKwargShape`'s
        // `"number"` / `"list of strings"` vocabulary) live on
        // different axes and MUST reject too — pin the closed-set
        // boundary.
        for label in [",", ",@", "number", "list of strings", "atom", "Atom"] {
            assert!(
                label.parse::<AtomKind>().is_err(),
                "cross-axis label {label:?} must NOT decode to an AtomKind",
            );
        }
    }

    #[test]
    fn atom_kind_is_well_formed_closed_set() {
        // Structural contract: AtomKind's six 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
        // (`AllocationPhase`, `RequestorKind`, `ProcessPhase`,
        // `ConditionKind`, `WorkloadKind`, …). The substrate-level
        // assertion runs on the auto-derived `impl ClosedSet for
        // AtomKind` emitted by `#[derive(tatara_closed_set::DeriveClosedSet)]`
        // — a regression that drifts the derive's `make_unknown`
        // delegation, the `via = "label"` projection, 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::<AtomKind>();
    }

    #[test]
    fn atom_kind_per_role_labels_alias_sexp_shape_per_role_labels_byte_for_byte() {
        // ALIAS CONTRACT: pin every one of the six per-role
        // `pub const AtomKind::*_LABEL` aliases equals the corresponding
        // `pub const SexpShape::*_LABEL` byte-for-byte — so the AtomKind
        // ⊂ SexpShape marker-vocabulary containment routes through the
        // typed `pub const AtomKind::V_LABEL: &'static str =
        // SexpShape::V_LABEL` alias chain rather than through two
        // independent literal-discipline sites. A regression that
        // renames the SexpShape side without updating the AtomKind
        // alias pointing at it fails-loudly here with the exact axis
        // identified (SYMBOL / KEYWORD / STRING / INT / FLOAT / BOOL);
        // a regression that re-inlines the AtomKind constant to a
        // fresh literal still passes this pin but loses the alias-
        // chain typing (which is what
        // `atom_kind_label_arms_route_through_per_role_labels_for_every_variant`
        // + `atom_kind_labels_align_with_all_by_index` catch in
        // combination).
        //
        // Six per-role checks, each spelled out so a regression on ONE
        // variant surfaces the exact axis rather than through a
        // variant-loop that hides which arm drifted. The `Str →
        // String` boundary rename is intentional and load-bearing (the
        // wire vocabulary is `"string"` on both axes) — the
        // STRING_LABEL alias is the canonical bridge, so a future
        // rename that reverses the `Str → "string"` rename to a
        // literal `"str"` fails the byte-equality pin at THIS test.
        assert_eq!(AtomKind::SYMBOL_LABEL, SexpShape::SYMBOL_LABEL);
        assert_eq!(AtomKind::KEYWORD_LABEL, SexpShape::KEYWORD_LABEL);
        assert_eq!(AtomKind::STRING_LABEL, SexpShape::STRING_LABEL);
        assert_eq!(AtomKind::INT_LABEL, SexpShape::INT_LABEL);
        assert_eq!(AtomKind::FLOAT_LABEL, SexpShape::FLOAT_LABEL);
        assert_eq!(AtomKind::BOOL_LABEL, SexpShape::BOOL_LABEL);
    }

    #[test]
    fn atom_kind_label_arms_route_through_per_role_labels_for_every_variant() {
        // PATH-UNIFORMITY: `AtomKind::V.label()` MUST equal the per-
        // role `pub const AtomKind::V_LABEL` for every `v: AtomKind`.
        // Pre-lift the six atomic-payload marker bytes were reachable
        // through `AtomKind::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
        // `AtomKind::*_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
        // `sexp_shape_label_routes_through_typed_per_variant_constants`
        // one algebra layer up — the parent superset's per-role
        // constants are pinned against `SexpShape::label`'s arms
        // there; this pin binds the AtomKind subset algebra's per-
        // role aliases against `AtomKind::label`'s composition-routed
        // arms so the six atomic-payload marker labels project through
        // ONE aliased typed source of truth per role rather than
        // through per-consumer inline literals.
        assert_eq!(AtomKind::Symbol.label(), AtomKind::SYMBOL_LABEL);
        assert_eq!(AtomKind::Keyword.label(), AtomKind::KEYWORD_LABEL);
        assert_eq!(AtomKind::Str.label(), AtomKind::STRING_LABEL);
        assert_eq!(AtomKind::Int.label(), AtomKind::INT_LABEL);
        assert_eq!(AtomKind::Float.label(), AtomKind::FLOAT_LABEL);
        assert_eq!(AtomKind::Bool.label(), AtomKind::BOOL_LABEL);
    }

    #[test]
    fn atom_kind_labels_has_expected_cardinality() {
        // Cardinality pin: `LABELS.len() == 6` matches `ALL.len()` so a
        // refactor that loosens the type to `&'static [&'static str]`
        // fails HERE (the `[_; 6]` 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 — six
        // atomic-payload markers, matching the six-arm carving of the
        // parent `SexpShape::LABELS` (the atomic subset of the twelve
        // canonical outer-shape labels).
        assert_eq!(AtomKind::LABELS.len(), 6);
        assert_eq!(AtomKind::LABELS.len(), AtomKind::ALL.len());
    }

    #[test]
    fn atom_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
        // `AtomKind::LABELS`, a Sekiban metric emitter labeling
        // `tatara_lisp_atom_type_mismatch_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!(AtomKind::LABELS.len(), AtomKind::ALL.len());
        for (i, kind) in AtomKind::ALL.iter().enumerate() {
            assert_eq!(
                AtomKind::LABELS[i],
                kind.label(),
                "AtomKind::LABELS[{i}] `{lbl}` drifted from \
                 AtomKind::ALL[{i}].label() `{via_variant}` — the \
                 canonical ALL ordering and the LABELS ordering must \
                 match element-wise",
                lbl = AtomKind::LABELS[i],
                via_variant = kind.label(),
            );
        }
    }

    #[test]
    fn atom_kind_labels_pairwise_distinct() {
        // 6x6 pairwise sweep so a collision between any two labels
        // (which would silently degrade two distinct atomic-payload
        // 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::<AtomKind>()` (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 AtomKind::LABELS.iter().enumerate() {
            for (j, b) in AtomKind::LABELS.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "AtomKind::LABELS[{i}] ({a:?}) collides with \
                     AtomKind::LABELS[{j}] ({b:?}) — two distinct \
                     atomic-payload markers cannot share diagnostic bytes",
                );
            }
        }
    }

    #[test]
    fn atom_label_projects_each_variant_to_canonical_diagnostic_label() {
        // PER-ARM CONTRACT: pin the outer-`Atom` `Self::label`
        // projection produces the SIX canonical `&'static str` labels
        // byte-for-byte across every reachable atomic-payload variant.
        // Pre-lift the outer-`Atom` label projection had no typed
        // primitive on the value-carrier algebra — a consumer with an
        // `Atom` value in hand wanting the canonical diagnostic label
        // had to spell the two-step composition `atom.kind().label()`
        // at every callsite, OR go through
        // `Sexp::Atom(atom.clone()).type_name()` which wraps and
        // unwraps for no runtime purpose. Post-lift the SIX arms bind
        // at ONE typed projection on the outer-`Atom` algebra that
        // routes through `AtomKind::label` (which itself composes
        // through `AtomKind::sexp_shape().label()` into the canonical
        // `SexpShape::label` site) — the (Atom variant, diagnostic
        // label) pairing binds at ONE typed algebra composition
        // spanning FOUR typed layers.
        //
        // Sibling-shape pin to
        // `atom_kind_label_renders_canonical_string_for_every_variant`
        // one algebra layer down and
        // `sexp_type_name_method_projects_each_outer_arm_to_canonical_label`
        // one algebra layer up. A regression that drifts ONE arm's
        // label (e.g. Symbol → "sym", swapping Int ↔ Float, dropping
        // the `Str → "string"` boundary rename) fails-loudly at THIS
        // test AND the sibling `AtomKind::label` per-arm pin.
        assert_eq!(Atom::Symbol("foo".to_owned()).label(), "symbol");
        assert_eq!(Atom::Keyword("kw".to_owned()).label(), "keyword");
        assert_eq!(Atom::Str("hi".to_owned()).label(), "string");
        assert_eq!(Atom::Int(42).label(), "int");
        assert_eq!(Atom::Float(1.5).label(), "float");
        assert_eq!(Atom::Bool(true).label(), "bool");
        assert_eq!(Atom::Bool(false).label(), "bool");
    }

    #[test]
    fn atom_label_composes_through_kind_label_for_every_variant() {
        // COMPOSITION-LAW CONTRACT: `atom.label() == atom.kind().label()`
        // for every reachable atomic payload — the outer-`Atom` label
        // projection is structurally derived through `Self::kind` +
        // `AtomKind::label` rather than through a parallel six-arm
        // inline match on the outer-`Atom` algebra. Pin the composition
        // law so a future refactor that re-inlines the six atomic-arm
        // literals here (and gains its own drift surface separate from
        // the `AtomKind::label` canonical site) surfaces immediately.
        // The pointer-equality check pins the composition produces the
        // SAME `&'static str` (not just a byte-equal copy) for every
        // variant — proof the routing hits ONE static literal site
        // (`SexpShape::label` via `AtomKind::sexp_shape().label()` via
        // `AtomKind::label`'s composition) rather than a parallel inline
        // table on the outer-`Atom` algebra.
        //
        // Sibling-shape pin to
        // `atom_kind_label_routes_through_sexp_shape_label_via_sexp_shape_projection`
        // one algebra layer down (which pins `AtomKind::label`'s routing
        // through `SexpShape::label`) and
        // `sexp_type_name_method_composes_through_shape_label_for_every_outer_shape`
        // one algebra layer up (which pins `Sexp::type_name`'s routing
        // through `Sexp::shape().label()`). The three routing pins jointly
        // enforce the (outer-`Atom` value, canonical label) pairing
        // stays a full four-layer typed composition (`Atom` → `AtomKind`
        // → `SexpShape` → `&'static str`) rather than degrading to a
        // per-layer inline literal table.
        let samples: Vec<Atom> = vec![
            Atom::Symbol("foo".to_owned()),
            Atom::Keyword("kw".to_owned()),
            Atom::Str("hi".to_owned()),
            Atom::Int(0),
            Atom::Int(-7),
            Atom::Int(42),
            Atom::Float(0.0),
            Atom::Float(-1.5),
            Atom::Float(f64::INFINITY),
            Atom::Bool(true),
            Atom::Bool(false),
        ];
        for atom in &samples {
            let via_label = atom.label();
            let via_composition = atom.kind().label();
            assert_eq!(
                via_label, via_composition,
                "Atom::label() must route through self.kind().label() \
                 for {atom:?} — drift here means the lift was reverted \
                 to inline arms",
            );
            assert!(
                std::ptr::eq(via_label.as_ptr(), via_composition.as_ptr()),
                "Atom::label() must return the SAME `&'static str` as \
                 self.kind().label() for {atom:?} — pointer drift \
                 means the lift composes through a parallel literal \
                 table rather than routing into the canonical \
                 AtomKind::label site",
            );
        }
    }

    #[test]
    fn atom_label_agrees_with_sexp_type_name_at_every_atom_arm() {
        // CROSS-ALGEBRA AGREEMENT CONTRACT: for every atomic payload
        // `a`, `a.label() == Sexp::Atom(a.clone()).type_name()`. The
        // agreement is a TYPED CONSEQUENCE of the two typed
        // compositions — `Sexp::Atom(a).type_name()` routes through
        // `Sexp::shape()`'s `Self::Atom(a) => a.kind().sexp_shape()`
        // arm which composes with `SexpShape::label` byte-for-byte
        // with `a.kind().label()` (which itself composes through
        // `AtomKind::sexp_shape().label()`). A regression that drifts
        // either side of the cross-algebra bridge (an outer-`Atom`
        // label re-inlined onto a different literal, an outer-`Sexp`
        // Atom-arm re-routed through a stale shape projection, an
        // `AtomKind::sexp_shape` arm that swaps Int ↔ Float) fails-
        // loudly here rather than as a silent operator-facing
        // diagnostic drift at every consumer that pattern-matches on
        // the outer-`Sexp` label vs the outer-`Atom` label
        // independently.
        //
        // Sibling posture to
        // `atom_kind_label_agrees_with_sexp_shape_label_for_every_atom_arm`
        // one algebra layer down — that pin binds the marker-level
        // vocabulary containment (`AtomKind::label ==
        // AtomKind::sexp_shape().label()`), this pin binds the
        // outer-value-level vocabulary containment (`Atom::label ==
        // Sexp::Atom(_).type_name()`) so the FOUR-layer typed
        // composition on the outer-`Atom` algebra and the FIVE-layer
        // typed composition on the outer-`Sexp` algebra agree at their
        // common atomic-payload arms.
        for atom in [
            Atom::Symbol("foo".to_owned()),
            Atom::Keyword("kw".to_owned()),
            Atom::Str("hi".to_owned()),
            Atom::Int(42),
            Atom::Float(2.5),
            Atom::Bool(true),
            Atom::Bool(false),
        ] {
            let via_atom = atom.label();
            let via_sexp = Sexp::Atom(atom.clone()).type_name();
            assert_eq!(
                via_atom, via_sexp,
                "Atom::label() must agree with Sexp::Atom(_).type_name() \
                 for {atom:?} — cross-algebra label drift at the \
                 atomic-payload arms would fracture the typed diagnostic \
                 vocabulary between the outer-Atom and outer-Sexp \
                 algebras",
            );
            assert!(
                std::ptr::eq(via_atom.as_ptr(), via_sexp.as_ptr()),
                "Atom::label() must return the SAME `&'static str` as \
                 Sexp::Atom(_).type_name() for {atom:?} — pointer drift \
                 means one algebra layer re-inlined the literal rather \
                 than routing into the canonical `SexpShape::label` \
                 site",
            );
        }
    }

    #[test]
    fn atom_sexp_shape_projects_each_variant_to_canonical_outer_shape() {
        // PER-ARM CONTRACT: pin the outer-`Atom` `Self::sexp_shape`
        // projection produces the SIX canonical `SexpShape` variants
        // byte-for-byte across every reachable atomic-payload variant.
        // Pre-lift the outer-`Atom` outer-shape projection had no typed
        // primitive on the value-carrier algebra — a consumer with an
        // `Atom` value in hand wanting the canonical outer-shape had to
        // spell the two-step composition `atom.kind().sexp_shape()` at
        // every callsite, OR go through `Sexp::Atom(atom.clone()).shape()`
        // which wraps and unwraps for no runtime purpose. Post-lift the
        // SIX arms bind at ONE typed projection on the outer-`Atom`
        // algebra that routes through `AtomKind::sexp_shape` — the
        // (Atom variant, SexpShape variant) pairing binds at ONE typed
        // algebra composition spanning THREE typed layers.
        //
        // Sibling-shape pin to
        // `atom_kind_sexp_shape_projects_each_variant_to_canonical_outer_shape`
        // one algebra layer down and `atom_label_projects_each_variant_to_canonical_diagnostic_label`
        // one vocabulary axis over. A regression that drifts ONE arm's
        // mapping (e.g. swapping Int ↔ Float, dropping the `Str →
        // SexpShape::String` boundary rename) fails-loudly at THIS
        // test AND the sibling `AtomKind::sexp_shape` per-arm pin.
        assert_eq!(
            Atom::Symbol("foo".to_owned()).sexp_shape(),
            SexpShape::Symbol
        );
        assert_eq!(
            Atom::Keyword("kw".to_owned()).sexp_shape(),
            SexpShape::Keyword
        );
        assert_eq!(Atom::Str("hi".to_owned()).sexp_shape(), SexpShape::String);
        assert_eq!(Atom::Int(42).sexp_shape(), SexpShape::Int);
        assert_eq!(Atom::Float(1.5).sexp_shape(), SexpShape::Float);
        assert_eq!(Atom::Bool(true).sexp_shape(), SexpShape::Bool);
        assert_eq!(Atom::Bool(false).sexp_shape(), SexpShape::Bool);
    }

    #[test]
    fn atom_sexp_shape_composes_through_kind_sexp_shape_for_every_variant() {
        // COMPOSITION-LAW CONTRACT: `atom.sexp_shape() ==
        // atom.kind().sexp_shape()` for every reachable atomic payload
        // — the outer-`Atom` outer-shape projection is structurally
        // derived through `Self::kind` + `AtomKind::sexp_shape` rather
        // than through a parallel six-arm inline match on the outer-
        // `Atom` algebra. Pin the composition law so a future refactor
        // that re-inlines the six atomic-arm literals here (and gains
        // its own drift surface separate from the `AtomKind::sexp_shape`
        // canonical site) surfaces immediately.
        //
        // `SexpShape` carries the `String`-carrying `Unknown` arm so
        // it can't be `Copy`; the pointer-equality axis
        // `atom_label_composes_through_kind_label_for_every_variant`
        // uses on the `&'static str` axis doesn't apply here. Byte-
        // equality on the `SexpShape` discriminant IS the routing
        // contract this pin binds: a regression that re-inlines the
        // mapping produces byte-equal SexpShape values yet gains its
        // own drift surface at the outer-`Atom` layer separate from
        // the canonical `AtomKind::sexp_shape` site.
        //
        // Sibling-shape pin to
        // `atom_label_composes_through_kind_label_for_every_variant`
        // one vocabulary axis over (the diagnostic-label axis) and
        // `atom_kind_sexp_shape_partition_matches_sexp_shape_atomic_carving`
        // one algebra layer down (which pins `AtomKind::sexp_shape`'s
        // partition-membership against `SexpShape::as_atom_kind`).
        // The three pins jointly enforce the (outer-`Atom` value,
        // outer-shape) pairing stays a full three-layer typed
        // composition (`Atom` → `AtomKind` → `SexpShape`) rather than
        // degrading to a per-layer inline literal table on the
        // outer-`Atom` algebra.
        let samples: Vec<Atom> = vec![
            Atom::Symbol("foo".to_owned()),
            Atom::Symbol(String::new()),
            Atom::Keyword("kw".to_owned()),
            Atom::Keyword(String::new()),
            Atom::Str("hi".to_owned()),
            Atom::Str(String::new()),
            Atom::Int(0),
            Atom::Int(-7),
            Atom::Int(i64::MIN),
            Atom::Int(i64::MAX),
            Atom::Float(0.0),
            Atom::Float(-1.5),
            Atom::Float(f64::INFINITY),
            Atom::Float(f64::from_bits(f64::NAN.to_bits())),
            Atom::Bool(true),
            Atom::Bool(false),
        ];
        for atom in &samples {
            let via_sexp_shape = atom.sexp_shape();
            let via_composition = atom.kind().sexp_shape();
            assert_eq!(
                via_sexp_shape, via_composition,
                "Atom::sexp_shape() must route through self.kind().sexp_shape() \
                 for {atom:?} — drift here means the lift was reverted \
                 to inline arms",
            );
            // Cross-projection agreement: the routed shape's diagnostic
            // label is byte-equal to `atom.label()` (the sibling
            // vocabulary axis' composition), pinning that the two typed
            // projections through `AtomKind` (one via `label`, one via
            // `sexp_shape`) agree at the canonical `SexpShape::label`
            // site.
            assert_eq!(
                via_sexp_shape.label(),
                atom.label(),
                "atom.sexp_shape().label() must agree with atom.label() \
                 for {atom:?} — cross-axis vocabulary drift at the \
                 shape-projection site would fracture the FOUR-layer \
                 diagnostic composition on the outer-Atom algebra",
            );
        }
    }

    #[test]
    fn atom_sexp_shape_agrees_with_sexp_shape_at_every_atom_arm() {
        // CROSS-ALGEBRA AGREEMENT CONTRACT: for every atomic payload
        // `a`, `a.sexp_shape() == Sexp::Atom(a.clone()).shape()`. The
        // agreement is a TYPED CONSEQUENCE of the two typed
        // compositions — `Sexp::Atom(a).shape()` routes through
        // `Sexp::shape()`'s `Self::Atom(a) => a.kind().sexp_shape()`
        // arm which byte-for-byte matches `a.sexp_shape()`'s composition
        // through `Self::kind` + `AtomKind::sexp_shape`. A regression
        // that drifts either side of the cross-algebra bridge (an
        // outer-`Atom` shape re-inlined onto a different projection,
        // an outer-`Sexp` Atom-arm re-routed through a stale kind
        // projection, an `AtomKind::sexp_shape` arm that swaps Int ↔
        // Float) fails-loudly here rather than as a silent operator-
        // facing drift at every consumer that pattern-matches on the
        // outer-`Sexp` shape vs the outer-`Atom` shape independently.
        //
        // Sibling posture to
        // `atom_label_agrees_with_sexp_type_name_at_every_atom_arm`
        // one vocabulary axis over — that pin binds the (outer-`Atom`,
        // outer-`Sexp`) cross-algebra bridge on the diagnostic-label
        // axis, this pin binds it on the outer-shape axis.
        for atom in [
            Atom::Symbol("foo".to_owned()),
            Atom::Keyword("kw".to_owned()),
            Atom::Str("hi".to_owned()),
            Atom::Int(42),
            Atom::Float(2.5),
            Atom::Bool(true),
            Atom::Bool(false),
        ] {
            let via_atom = atom.sexp_shape();
            let via_sexp = Sexp::Atom(atom.clone()).shape();
            assert_eq!(
                via_atom, via_sexp,
                "Atom::sexp_shape() must agree with Sexp::Atom(_).shape() \
                 for {atom:?} — cross-algebra shape drift at the \
                 atomic-payload arms would fracture the typed shape \
                 vocabulary between the outer-Atom and outer-Sexp \
                 algebras",
            );
        }
    }

    #[test]
    fn atom_sexp_shape_round_trips_through_sexp_shape_as_atom_kind() {
        // ROUND-TRIP CONTRACT: for every atomic payload `a`,
        // `a.sexp_shape().as_atom_kind() == Some(a.kind())`. The typed
        // embed `Atom → AtomKind → SexpShape` inverts through the
        // soft-projection retraction `SexpShape → AtomKind` exactly on
        // the 6-of-12 atomic-payload image. A regression that ANY of
        // the three embeds (`Self::kind`, `AtomKind::sexp_shape`) OR
        // the soft-projection retraction `SexpShape::as_atom_kind`
        // drifts on any arm fails-loudly here — the structural
        // round-trip is the invariant that holds the closed-set-
        // lattice's atomic-payload cell load-bearing across future
        // edits.
        //
        // Peer to `unquote_form_sexp_shape_round_trips_through_sexp_shape_as_quote_form_and_as_unquote_form`
        // (error.rs) one carving axis over on the substitution-subset
        // side of the outer-shape lattice, and to `atom_kind_sexp_shape_round_trips_through_sexp_shape_as_atom_kind`
        // one algebra layer down (which pins the marker-level round-
        // trip). This pin extends the round-trip up to the outer-
        // `Atom` value carrier.
        for atom in [
            Atom::Symbol("foo".to_owned()),
            Atom::Keyword("kw".to_owned()),
            Atom::Str("hi".to_owned()),
            Atom::Int(0),
            Atom::Int(i64::MIN),
            Atom::Float(0.0),
            Atom::Float(f64::INFINITY),
            Atom::Bool(true),
            Atom::Bool(false),
        ] {
            let shape = atom.sexp_shape();
            let round_tripped = shape.as_atom_kind();
            assert_eq!(
                round_tripped,
                Some(atom.kind()),
                "Atom::sexp_shape() must round-trip through \
                 SexpShape::as_atom_kind for {atom:?} — the typed embed \
                 Atom → AtomKind → SexpShape is no longer a section of \
                 SexpShape::as_atom_kind's inverse on the atomic \
                 6-of-12 image",
            );
        }
    }

    #[test]
    fn hash_for_atom_preserves_legacy_discriminator_bytes() {
        // CACHE-KEY CONTRACT (Hash side): pin that the lifted
        // `Hash for Atom` impl produces byte-identical hashes for the
        // six atomic variants as the pre-lift implementation. We
        // compute the expected hash via a SECOND hasher that manually
        // drives the pre-lift `<discr>u8.hash(h); <inner>.hash(h)`
        // sequence (with `Float`'s `to_bits()` projection preserved
        // and `String` payloads hashed via `String::hash`), then
        // compare. A regression that drifts the discriminator OR
        // re-orders the (discr, inner) sequence surfaces here as a
        // hash-value mismatch. Sibling posture to
        // `hash_for_sexp_preserves_legacy_quote_family_discriminator_bytes`
        // on the quote-family axis.
        use std::collections::hash_map::DefaultHasher;

        let payload = String::from("payload");

        // Helper: hash the legacy `<discr>u8.hash(h); <inner>` shape
        // through a fresh DefaultHasher and finish.
        let legacy_hash = |atom: &Atom, expected_discr: u8| -> u64 {
            let mut h = DefaultHasher::new();
            expected_discr.hash(&mut h);
            match atom {
                Atom::Symbol(s) | Atom::Keyword(s) | Atom::Str(s) => s.hash(&mut h),
                Atom::Int(n) => n.hash(&mut h),
                Atom::Float(f) => f.to_bits().hash(&mut h),
                Atom::Bool(b) => b.hash(&mut h),
            }
            h.finish()
        };

        // (label, atom, pre-lift discriminator byte)
        let cases: &[(&str, Atom, u8)] = &[
            ("symbol", Atom::Symbol(payload.clone()), 0u8),
            ("keyword", Atom::Keyword(payload.clone()), 1u8),
            ("str", Atom::Str(payload.clone()), 2u8),
            ("int", Atom::Int(42), 3u8),
            ("float", Atom::Float(1.5), 4u8),
            ("bool-true", Atom::Bool(true), 5u8),
            ("bool-false", Atom::Bool(false), 5u8),
        ];

        for (label, atom, expected_discr) in cases {
            let mut via_impl = DefaultHasher::new();
            atom.hash(&mut via_impl);

            let via_legacy = legacy_hash(atom, *expected_discr);

            assert_eq!(
                via_impl.finish(),
                via_legacy,
                "Hash for Atom drifted from legacy \
                 (discr={expected_discr}, inner) sequence at {label}"
            );
        }
    }

    #[test]
    fn atom_hash_discriminator_composes_through_kind_hash_discriminator_for_every_variant() {
        // COMPOSITION-LAW CONTRACT: `atom.hash_discriminator() ==
        // atom.kind().hash_discriminator()` for every reachable atomic
        // payload — the outer-`Atom` cache-key byte projection is
        // structurally derived through `Self::kind` +
        // `AtomKind::hash_discriminator` rather than through a parallel
        // six-arm inline match on the outer-`Atom` algebra. Pin the
        // composition law so a future refactor that re-inlines the six
        // atomic-arm literals here (and gains its own drift surface
        // separate from the `AtomKind::hash_discriminator` canonical
        // site) surfaces immediately.
        //
        // Sibling-shape pin to
        // `atom_label_composes_through_kind_label_for_every_variant`
        // (diagnostic-label axis) and
        // `atom_sexp_shape_composes_through_kind_sexp_shape_for_every_variant`
        // (outer-shape axis) one vocabulary axis over — the three pins
        // jointly enforce the outer-`Atom` algebra closes the (label,
        // sexp_shape, hash_discriminator) trio through the SAME typed
        // marker layer (`Self::kind` into `AtomKind`) rather than
        // degrading to a per-layer inline literal table on the
        // outer-`Atom` algebra. The sweep includes NaN and ±∞ Float
        // payloads (matching `Hash for Atom`'s `f64::to_bits()`
        // posture), both empty and non-empty String/Symbol/Keyword
        // arms, `i64::{MIN, MAX}` on the Int arm, and both Bool arms —
        // exhausting the byte-partition surface at every reachable
        // atomic-payload witness.
        let samples: Vec<Atom> = vec![
            Atom::Symbol("foo".to_owned()),
            Atom::Symbol(String::new()),
            Atom::Keyword("kw".to_owned()),
            Atom::Keyword(String::new()),
            Atom::Str("hi".to_owned()),
            Atom::Str(String::new()),
            Atom::Int(0),
            Atom::Int(-7),
            Atom::Int(42),
            Atom::Int(i64::MIN),
            Atom::Int(i64::MAX),
            Atom::Float(0.0),
            Atom::Float(-1.5),
            Atom::Float(f64::INFINITY),
            Atom::Float(f64::NEG_INFINITY),
            Atom::Float(f64::NAN),
            Atom::Bool(true),
            Atom::Bool(false),
        ];
        for atom in &samples {
            let via_outer = atom.hash_discriminator();
            let via_composition = atom.kind().hash_discriminator();
            assert_eq!(
                via_outer, via_composition,
                "Atom::hash_discriminator() must route through \
                 self.kind().hash_discriminator() for {atom:?} — drift \
                 here means the lift was reverted to inline arms and \
                 the outer-`Atom` cache-key algebra fractured from the \
                 canonical AtomKind::hash_discriminator site",
            );
        }
    }

    #[test]
    fn hash_for_atom_routes_atom_discriminator_through_atom_hash_discriminator() {
        // ROUTING-LAW CONTRACT: pin the outer-`Atom` routing IDENTITY —
        // for every reachable atomic payload, `Hash for Atom` produces
        // byte-identical output to a hand-driven
        // `atom.hash_discriminator().hash(h); <inner-payload-hash>`
        // sequence. Binds the composition IDENTITY (not just value
        // equality) between the outer Hash body and the typed algebra
        // method — a regression that re-inlines the two-hop
        // `self.kind().hash_discriminator()` chain at the outer arm
        // still drifts detectably if the future
        // `Atom::hash_discriminator` composes through a different site.
        // Sibling posture to
        // `hash_for_sexp_routes_outer_discriminator_through_sexp_hash_discriminator`
        // — that pin binds the `Hash for Sexp` body against the
        // outer-`Sexp` cache-key method; this pin binds the
        // `Hash for Atom` body against the outer-`Atom` cache-key
        // method. Together the two routing pins enforce the outer-value
        // Hash bodies at BOTH algebras stay structurally parallel
        // (`self.hash_discriminator().hash(h); <inner>`).
        use std::collections::hash_map::DefaultHasher;
        let seeds: Vec<(&str, Atom)> = vec![
            ("symbol", Atom::Symbol("s".to_owned())),
            ("symbol-empty", Atom::Symbol(String::new())),
            ("keyword", Atom::Keyword("kw".to_owned())),
            ("str", Atom::Str("hi".to_owned())),
            ("int-zero", Atom::Int(0)),
            ("int-min", Atom::Int(i64::MIN)),
            ("int-max", Atom::Int(i64::MAX)),
            ("float", Atom::Float(2.5)),
            ("float-nan", Atom::Float(f64::NAN)),
            ("float-inf", Atom::Float(f64::INFINITY)),
            ("bool-true", Atom::Bool(true)),
            ("bool-false", Atom::Bool(false)),
        ];
        for (label, atom) in &seeds {
            let mut via_impl = DefaultHasher::new();
            atom.hash(&mut via_impl);

            let mut via_lifted = DefaultHasher::new();
            atom.hash_discriminator().hash(&mut via_lifted);
            match atom {
                Atom::Symbol(s) | Atom::Keyword(s) | Atom::Str(s) => s.hash(&mut via_lifted),
                Atom::Int(n) => n.hash(&mut via_lifted),
                Atom::Float(f) => f.to_bits().hash(&mut via_lifted),
                Atom::Bool(b) => b.hash(&mut via_lifted),
            }

            assert_eq!(
                via_impl.finish(),
                via_lifted.finish(),
                "Hash for Atom drifted from routed-through-hash_discriminator sequence at {label}"
            );
        }
    }

    #[test]
    fn atom_kind_composes_with_domain_sexp_shape_for_every_atomic_arm() {
        // PATH-UNIFORMITY / COMPOSITION-LAW CONTRACT: the substrate's
        // outer-shape projection `domain::sexp_shape` now routes the
        // six atomic arms through `Atom::kind` + `AtomKind::sexp_shape`.
        // Pin that the composed projection produces the SAME
        // `SexpShape` variant that the pre-lift inline six-arm match
        // produced for every `Atom` payload. A regression that drifts
        // ONE arm of either `Atom::kind` (e.g. routes `Atom::Int(_)`
        // through `AtomKind::Float`) or `AtomKind::sexp_shape` (e.g.
        // routes `AtomKind::Symbol` through `SexpShape::Keyword`)
        // surfaces as an immediate inequality between
        // `domain::sexp_shape(&Sexp::Atom(a))` and
        // `a.kind().sexp_shape()` — and since both projections are
        // load-bearing for the diagnostic surface, the test pins both
        // sides of the typed algebra at once. Sibling posture to
        // `quote_form_sexp_shape_paired_with_as_quote_form_preserves_
        // pre_lift_pairing_for_every_sexp` on the quote-family axis.
        let cases: &[(Atom, SexpShape)] = &[
            (Atom::Symbol("x".into()), SexpShape::Symbol),
            (Atom::Keyword("k".into()), SexpShape::Keyword),
            (Atom::Str("s".into()), SexpShape::String),
            (Atom::Int(7), SexpShape::Int),
            (Atom::Float(2.5), SexpShape::Float),
            (Atom::Bool(true), SexpShape::Bool),
        ];
        for (atom, expected_shape) in cases {
            let via_composed = atom.kind().sexp_shape();
            assert_eq!(
                via_composed, *expected_shape,
                "Atom::kind().sexp_shape() drifted for {atom:?}"
            );
            // Cross-projection identity with the public
            // `domain::sexp_shape` projection — pins that the lifted
            // arm routes through `AtomKind` exactly as the inline
            // arms did pre-lift.
            let via_domain = crate::domain::sexp_shape(&Sexp::Atom(atom.clone()));
            assert_eq!(
                via_domain, via_composed,
                "domain::sexp_shape vs Atom::kind().sexp_shape() drift for {atom:?}"
            );
        }
    }

    #[test]
    fn atom_display_renders_each_variant_to_canonical_form() {
        // CANONICAL-RENDERING CONTRACT: pin that the lifted
        // `fmt::Display for Atom` impl produces byte-identical
        // canonical output for the seven atomic variant cases
        // (Bool splits into true/false) as the pre-lift inline
        // sub-arms inside `Display for Sexp`'s atom arm. Sibling-arm
        // sweep so the seven pairings stay load-bearing under
        // reordering refactors. A regression that drifts the Bool
        // spelling (`#t`/`#f` vs Rust's `true`/`false`) — the
        // CLAUDE.md-pinned reader-round-trip invariant — fails
        // loudly here. Direct sibling to `atom_kind_label_renders_
        // canonical_string_for_every_variant` on the diagnostic-
        // label axis: this pins the rendered SOURCE (`#t`), that pins
        // the rendered LABEL (`bool`); the two projections share the
        // closed-set `AtomKind` algebra but render to distinct
        // surfaces (source vs diagnostic vocabulary).
        let cases: &[(Atom, &str)] = &[
            (Atom::Symbol("foo".into()), "foo"),
            (Atom::Keyword("k".into()), ":k"),
            (Atom::Str("hello".into()), "\"hello\""),
            (Atom::Int(42), "42"),
            (Atom::Int(-7), "-7"),
            (Atom::Float(1.5), "1.5"),
            (Atom::Bool(true), "#t"),
            (Atom::Bool(false), "#f"),
        ];
        for (atom, expected) in cases {
            assert_eq!(
                atom.to_string(),
                *expected,
                "Atom::Display drifted from canonical rendering for {atom:?}"
            );
        }
    }

    #[test]
    fn atom_display_renders_integral_float_with_dot_zero_suffix() {
        // ROUND-TRIP-INVARIANT PIN: `fmt_float`'s `.0`-suffix
        // discipline composes through `Atom::Display` — `Float(1.0)`
        // renders as `"1.0"`, NOT `"1"` (which the reader would
        // re-parse as `Atom::Int(1)`, silently coercing the typed
        // `Float` track into the `Int` track at the Display→read
        // boundary). Direct sibling pin to the existing Display-for-
        // Sexp round-trip tests that exercise the same invariant
        // through the `Sexp::Atom` outer wrap. Lifting the rendering
        // onto the typed `Atom` algebra surfaces a future regression
        // (e.g. an Atom::Display arm that bypasses `fmt_float` and
        // formats `f64` directly) at the atom layer without
        // requiring a Sexp wrap to reproduce.
        assert_eq!(Atom::Float(1.0).to_string(), "1.0");
        assert_eq!(Atom::Float(-42.0).to_string(), "-42.0");
        assert_eq!(Atom::Float(0.99).to_string(), "0.99");
    }

    #[test]
    fn sexp_atom_display_arm_routes_through_atom_display_for_every_variant() {
        // LIFTED-BOUNDARY CONTRACT: pin that `Sexp::Atom(a).to_string()
        // == a.to_string()` for every atomic payload variant. Pre-
        // lift the per-variant body lived inline at the `Sexp::Atom(a)
        // => match a { … }` arm of `Display for Sexp`; post-lift the
        // outer arm delegates to `fmt::Display::fmt(a, f)`. A
        // regression that drifts the outer arm (e.g. wraps the atom
        // rendering in parens, or routes Symbol through a Sexp-
        // specific arm before delegating) surfaces as an inequality
        // here. The cases sweep all six `Atom` variants (Bool unified
        // — both true/false agree under the impl). Sibling posture
        // to the quote-family routing test
        // `sexp_to_json_routes_quote_family_arms_through_as_quote_form_typed_marker`
        // that pins the analogous `Sexp` outer arm routing through
        // a typed algebra projection.
        let cases: &[Atom] = &[
            Atom::Symbol("name".into()),
            Atom::Keyword("kw".into()),
            Atom::Str("body".into()),
            Atom::Int(7),
            Atom::Float(2.5),
            Atom::Float(1.0),
            Atom::Bool(true),
            Atom::Bool(false),
        ];
        for atom in cases {
            let via_sexp = Sexp::Atom(atom.clone()).to_string();
            let via_atom = atom.to_string();
            assert_eq!(
                via_sexp, via_atom,
                "Sexp::Atom Display arm drifted from Atom::Display for {atom:?}"
            );
        }
    }

    #[test]
    fn atom_display_round_trips_through_reader_preserving_typed_identity() {
        // BIDIRECTIONAL TYPED-IDENTITY CONTRACT: render an atom via
        // `Atom::Display`, parse the rendering through
        // `crate::reader::read`, and pin that the parsed value's
        // outer shape is `Sexp::Atom(_)` carrying the SAME variant
        // discriminator as the seed (via `Atom::kind`) AND that the
        // payload round-trips bit-for-bit. This is the typed-exit /
        // typed-entry mirror at the atomic-payload boundary — the
        // load-bearing invariant the `fmt_float` `.0`-suffix
        // discipline already exists to preserve. A regression that
        // drifts ONE side (Display arm OR reader arm) corrupts the
        // round-trip; pin it at the typed boundary directly. Sibling
        // posture to the existing Sexp-layer round-trip tests:
        // `float_display_round_trips_through_reader_into_typed_float`,
        // `quote_prefix_round_trips_through_read_quoted_into_sexp_quote`.
        let cases: &[Atom] = &[
            Atom::Symbol("foo-bar".into()),
            Atom::Keyword("kw".into()),
            Atom::Int(42),
            Atom::Int(-7),
            Atom::Int(0),
            Atom::Float(1.0),
            Atom::Float(1.5),
            Atom::Float(-42.0),
            Atom::Bool(true),
            Atom::Bool(false),
        ];
        for seed in cases {
            let rendered = seed.to_string();
            let mut parsed = crate::reader::read(&rendered)
                .unwrap_or_else(|e| panic!("reader rejected {rendered:?} for {seed:?}: {e}"));
            assert_eq!(
                parsed.len(),
                1,
                "rendered {rendered:?} for {seed:?} re-read as != 1 form"
            );
            let Sexp::Atom(round_tripped) = parsed.remove(0) else {
                panic!("rendered {rendered:?} for {seed:?} re-read as non-Atom");
            };
            assert_eq!(
                round_tripped.kind(),
                seed.kind(),
                "Atom::Display→reader drifted variant for {seed:?} via {rendered:?}"
            );
            assert_eq!(
                round_tripped, *seed,
                "Atom::Display→reader drifted payload for {seed:?} via {rendered:?}"
            );
        }
    }

    #[test]
    fn atom_to_json_projects_each_variant_to_canonical_json_value() {
        // CANONICAL-MAPPING CONTRACT: pin that `Atom::to_json` produces
        // byte-identical `serde_json::Value` outputs for each
        // `AtomKind` variant as the pre-lift inline arms inside
        // `crate::domain::sexp_to_json` did. Sweeps a representative
        // atom of each variant so a regression that drifts ONE arm
        // (e.g. swaps `Symbol`'s mapping to a Number, or drops
        // `Keyword`'s `:` prefix that `json_to_sexp`'s inverse strips
        // — silently breaking every `:values-overlay` payload pinned
        // by the CLAUDE.md bool warning) fails loudly. Sibling-arm
        // sweep to `atom_display_renders_each_variant_to_canonical_form`
        // — both pin the typed-algebra rendering of the atomic
        // payload at its canonical projection. The float case uses
        // `1.5` (finite) here; NaN / ±∞ get their own pin below.
        use serde_json::Value as JValue;
        assert_eq!(
            Atom::Symbol("name".into()).to_json(),
            JValue::String("name".into()),
        );
        assert_eq!(
            Atom::Keyword("parent".into()).to_json(),
            JValue::String(":parent".into()),
        );
        assert_eq!(
            Atom::Str("body".into()).to_json(),
            JValue::String("body".into()),
        );
        assert_eq!(Atom::Int(42).to_json(), JValue::Number(42i64.into()));
        assert_eq!(Atom::Int(-7).to_json(), JValue::Number((-7i64).into()));
        assert_eq!(
            Atom::Float(1.5).to_json(),
            JValue::Number(serde_json::Number::from_f64(1.5).unwrap()),
        );
        assert_eq!(Atom::Bool(true).to_json(), JValue::Bool(true));
        assert_eq!(Atom::Bool(false).to_json(), JValue::Bool(false));
    }

    #[test]
    fn atom_from_json_number_int_arm_projects_i64_backed_numbers_to_atom_int() {
        // TYPED-INVERSE CONTRACT (Int arm): pin that `Atom::from_json_number`
        // decodes every `serde_json::Number` whose `.as_i64()` returns
        // `Some(i)` to `Atom::Int(i)`. Sweeps every i64-boundary value
        // the substrate pinned in the sibling `Atom::to_json` sweep
        // (0, ±1, ±42, i64::MAX, i64::MIN) plus a representative
        // interior sample; the sweep pins that the `as_i64()` arm
        // fires eagerly BEFORE the `as_f64()` arm, so an
        // integer-valued `Number` never sinks to `Atom::Float` at the
        // atomic-algebra boundary. A regression that drifts the arm
        // (e.g. swaps the `as_i64` / `as_f64` order) fails at the
        // `i64::MAX` / `i64::MIN` boundary samples because those two
        // values exceed `f64`'s 53-bit mantissa and would silently
        // round through the `as_f64` sink.
        for i in [0i64, 1, -1, 42, -7, i64::MAX, i64::MIN] {
            let n: serde_json::Number = i.into();
            assert_eq!(
                Atom::from_json_number(&n),
                Atom::Int(i),
                "Atom::from_json_number drifted Int arm for i64 sample {i}",
            );
        }
    }

    #[test]
    fn atom_from_json_number_float_arm_projects_finite_non_integer_f64_backed_numbers_to_atom_float(
    ) {
        // TYPED-INVERSE CONTRACT (Float arm): pin that
        // `Atom::from_json_number` decodes every `serde_json::Number`
        // whose `.as_i64()` returns `None` but `.as_f64()` returns
        // `Some(f)` to `Atom::Float(f)`. Sweeps a representative set of
        // finite non-integer-valued f64 samples the substrate pinned
        // in the sibling `Atom::to_json` sweep (1.5, -2.5, positive
        // and negative fractional values, subnormal, `f64::MIN_POSITIVE`).
        // Every sample is constructed via `serde_json::Number::from_f64`
        // which the standard library documents as f64-backed
        // (`.as_i64()` returns `None`, `.as_f64()` returns
        // `Some(input)`) so the Float arm fires deterministically.
        // A regression that drifts the arm (e.g. drops the `as_f64`
        // sink entirely and falls through to the `Int(0)` typed floor)
        // fails HERE at the fractional-value assertions with an
        // `Int(0)` mismatch.
        for f in [
            1.5f64,
            -2.5,
            0.1,
            -0.1,
            f64::MIN_POSITIVE,
            1.234_567_890_123,
        ] {
            let n = serde_json::Number::from_f64(f)
                .unwrap_or_else(|| panic!("Number::from_f64({f}) must accept finite float"));
            assert_eq!(
                Atom::from_json_number(&n),
                Atom::Float(f),
                "Atom::from_json_number drifted Float arm for f64 sample {f}",
            );
        }
    }

    #[test]
    fn atom_from_json_number_round_trips_atom_to_json_int_arm() {
        // ROUND-TRIP LAW (Int axis): pin the paired-projection identity
        // `Atom::from_json_number(&<Atom::Int(i).to_json() as Number>)
        // == Atom::Int(i)` for every i64 boundary sample. The pair
        // `Atom::to_json` (forward) + `Atom::from_json_number` (inverse)
        // now lives on the SAME closed-set [`Atom`] algebra — this
        // pin proves the closure at ONE algebra layer without a
        // `Sexp::from_json` intermediary. A regression that drifts
        // either side of the pair (e.g. `Atom::to_json` emits `Int(n)`
        // as a JSON string, or `Atom::from_json_number` inverts the
        // `as_i64` / `as_f64` cascade order) surfaces here at the
        // boundary-value mismatch. Sibling-shape pin to
        // `atom_display_round_trips_through_reader_preserving_typed_identity`
        // — where that pin closes the `Atom → Display → reader → Atom`
        // round-trip on the Display axis, THIS pin closes the
        // `Atom::Int → to_json → Number → from_json_number → Atom::Int`
        // round-trip on the JSON numeric axis, both on the SAME [`Atom`]
        // algebra.
        for i in [0i64, 1, -1, 42, -7, i64::MAX, i64::MIN] {
            let atom_before = Atom::Int(i);
            let via_forward = atom_before.to_json();
            let n = match via_forward {
                serde_json::Value::Number(n) => n,
                other => {
                    panic!("Atom::Int({i}).to_json() must project to JValue::Number, got {other:?}",)
                }
            };
            assert_eq!(
                Atom::from_json_number(&n),
                atom_before,
                "Atom::Int({i}) round-trip through to_json + from_json_number drifted",
            );
        }
    }

    #[test]
    fn atom_from_json_number_round_trips_atom_to_json_float_arm_for_non_integer_finite_samples() {
        // ROUND-TRIP LAW (Float axis, non-integer subset): pin the
        // paired-projection identity `Atom::from_json_number(&<Atom::Float(f)
        // .to_json() as Number>) == Atom::Float(f)` for every finite
        // non-integer f64 sample. The non-integer restriction is
        // load-bearing: `serde_json::Number::from_f64` on an
        // integer-valued f64 like `1.0` produces a Number whose
        // `.as_i64()` may return `Some(1)` (the exact behavior depends
        // on `serde_json`'s internal representation of the JSON
        // number tower — integer-valued floats can round-trip through
        // the `as_i64` arm, sinking to `Atom::Int(1)` instead of
        // `Atom::Float(1.0)`). The three-way (`Symbol` / `Keyword` /
        // `Str`) collapse on the string side of `Sexp::from_json`'s
        // docstring is one axis; THIS pin covers the (`Int` / `Float`)
        // collapse on the numeric side for the round-trippable subset
        // (non-integer-valued finite floats). Together with the Int
        // round-trip pin above the two floors close the numeric-axis
        // round-trip closure at the algebra layer. NaN / ±∞ are
        // pinned separately at `atom_to_json_float_nan_and_infinity_collapse_to_null`
        // — those don't produce a `Number` from `to_json` so the
        // round-trip law does NOT apply to them.
        for f in [
            1.5f64,
            -2.5,
            0.1,
            -0.1,
            f64::MIN_POSITIVE,
            1.234_567_890_123,
        ] {
            let atom_before = Atom::Float(f);
            let via_forward = atom_before.to_json();
            let n = match via_forward {
                serde_json::Value::Number(n) => n,
                other => panic!(
                    "Atom::Float({f}).to_json() must project to JValue::Number, got {other:?}",
                ),
            };
            assert_eq!(
                Atom::from_json_number(&n),
                atom_before,
                "Atom::Float({f}) round-trip through to_json + from_json_number drifted",
            );
        }
    }

    #[test]
    fn atom_to_json_float_nan_and_infinity_collapse_to_null() {
        // JSON-INEXPRESSIBILITY PIN: JSON has no canonical form for
        // `NaN` / `±∞` — `serde_json::Number::from_f64` returns `None`
        // for those values, and the substrate's pre-lift behavior at
        // `sexp_to_json` mapped them to `JValue::Null` via
        // `unwrap_or(JValue::Null)`. Pin the special-case branch at
        // the typed-algebra boundary directly so a future refactor
        // that bypasses `serde_json::Number::from_f64` (e.g. emits
        // `NaN` as the string `"NaN"`, which the JSON deserializer
        // would silently re-read as a String at the round-trip
        // boundary) surfaces at this test without requiring a Sexp
        // wrap to reproduce. Sibling-shape pin to
        // `atom_display_renders_integral_float_with_dot_zero_suffix`
        // — both pin a non-default branch of the float projection's
        // canonical rendering. The branch IS load-bearing for the
        // `sexp_to_json` → `serde_json::from_value::<T>` bridge the
        // derive-macro fallthrough uses: a downstream `f64` field
        // that the operator wrote `:rate :nan` for collapses to
        // `JValue::Null` HERE rather than at the serde boundary,
        // emitting a clean structural diagnostic instead of a JSON
        // parse error miles downstream.
        use serde_json::Value as JValue;
        assert_eq!(Atom::Float(f64::NAN).to_json(), JValue::Null);
        assert_eq!(Atom::Float(f64::INFINITY).to_json(), JValue::Null);
        assert_eq!(Atom::Float(f64::NEG_INFINITY).to_json(), JValue::Null);
    }

    #[test]
    fn atom_from_lexeme_classifies_each_atom_kind_for_canonical_lexeme() {
        // CANONICAL-CLASSIFICATION CONTRACT: pin that `Atom::from_lexeme`
        // produces byte-identical typed `Atom` outputs for a canonical
        // lexeme of each `AtomKind` variant against the pre-lift
        // `crate::reader::atom_from_str` cascade. Sweeps a representative
        // lexeme of each variant so a regression that drifts ONE arm
        // (e.g. swaps `"#t"` to `Atom::Symbol("#t")` silently breaking
        // every `:values-overlay` payload pinned by the CLAUDE.md bool
        // warning, or strips `":kw"`'s prefix when classifying to
        // `Atom::Symbol` rather than `Atom::Keyword`) fails loudly.
        // Sibling-arm sweep to
        // `atom_display_renders_each_variant_to_canonical_form` and
        // `atom_to_json_projects_each_variant_to_canonical_json_value` —
        // all three pin the typed-algebra at its canonical per-variant
        // projection. This is the typed-ENTRY side of the bidirectional
        // sweep; those are the typed-EXIT sides.
        //
        // `Atom::Str` is intentionally absent — `Atom::from_lexeme`'s
        // typed-entry surface processes BARE reader-token lexemes, and
        // string literals take the reader's `"`-quoted tokenizer branch
        // (a `Token::Str(_)`, NOT a `Token::Atom(_)`). The reader's
        // string round-trip is pinned by `string_escapes` in
        // `crate::reader::tests`.
        assert_eq!(Atom::from_lexeme("foo"), Atom::Symbol("foo".into()));
        assert_eq!(
            Atom::from_lexeme("defpoint"),
            Atom::Symbol("defpoint".into())
        );
        assert_eq!(Atom::from_lexeme("seph.1"), Atom::Symbol("seph.1".into()));
        assert_eq!(Atom::from_lexeme(":parent"), Atom::Keyword("parent".into()));
        assert_eq!(Atom::from_lexeme(":kw"), Atom::Keyword("kw".into()));
        assert_eq!(Atom::from_lexeme("42"), Atom::Int(42));
        assert_eq!(Atom::from_lexeme("-7"), Atom::Int(-7));
        assert_eq!(Atom::from_lexeme("0"), Atom::Int(0));
        assert_eq!(Atom::from_lexeme("1.5"), Atom::Float(1.5));
        assert_eq!(Atom::from_lexeme("-2.5"), Atom::Float(-2.5));
        assert_eq!(Atom::from_lexeme("#t"), Atom::Bool(true));
        assert_eq!(Atom::from_lexeme("#f"), Atom::Bool(false));
    }

    #[test]
    fn atom_from_lexeme_prefers_int_over_float_for_integer_lexeme() {
        // LOAD-BEARING DISPATCH-ORDERING PIN: `Atom::from_lexeme` tries
        // `i64::from_str` BEFORE `f64::from_str` so a bare `"1"`
        // classifies as `Atom::Int(1)`, NOT `Atom::Float(1.0)`. The
        // typed-int-vs-typed-float distinction at the typed-entry
        // boundary is the dual of `fmt_float`'s `.0`-suffix discipline
        // on the typed-exit side — together the two projections form
        // the round-trip identity `from_lexeme(a.to_string()) == a`
        // for both `Int(_)` and `Float(_)` payloads pinned by
        // `atom_from_lexeme_round_trips_with_atom_display_for_every_non_str_variant`
        // below. A regression that reorders the parse-cascade (e.g.
        // tries `f64::from_str` first, or unifies both via
        // `f64::from_str` alone since `f64` parse accepts integer
        // lexemes too) silently demotes every integer authoring slot
        // into the float track at the reader, corrupting every
        // downstream `i64` field's serde round-trip without a
        // structural error to point to.
        assert_eq!(Atom::from_lexeme("1"), Atom::Int(1));
        assert_eq!(Atom::from_lexeme("0"), Atom::Int(0));
        assert_eq!(Atom::from_lexeme("-100"), Atom::Int(-100));
        // The bare-int lexeme MUST NOT classify to `Atom::Float`.
        assert_ne!(Atom::from_lexeme("1"), Atom::Float(1.0));
        // Float lexemes (with explicit `.` or scientific notation)
        // route through the f64 arm — pin the cascade's fallthrough
        // ordering so the int-shortcut doesn't swallow them.
        assert_eq!(Atom::from_lexeme("1.0"), Atom::Float(1.0));
        assert_eq!(Atom::from_lexeme("1.5"), Atom::Float(1.5));
        assert_eq!(Atom::from_lexeme("1e3"), Atom::Float(1e3));
    }

    #[test]
    fn atom_from_lexeme_routes_unknown_lexeme_to_symbol_default() {
        // CLOSED-SET DEFAULT-ARM PIN: every lexeme that didn't match a
        // structural prefix (`"#t"`/`"#f"` for Bool, `":"` prefix for
        // Keyword) or parse as a number (`i64` then `f64`) classifies
        // to `Atom::Symbol(_)` by default — the closed-set fallthrough
        // arm the reader has shipped with from inception. Pin the
        // default-arm projection so a future refactor that adds a new
        // structural prefix (e.g. `"#["` for vector literals, `"#\\x"`
        // for char literals) without updating the default-arm wording
        // cannot silently drift previously-Symbol lexemes into a new
        // bucket — the regression surfaces at this test, which sweeps
        // the structural-prefix non-matches every closed-set extension
        // must continue to classify as Symbol unless the extension
        // explicitly claims them. Sibling-shape pin to
        // `atom_from_lexeme_classifies_each_atom_kind_for_canonical_lexeme`
        // — that pins the structural-prefix MATCHES, this pins the
        // structural-prefix NON-MATCHES.
        //
        // The CLAUDE.md-pinned `true`/`false` round-trip discipline
        // also rides this default arm: bare `true`/`false` re-read as
        // `Atom::Symbol("true")` / `Atom::Symbol("false")` because the
        // Scheme bool spellings are `"#t"`/`"#f"`. The pin guards the
        // `serde_json::Value::Bool` field round-trip every
        // `:values-overlay` payload depends on.
        assert_eq!(Atom::from_lexeme("foo"), Atom::Symbol("foo".into()));
        assert_eq!(
            Atom::from_lexeme("defpoint"),
            Atom::Symbol("defpoint".into())
        );
        // The CLAUDE.md `true`/`false` warning — these lexemes MUST
        // route through the default Symbol arm, NOT through the Bool
        // arm. A regression that adds `"true"`/`"false"` recognition
        // silently flips every `:values-overlay` Bool field to the
        // wrong serde shape.
        assert_eq!(Atom::from_lexeme("true"), Atom::Symbol("true".into()));
        assert_eq!(Atom::from_lexeme("false"), Atom::Symbol("false".into()));
        // Non-structural-prefix shapes — pin a sampling so the
        // default arm continues to absorb every shape the prefix
        // arms haven't claimed.
        assert_eq!(Atom::from_lexeme("seph.1"), Atom::Symbol("seph.1".into()));
        assert_eq!(Atom::from_lexeme("a-b"), Atom::Symbol("a-b".into()));
        assert_eq!(Atom::from_lexeme("+"), Atom::Symbol("+".into()));
    }

    #[test]
    fn atom_from_lexeme_round_trips_with_atom_display_for_every_non_str_variant() {
        // BIDIRECTIONAL TYPED-IDENTITY CONTRACT: render each `Atom`
        // (excluding `Atom::Str` — see below) via `fmt::Display`, parse
        // the rendering through `Atom::from_lexeme`, and pin that the
        // round-trip preserves the typed identity exactly. This is the
        // typed-exit / typed-entry mirror at the atomic-payload
        // boundary AT THE ALGEBRA LEVEL — sibling-shape pin to
        // `atom_display_round_trips_through_reader_preserving_typed_identity`
        // which exercises the same round-trip through the full reader.
        // Lifting the typed-entry surface onto `Atom::from_lexeme`
        // means the round-trip law now lives at the algebra rather
        // than at the reader's free-function boundary — a future
        // tool that wants to round-trip an `Atom` through its
        // canonical lexeme spelling (LSP token-completion, REPL
        // pretty-printer, structural editor) binds to `from_lexeme` +
        // `Display` directly without crossing through the reader's
        // tokenizer.
        //
        // `Atom::Str` is intentionally absent — `Display for Atom`
        // renders `Str(s)` as `"{s:?}"` (debug-quoted, with quote
        // marks around the content). The quoted form is NOT a bare
        // reader-token lexeme: it's a `Token::Str(_)` to the
        // tokenizer, taking a distinct branch. The Str round-trip
        // through the FULL reader is pinned by `string_escapes` in
        // `crate::reader::tests`.
        let cases: &[Atom] = &[
            Atom::Symbol("foo-bar".into()),
            Atom::Symbol("defpoint".into()),
            Atom::Symbol("seph.1".into()),
            Atom::Keyword("parent".into()),
            Atom::Keyword("kw".into()),
            Atom::Int(0),
            Atom::Int(42),
            Atom::Int(-7),
            Atom::Float(1.0),
            Atom::Float(1.5),
            Atom::Float(-42.0),
            Atom::Bool(true),
            Atom::Bool(false),
        ];
        for seed in cases {
            let rendered = seed.to_string();
            let round_tripped = Atom::from_lexeme(&rendered);
            assert_eq!(
                round_tripped.kind(),
                seed.kind(),
                "Atom::from_lexeme∘Display drifted variant for {seed:?} via {rendered:?}"
            );
            assert_eq!(
                round_tripped, *seed,
                "Atom::from_lexeme∘Display drifted payload for {seed:?} via {rendered:?}"
            );
        }
    }

    // ── Atom::as_X soft-projection family + Sexp::as_atom structural lift ──
    //
    // The six per-variant soft-projection methods on the typed `Atom` algebra
    // (`as_symbol` / `as_keyword` / `as_string` / `as_int` / `as_float` /
    // `as_bool`) lift the inline `Self::Atom(Atom::X(s)) => Some(s)` arms
    // that previously lived at the six `Sexp::as_X` consumer sites onto ONE
    // method per closed-set arm. The `Sexp::as_atom` structural lift gives
    // the consumer family a uniform two-step composition `as_atom().and_then
    // (Atom::as_X)`. The tests below pin:
    //
    //   (1) per-variant typed projection — `Atom::as_X` returns `Some(payload)`
    //       iff the variant matches AND `None` for every other closed-set arm
    //       (path-uniformity over `AtomKind::ALL`);
    //   (2) the `Sexp::as_atom` projection — `Some(&Atom)` iff `Sexp::Atom(_)`
    //       AND `None` for the structural shapes (`Nil` / `List` /
    //       `Quote` / `Quasiquote` / `Unquote` / `UnquoteSplice`);
    //   (3) lifted-boundary composition — `Sexp::as_<X>(s) == s.as_atom()
    //       .and_then(Atom::as_<X>)` for every atomic variant, AND the
    //       `Sexp::as_float` widening specialization (`Atom::Int(n)` →
    //       `Some(n as f64)`) lives at the consumer layer, NOT the algebra
    //       layer (per the typed-identity discipline pinned at
    //       `Atom::as_int`'s docstring).

    #[test]
    fn atom_as_symbol_returns_payload_iff_symbol_variant() {
        // PER-VARIANT PROJECTION CONTRACT: `Atom::as_symbol` projects
        // `Atom::Symbol(s)` to `Some(&s)` and every other `AtomKind`
        // variant to `None`. Sweeps `AtomKind::ALL` for the path-
        // uniformity guard — catches a regression that mis-routes ONE
        // arm (e.g. accepts `Atom::Keyword(s)` thinking it's "also a
        // symbol-like identifier", or rejects `Atom::Symbol("foo")` if
        // a future closed-set sweep accidentally narrows the projection
        // by an `s.is_empty()` filter).
        assert_eq!(Atom::Symbol("foo".into()).as_symbol(), Some("foo"));
        assert_eq!(Atom::Symbol("seph.1".into()).as_symbol(), Some("seph.1"));
        assert_eq!(Atom::Symbol(String::new()).as_symbol(), Some(""));
        for kind in AtomKind::ALL {
            if kind == AtomKind::Symbol {
                continue;
            }
            let probe: Atom = match kind {
                AtomKind::Symbol => unreachable!(),
                AtomKind::Keyword => Atom::Keyword("kw".into()),
                AtomKind::Str => Atom::Str("body".into()),
                AtomKind::Int => Atom::Int(42),
                AtomKind::Float => Atom::Float(1.5),
                AtomKind::Bool => Atom::Bool(true),
            };
            assert_eq!(
                probe.as_symbol(),
                None,
                "Atom::as_symbol must reject non-Symbol variant {kind:?}",
            );
        }
    }

    #[test]
    fn atom_as_keyword_returns_payload_iff_keyword_variant() {
        // PER-VARIANT PROJECTION CONTRACT: `Atom::as_keyword` projects
        // `Atom::Keyword(s)` to `Some(&s)` and every other `AtomKind`
        // variant to `None`. The returned `&str` is the BARE identifier
        // (the `:` prefix was already stripped at the typed-ENTRY
        // classifier boundary, `Atom::from_lexeme`); this projection
        // does not re-add or re-strip the prefix — pinned by the empty
        // probe to catch a regression that accidentally trims a leading
        // char.
        assert_eq!(Atom::Keyword("parent".into()).as_keyword(), Some("parent"));
        assert_eq!(Atom::Keyword(String::new()).as_keyword(), Some(""));
        for kind in AtomKind::ALL {
            if kind == AtomKind::Keyword {
                continue;
            }
            let probe: Atom = match kind {
                AtomKind::Symbol => Atom::Symbol("foo".into()),
                AtomKind::Keyword => unreachable!(),
                AtomKind::Str => Atom::Str("body".into()),
                AtomKind::Int => Atom::Int(42),
                AtomKind::Float => Atom::Float(1.5),
                AtomKind::Bool => Atom::Bool(true),
            };
            assert_eq!(
                probe.as_keyword(),
                None,
                "Atom::as_keyword must reject non-Keyword variant {kind:?}",
            );
        }
    }

    #[test]
    fn atom_as_string_returns_payload_iff_str_variant() {
        // PER-VARIANT PROJECTION CONTRACT: `Atom::as_string` projects
        // `Atom::Str(s)` to `Some(&s)` and every other `AtomKind`
        // variant (including `Symbol` and `Keyword`, which also carry
        // `String` payloads) to `None`. The closed-set discriminator is
        // load-bearing: a `Symbol("foo")` MUST NOT route through this
        // projection — a regression that conflates the three string-
        // carrying variants would silently re-classify operator-position
        // symbols as string-typed kwarg values at every `extract_string`
        // boundary.
        assert_eq!(Atom::Str("body".into()).as_string(), Some("body"));
        assert_eq!(
            Atom::Str("with\nnewline".into()).as_string(),
            Some("with\nnewline"),
        );
        assert_eq!(Atom::Str(String::new()).as_string(), Some(""));
        assert_eq!(
            Atom::Symbol("looks-like-a-string".into()).as_string(),
            None,
            "Atom::as_string MUST NOT conflate Symbol with Str — load-bearing typed-identity",
        );
        assert_eq!(
            Atom::Keyword("looks-like-a-string".into()).as_string(),
            None,
            "Atom::as_string MUST NOT conflate Keyword with Str — load-bearing typed-identity",
        );
        for kind in [AtomKind::Int, AtomKind::Float, AtomKind::Bool] {
            let probe: Atom = match kind {
                AtomKind::Int => Atom::Int(42),
                AtomKind::Float => Atom::Float(1.5),
                AtomKind::Bool => Atom::Bool(true),
                _ => unreachable!(),
            };
            assert_eq!(
                probe.as_string(),
                None,
                "Atom::as_string must reject non-Str variant {kind:?}",
            );
        }
    }

    #[test]
    fn atom_as_int_returns_payload_iff_int_variant_strict_no_float_widening() {
        // PER-VARIANT PROJECTION CONTRACT (STRICT): `Atom::as_int`
        // projects `Atom::Int(n)` to `Some(n)` and every other variant
        // to `None`. STRICT typed identity: `Atom::Float(1.0)` does
        // NOT project through (stays `None`) — the typed-identity
        // distinction `Int(1)` vs `Float(1.0)` (load-bearing at the
        // `Atom::from_lexeme` ⇄ `Atom::Display` round-trip boundary, dual of
        // `fmt_float`'s `.0`-suffix discipline) is preserved at the
        // algebra layer. The widening face lives at the
        // `Sexp::as_float` consumer (which accepts both `Float` AND
        // `Int`); the strict typed identity at the `Atom` algebra is
        // load-bearing.
        assert_eq!(Atom::Int(42).as_int(), Some(42));
        assert_eq!(Atom::Int(-7).as_int(), Some(-7));
        assert_eq!(Atom::Int(0).as_int(), Some(0));
        assert_eq!(
            Atom::Float(1.0).as_int(),
            None,
            "Atom::as_int MUST be strict — Float(1.0) is NOT Int(1) at the algebra layer",
        );
        for kind in [
            AtomKind::Symbol,
            AtomKind::Keyword,
            AtomKind::Str,
            AtomKind::Float,
            AtomKind::Bool,
        ] {
            let probe: Atom = match kind {
                AtomKind::Symbol => Atom::Symbol("foo".into()),
                AtomKind::Keyword => Atom::Keyword("kw".into()),
                AtomKind::Str => Atom::Str("body".into()),
                AtomKind::Float => Atom::Float(1.5),
                AtomKind::Bool => Atom::Bool(true),
                _ => unreachable!(),
            };
            assert_eq!(
                probe.as_int(),
                None,
                "Atom::as_int must reject non-Int variant {kind:?}",
            );
        }
    }

    #[test]
    fn atom_as_float_returns_payload_iff_float_variant_strict_no_int_widening() {
        // PER-VARIANT PROJECTION CONTRACT (STRICT): `Atom::as_float`
        // projects `Atom::Float(n)` to `Some(n)` and every other
        // variant to `None`. STRICT typed identity: `Atom::Int(1)`
        // does NOT project through (stays `None`) — see
        // `atom_as_int_returns_payload_iff_int_variant_strict_no_float_widening`
        // for the symmetric discipline. The widening face
        // (`Atom::Int(n) → Some(n as f64)`) lives at the `Sexp::as_float`
        // consumer layer, NOT the algebra layer.
        assert_eq!(Atom::Float(1.5).as_float(), Some(1.5));
        assert_eq!(Atom::Float(1.0).as_float(), Some(1.0));
        assert_eq!(Atom::Float(-42.0).as_float(), Some(-42.0));
        assert_eq!(
            Atom::Int(1).as_float(),
            None,
            "Atom::as_float MUST be strict — Int(1) is NOT Float(1.0) at the algebra layer",
        );
        for kind in [
            AtomKind::Symbol,
            AtomKind::Keyword,
            AtomKind::Str,
            AtomKind::Int,
            AtomKind::Bool,
        ] {
            let probe: Atom = match kind {
                AtomKind::Symbol => Atom::Symbol("foo".into()),
                AtomKind::Keyword => Atom::Keyword("kw".into()),
                AtomKind::Str => Atom::Str("body".into()),
                AtomKind::Int => Atom::Int(42),
                AtomKind::Bool => Atom::Bool(true),
                _ => unreachable!(),
            };
            assert_eq!(
                probe.as_float(),
                None,
                "Atom::as_float must reject non-Float variant {kind:?}",
            );
        }
    }

    #[test]
    fn atom_as_bool_returns_payload_iff_bool_variant() {
        // PER-VARIANT PROJECTION CONTRACT: `Atom::as_bool` projects
        // `Atom::Bool(b)` to `Some(b)` and every other variant to
        // `None`. Both spellings (`true` / `false`) project through
        // the SAME projection — the variant identity (`Bool`) is what
        // routes; the inner payload (`true` / `false`) is the
        // projected value. CLAUDE.md "Lisp bools": at the reader
        // boundary the typed-entry classifier `Atom::from_lexeme`
        // routes `"#t"` / `"#f"` to `Atom::Bool(_)` and bare
        // `"true"` / `"false"` to `Atom::Symbol(_)`; this projection
        // does NOT re-classify the symbol-spelled bools — they STAY
        // symbols. The negative test (`Atom::Symbol("true")` rejects)
        // pins the discriminator discipline.
        assert_eq!(Atom::Bool(true).as_bool(), Some(true));
        assert_eq!(Atom::Bool(false).as_bool(), Some(false));
        assert_eq!(
            Atom::Symbol("true".into()).as_bool(),
            None,
            "Atom::as_bool MUST reject Symbol(\"true\") — CLAUDE.md typed-identity discipline",
        );
        assert_eq!(
            Atom::Symbol("false".into()).as_bool(),
            None,
            "Atom::as_bool MUST reject Symbol(\"false\") — CLAUDE.md typed-identity discipline",
        );
        for kind in [
            AtomKind::Symbol,
            AtomKind::Keyword,
            AtomKind::Str,
            AtomKind::Int,
            AtomKind::Float,
        ] {
            let probe: Atom = match kind {
                AtomKind::Symbol => Atom::Symbol("foo".into()),
                AtomKind::Keyword => Atom::Keyword("kw".into()),
                AtomKind::Str => Atom::Str("body".into()),
                AtomKind::Int => Atom::Int(42),
                AtomKind::Float => Atom::Float(1.5),
                _ => unreachable!(),
            };
            assert_eq!(
                probe.as_bool(),
                None,
                "Atom::as_bool must reject non-Bool variant {kind:?}",
            );
        }
    }

    #[test]
    fn atom_as_symbol_or_string_returns_payload_iff_symbol_or_str_variant() {
        // UNION-PROJECTION CONTRACT: `Atom::as_symbol_or_string` projects
        // BOTH `Atom::Symbol(s)` AND `Atom::Str(s)` to `Some(s)` and every
        // other atomic kind (`Keyword`, `Int`, `Float`, `Bool`) to `None`.
        // The disjunctive composition `as_symbol().or_else(||
        // as_string())` lives at ONE typed-algebra projection on the
        // closed-set `Atom` algebra; pre-lift the composition lived at
        // `Sexp::as_symbol_or_string`'s consumer body and traversed
        // `Sexp::as_atom` TWICE (once per per-variant projection),
        // post-lift it traverses `Sexp::as_atom` ONCE through the
        // algebra-level union projection. Pin the algebra-level contract
        // sweep so a regression that drifts ONE union arm (e.g. drops the
        // `Str` arm, accidentally widens to accept `Keyword`) surfaces
        // structurally.
        assert_eq!(
            Atom::Symbol("my-name".into()).as_symbol_or_string(),
            Some("my-name"),
            "Atom::as_symbol_or_string must accept Atom::Symbol",
        );
        assert_eq!(
            Atom::Str("my-name".into()).as_symbol_or_string(),
            Some("my-name"),
            "Atom::as_symbol_or_string must accept Atom::Str",
        );
        // Empty payloads project through too — the union projection
        // is keyed on variant identity, not payload contents.
        assert_eq!(
            Atom::Symbol(String::new()).as_symbol_or_string(),
            Some(""),
            "Atom::as_symbol_or_string must accept empty Symbol payload",
        );
        assert_eq!(
            Atom::Str(String::new()).as_symbol_or_string(),
            Some(""),
            "Atom::as_symbol_or_string must accept empty Str payload",
        );
        // Negative sweep: the four non-Symbol-non-Str variants reject.
        for kind in [
            AtomKind::Keyword,
            AtomKind::Int,
            AtomKind::Float,
            AtomKind::Bool,
        ] {
            let probe: Atom = match kind {
                AtomKind::Keyword => Atom::Keyword("kw".into()),
                AtomKind::Int => Atom::Int(42),
                AtomKind::Float => Atom::Float(1.5),
                AtomKind::Bool => Atom::Bool(true),
                _ => unreachable!(),
            };
            assert_eq!(
                probe.as_symbol_or_string(),
                None,
                "Atom::as_symbol_or_string must reject non-Symbol-non-Str variant {kind:?}",
            );
        }
    }

    #[test]
    fn atom_as_symbol_or_string_borrow_ptr_eq_payload() {
        // BORROW-LIFETIME CONTRACT: the yielded `&str` borrows the inner
        // `String` payload's `&str` view verbatim — no copy, no
        // allocation, no `to_string()` round-trip. Pin via `ptr::eq` on
        // both projection sides (Symbol arm AND Str arm) so a regression
        // that re-inlines the union as `match self { Symbol(s) =>
        // Some(s.clone().as_str()), … }` (a `String::clone` reborrow that
        // changes the byte-identity) surfaces structurally. Same posture
        // as `as_call_to_args_borrow_is_same_pointer_as_as_call_tail` on
        // the call-form algebra.
        let sym = Atom::Symbol("my-name".into());
        let projected = sym.as_symbol_or_string().expect("Symbol arm projects");
        match &sym {
            Atom::Symbol(s) => assert!(
                std::ptr::eq(projected.as_ptr(), s.as_ptr()),
                "Atom::as_symbol_or_string must borrow Atom::Symbol payload verbatim",
            ),
            _ => unreachable!(),
        }
        let str_atom = Atom::Str("my-name".into());
        let projected_str = str_atom.as_symbol_or_string().expect("Str arm projects");
        match &str_atom {
            Atom::Str(s) => assert!(
                std::ptr::eq(projected_str.as_ptr(), s.as_ptr()),
                "Atom::as_symbol_or_string must borrow Atom::Str payload verbatim",
            ),
            _ => unreachable!(),
        }
    }

    #[test]
    fn atom_as_symbol_or_string_is_the_disjunction_of_as_symbol_and_as_string() {
        // COMPOSITION LAW: pin that the union projection's value AGREES
        // byte-for-byte with the explicit disjunctive composition
        // `as_symbol().or_else(|| as_string())` across every atom kind.
        // A regression that drifts the union from its disjunctive
        // composition (e.g. swaps the `or_else` order so an
        // `Atom::Symbol` somehow routes through the `Str` arm first, or
        // adds a phantom arm that accepts `Keyword` payloads) surfaces
        // here. Same posture as `is_kwargs_list` composing through
        // `as_list ∘ atom_as_keyword`.
        for atom in [
            Atom::Symbol("foo".into()),
            Atom::Keyword("kw".into()),
            Atom::Str("body".into()),
            Atom::Int(42),
            Atom::Float(1.5),
            Atom::Bool(true),
            Atom::Bool(false),
            Atom::Symbol(String::new()),
            Atom::Str(String::new()),
        ] {
            let by_hand = atom.as_symbol().or_else(|| atom.as_string());
            assert_eq!(
                atom.as_symbol_or_string(),
                by_hand,
                "Atom::as_symbol_or_string drifted from as_symbol().or_else(|| as_string()) for {atom:?}",
            );
        }
    }

    #[test]
    fn sexp_as_symbol_or_string_routes_through_atom_as_symbol_or_string_via_as_atom_composition() {
        // CONSUMER-LAYER COMPOSITION LAW: pin that `Sexp::as_symbol_or_string`
        // routes through the structural lift `Sexp::as_atom` + the
        // algebra-level `Atom::as_symbol_or_string` union projection —
        // a regression that re-inlines the pre-lift body
        // `self.as_symbol().or_else(|| self.as_string())` (TWO
        // `Sexp::as_atom` traversals) at the `Sexp` consumer layer
        // becomes detectable here. Sweeps every reachable outer shape so
        // the closed-form composition is pinned across Nil + every Atom
        // variant + every quote-family wrapper + List + the Sexp::Atom
        // arms a regression could route to.
        let cases = [
            Sexp::Nil,
            Sexp::symbol("foo"),
            Sexp::symbol(""),
            Sexp::string("body"),
            Sexp::string(""),
            Sexp::keyword("kw"),
            Sexp::int(7),
            Sexp::float(2.5),
            Sexp::boolean(true),
            Sexp::Quote(Box::new(Sexp::symbol("x"))),
            Sexp::Quasiquote(Box::new(Sexp::symbol("x"))),
            Sexp::Unquote(Box::new(Sexp::symbol("x"))),
            Sexp::UnquoteSplice(Box::new(Sexp::symbol("x"))),
            Sexp::List(vec![Sexp::symbol("a")]),
            Sexp::List(vec![]),
        ];
        for s in &cases {
            let by_composition = s.as_atom().and_then(Atom::as_symbol_or_string);
            assert_eq!(
                s.as_symbol_or_string(),
                by_composition,
                "Sexp::as_symbol_or_string drifted from as_atom().and_then(Atom::as_symbol_or_string) for {s}",
            );
        }
    }

    #[test]
    fn sexp_as_symbol_or_string_yields_none_for_non_atom_outer_shapes() {
        // OUTER-SHAPE NEGATIVE SWEEP: pin that every non-Atom outer
        // shape (`Nil`, `List`, every quote-family wrapper) projects to
        // `None` — the structural-lift `Sexp::as_atom` rejects them at
        // the outer match before the union projection even runs. Pins
        // the soft-projection face: the named-form NAME gate
        // (`crate::compile::split_name_slot`'s `as_symbol_or_string`
        // consumer at compile.rs:671) sees `None` for these shapes and
        // emits `NamedFormNonSymbolName` with the projected `SexpShape`
        // — the lift preserves the same rejection arm boundary.
        for outer in [
            Sexp::Nil,
            Sexp::List(vec![Sexp::symbol("a")]),
            Sexp::List(vec![]),
            Sexp::Quote(Box::new(Sexp::symbol("x"))),
            Sexp::Quasiquote(Box::new(Sexp::symbol("x"))),
            Sexp::Unquote(Box::new(Sexp::symbol("x"))),
            Sexp::UnquoteSplice(Box::new(Sexp::symbol("x"))),
        ] {
            assert_eq!(
                outer.as_symbol_or_string(),
                None,
                "Sexp::as_symbol_or_string must reject non-Atom outer shape {outer:?}",
            );
        }
    }

    #[test]
    fn sexp_as_symbol_or_string_borrow_ptr_eq_atom_payload() {
        // BORROW-LIFETIME CONTRACT: the yielded `&str` borrows the inner
        // `Atom::Symbol` / `Atom::Str` payload verbatim — no copy, no
        // allocation, same lifetime as the outer `&Sexp`. Pin via
        // `ptr::eq` on both projection sides so a regression that
        // re-inlines the union as a `String`-allocating reborrow (e.g.
        // `.map(|s| s.to_owned())` somewhere along the chain) surfaces
        // structurally. Sibling pin to
        // `atom_as_symbol_or_string_borrow_ptr_eq_payload` at the outer
        // (`&Sexp`) layer rather than the inner (`&Atom`) layer.
        let sym_sexp = Sexp::symbol("my-name");
        let projected = sym_sexp.as_symbol_or_string().expect("Symbol arm projects");
        match &sym_sexp {
            Sexp::Atom(Atom::Symbol(s)) => assert!(
                std::ptr::eq(projected.as_ptr(), s.as_ptr()),
                "Sexp::as_symbol_or_string must borrow Atom::Symbol payload verbatim",
            ),
            _ => unreachable!(),
        }
        let str_sexp = Sexp::string("my-name");
        let projected_str = str_sexp.as_symbol_or_string().expect("Str arm projects");
        match &str_sexp {
            Sexp::Atom(Atom::Str(s)) => assert!(
                std::ptr::eq(projected_str.as_ptr(), s.as_ptr()),
                "Sexp::as_symbol_or_string must borrow Atom::Str payload verbatim",
            ),
            _ => unreachable!(),
        }
    }

    #[test]
    fn sexp_as_atom_projects_inner_atom_iff_outer_is_atom_variant() {
        // STRUCTURAL-LIFT CONTRACT: `Sexp::as_atom` projects
        // `Sexp::Atom(a)` to `Some(&a)` and every other outer shape
        // (`Nil` / `List` / `Quote` / `Quasiquote` / `Unquote` /
        // `UnquoteSplice`) to `None`. Sweeps each outer shape so a
        // regression that mis-routes ONE arm (e.g. accepts the
        // singleton list `(a)` thinking the inner counts as the
        // "wrapped atom", or rejects an `Atom` whose payload is empty)
        // fails loudly. The `&Atom` borrow is rooted at the outer
        // `&Sexp` — the projection does not clone, allocate, or take
        // ownership.
        let atom = Atom::Symbol("foo".into());
        let sexp = Sexp::Atom(atom.clone());
        assert_eq!(sexp.as_atom(), Some(&atom));

        for outer in [
            Sexp::Nil,
            Sexp::List(vec![Sexp::symbol("a")]),
            Sexp::List(vec![]),
            Sexp::Quote(Box::new(Sexp::symbol("x"))),
            Sexp::Quasiquote(Box::new(Sexp::symbol("x"))),
            Sexp::Unquote(Box::new(Sexp::symbol("x"))),
            Sexp::UnquoteSplice(Box::new(Sexp::symbol("x"))),
        ] {
            assert_eq!(
                outer.as_atom(),
                None,
                "Sexp::as_atom must reject non-Atom outer shape {outer:?}",
            );
        }
    }

    #[test]
    fn sexp_shape_method_projects_each_outer_arm_to_canonical_sexp_shape() {
        // CANONICAL-MAPPING CONTRACT: pin that `Sexp::shape()` produces
        // byte-identical `SexpShape` markers for each outer-arm of the
        // closed `Sexp` algebra. Sweeps every reachable outer shape
        // (`Nil`, every `AtomKind` payload, `List`, every `QuoteForm`
        // wrapper) so a regression that drifts ONE arm (e.g. routes the
        // `Atom::Keyword` arm through `Atom::kind().sexp_shape()` to the
        // wrong `SexpShape` variant, or drops the `expect_quote_form`
        // projection's marker for a quote-family wrapper) fails loudly.
        // Sibling-arm sweep to
        // `quote_form_sexp_shape_pins_canonical_shape_identity_for_every_variant`
        // (the four quote-family arms in isolation) AND
        // `atom_kind_sexp_shape_pins_canonical_atom_payload_shape_for_every_variant`
        // (the six atomic-payload arms in isolation) — this test pins
        // the OUTER projection that COMPOSES both peer algebras + the
        // `Nil` / `List` arms into ONE typed method on the `Sexp`
        // algebra.
        use crate::error::SexpShape;
        assert_eq!(Sexp::Nil.shape(), SexpShape::Nil);
        assert_eq!(Sexp::symbol("foo").shape(), SexpShape::Symbol);
        assert_eq!(Sexp::keyword("k").shape(), SexpShape::Keyword);
        assert_eq!(Sexp::string("s").shape(), SexpShape::String);
        assert_eq!(Sexp::int(7).shape(), SexpShape::Int);
        assert_eq!(Sexp::float(7.5).shape(), SexpShape::Float);
        assert_eq!(Sexp::boolean(true).shape(), SexpShape::Bool);
        assert_eq!(Sexp::List(vec![]).shape(), SexpShape::List);
        assert_eq!(
            Sexp::List(vec![Sexp::symbol("op"), Sexp::int(1)]).shape(),
            SexpShape::List,
            "non-empty list must project to SexpShape::List — payload count is irrelevant",
        );
        assert_eq!(Sexp::Quote(Box::new(Sexp::Nil)).shape(), SexpShape::Quote);
        assert_eq!(
            Sexp::Quasiquote(Box::new(Sexp::Nil)).shape(),
            SexpShape::Quasiquote
        );
        assert_eq!(
            Sexp::Unquote(Box::new(Sexp::Nil)).shape(),
            SexpShape::Unquote
        );
        assert_eq!(
            Sexp::UnquoteSplice(Box::new(Sexp::Nil)).shape(),
            SexpShape::UnquoteSplice
        );
    }

    #[test]
    fn sexp_shape_method_agrees_with_domain_sexp_shape_for_every_outer_shape() {
        // LIFTED-BOUNDARY CONTRACT: pin that the inherent
        // `Sexp::shape()` method agrees with the free-function
        // delegate `crate::domain::sexp_shape` for every reachable
        // outer shape. Pre-lift the dispatcher lived as a free
        // function in `domain.rs`; post-lift the canonical site is
        // the inherent method on the `Sexp` algebra and the free
        // function is a one-line delegate. Pin that the delegation
        // stays byte-for-byte equivalent across every outer arm so a
        // regression where the free function drifts from the inherent
        // method (or vice versa) surfaces here immediately. Catches
        // a future "consolidation" that removes the free function
        // without updating the method, or vice versa.
        let samples = [
            Sexp::Nil,
            Sexp::symbol("foo"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::int(-1),
            Sexp::float(7.5),
            Sexp::float(0.0),
            Sexp::boolean(true),
            Sexp::boolean(false),
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("op"), Sexp::int(1), Sexp::int(2)]),
            Sexp::Quote(Box::new(Sexp::symbol("payload"))),
            Sexp::Quasiquote(Box::new(Sexp::List(vec![Sexp::symbol("foo")]))),
            Sexp::Unquote(Box::new(Sexp::symbol("x"))),
            Sexp::UnquoteSplice(Box::new(Sexp::symbol("xs"))),
        ];
        for s in &samples {
            let via_method = s.shape();
            let via_delegate = crate::domain::sexp_shape(s);
            assert_eq!(
                via_method, via_delegate,
                "Sexp::shape and domain::sexp_shape drifted at {s:?}",
            );
        }
    }

    #[test]
    fn sexp_shape_method_routes_atom_arm_through_atom_kind_sexp_shape_projection() {
        // PATH-UNIFORMITY CONTRACT (atomic axis): the lifted
        // `Sexp::shape()` routes its Atom arm through
        // `Atom::kind().sexp_shape()` — the typed closed-set projection
        // on the `AtomKind` algebra. Pin that the composition agrees
        // bit-for-bit with the direct `Sexp::shape()` projection across
        // every atomic kind variant. A regression in EITHER projection
        // direction (an `Atom::kind` arm that swaps markers, or an
        // `AtomKind::sexp_shape` arm that drifts its `SexpShape` mapping)
        // surfaces here immediately. Sibling shape to
        // `sexp_shape_method_routes_quote_family_arms_through_quote_form_sexp_shape_projection`
        // for the quote-family axis.
        for kind in AtomKind::ALL {
            let atom = match kind {
                AtomKind::Symbol => Atom::Symbol("name".into()),
                AtomKind::Keyword => Atom::Keyword("parent".into()),
                AtomKind::Str => Atom::Str("body".into()),
                AtomKind::Int => Atom::Int(42),
                AtomKind::Float => Atom::Float(1.5),
                AtomKind::Bool => Atom::Bool(true),
            };
            let via_outer = Sexp::Atom(atom.clone()).shape();
            let via_composed = atom.kind().sexp_shape();
            assert_eq!(
                via_outer, via_composed,
                "Sexp::shape's Atom arm drifted from Atom::kind().sexp_shape() at {kind:?}",
            );
        }
    }

    #[test]
    fn sexp_shape_method_routes_quote_family_arms_through_quote_form_sexp_shape_projection() {
        // PATH-UNIFORMITY CONTRACT (quote-family axis): the lifted
        // `Sexp::shape()` routes its four quote-family arms through
        // `as_quote_form() + QuoteForm::sexp_shape()`. Pin that the
        // composition agrees bit-for-bit with the direct `Sexp::shape()`
        // projection across every quote-family wrapper variant. A
        // regression in EITHER projection direction (an `as_quote_form`
        // arm that swaps markers, or a `QuoteForm::sexp_shape` arm that
        // drifts its `SexpShape` mapping) surfaces here immediately.
        // Mirrors the atomic-axis test
        // `sexp_shape_method_routes_atom_arm_through_atom_kind_sexp_shape_projection`.
        let samples = [
            (
                Sexp::Quote(Box::new(Sexp::symbol("payload"))),
                QuoteForm::Quote,
            ),
            (
                Sexp::Quasiquote(Box::new(Sexp::symbol("payload"))),
                QuoteForm::Quasiquote,
            ),
            (
                Sexp::Unquote(Box::new(Sexp::symbol("payload"))),
                QuoteForm::Unquote,
            ),
            (
                Sexp::UnquoteSplice(Box::new(Sexp::symbol("payload"))),
                QuoteForm::UnquoteSplice,
            ),
        ];
        for (sexp, expected_qf) in &samples {
            let via_outer = sexp.shape();
            let (qf, _) = sexp
                .as_quote_form()
                .expect("quote-family sample must project through as_quote_form");
            assert_eq!(
                qf, *expected_qf,
                "as_quote_form drifted typed marker at {sexp:?}"
            );
            let via_composed = qf.sexp_shape();
            assert_eq!(
                via_outer, via_composed,
                "Sexp::shape drifted from as_quote_form + QuoteForm::sexp_shape at {sexp:?}"
            );
        }
    }

    #[test]
    fn sexp_shape_method_routes_structural_arms_through_structural_kind_sexp_shape_projection() {
        // PATH-UNIFORMITY CONTRACT (structural-residual axis): the
        // lifted `Sexp::shape()` routes its two structural-residual
        // arms (Nil, List) through `StructuralKind::sexp_shape()`. Pin
        // that the composition agrees bit-for-bit with the direct
        // `Sexp::shape()` projection across the two structural-residual
        // variants. A regression that drifts EITHER projection direction
        // (a `Sexp::shape` arm that inlines `SexpShape::Nil` /
        // `SexpShape::List` back as a raw literal, or a
        // `StructuralKind::sexp_shape` arm that drifts its `SexpShape`
        // mapping) surfaces here immediately. Sibling-shape pin to the
        // atomic-axis routing test
        // `sexp_shape_method_routes_atom_arm_through_atom_kind_sexp_shape_projection`
        // and the quote-family-axis routing test
        // `sexp_shape_method_routes_quote_family_arms_through_quote_form_sexp_shape_projection`
        // — together the three tests pin ALL THREE closed-set
        // carving-marker `sexp_shape` compositions the lifted
        // `Sexp::shape()` body owns.
        let samples = [
            (Sexp::Nil, StructuralKind::Nil),
            (Sexp::List(vec![]), StructuralKind::List),
            (Sexp::List(vec![Sexp::symbol("a")]), StructuralKind::List),
        ];
        for (sexp, expected_sk) in &samples {
            let via_outer = sexp.shape();
            let sk = sexp
                .as_structural_kind()
                .expect("structural-residual sample must project through as_structural_kind");
            assert_eq!(
                sk, *expected_sk,
                "as_structural_kind drifted typed marker at {sexp:?}"
            );
            let via_composed = sk.sexp_shape();
            assert_eq!(
                via_outer, via_composed,
                "Sexp::shape drifted from as_structural_kind + StructuralKind::sexp_shape at {sexp:?}"
            );
        }
    }

    #[test]
    fn sexp_as_structural_kind_projects_nil_and_list_to_canonical_structural_kind() {
        // PER-ARM CONTRACT: pin that `Sexp::as_structural_kind()`
        // projects `Sexp::Nil` to `Some(StructuralKind::Nil)` and
        // `Sexp::List(_)` to `Some(StructuralKind::List)` — the two
        // structural-residual arms of the `Sexp` algebra. A regression
        // that swaps the two arms (routes `Nil` to `Some(List)` or
        // vice versa), returns `None` for either, or projects to a
        // wrong `StructuralKind` variant surfaces here immediately.
        // The List arm is exercised with an empty AND a non-empty
        // items slice so a body that gates on `items.is_empty()`
        // (rather than the outer arm) fails loudly.
        assert_eq!(Sexp::Nil.as_structural_kind(), Some(StructuralKind::Nil));
        assert_eq!(
            Sexp::List(vec![]).as_structural_kind(),
            Some(StructuralKind::List)
        );
        assert_eq!(
            Sexp::List(vec![Sexp::symbol("a")]).as_structural_kind(),
            Some(StructuralKind::List)
        );
        assert_eq!(
            Sexp::List(vec![Sexp::int(1), Sexp::int(2), Sexp::int(3)]).as_structural_kind(),
            Some(StructuralKind::List)
        );
    }

    #[test]
    fn sexp_as_structural_kind_rejects_non_structural_outer_shapes() {
        // KERNEL CONTRACT: pin that `Sexp::as_structural_kind()`
        // returns `None` for every non-structural outer shape — every
        // `Sexp::Atom` variant (the atomic-payload carving) AND every
        // quote-family wrapper (the quote-family carving). Sweeps
        // every non-residual arm so a regression that accepts an atom
        // (e.g. routes `Sexp::Atom(_)` to `Some(List)` because the
        // outer arm is misread as a "container" of an atomic payload)
        // or a quote-family wrapper (e.g. routes `Sexp::Quote(_)`
        // through `_ => Some(_)` because the residual match falls
        // through) fails loudly. Sibling-cohort sweep to
        // `sexp_as_atom_projects_inner_atom_iff_outer_is_atom_variant`
        // — that test pins the atomic-projection kernel, this one
        // pins the structural-residual kernel.
        for outer in [
            Sexp::symbol("foo"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::float(7.5),
            Sexp::boolean(true),
            Sexp::Quote(Box::new(Sexp::symbol("x"))),
            Sexp::Quasiquote(Box::new(Sexp::symbol("x"))),
            Sexp::Unquote(Box::new(Sexp::symbol("x"))),
            Sexp::UnquoteSplice(Box::new(Sexp::symbol("x"))),
        ] {
            assert_eq!(
                outer.as_structural_kind(),
                None,
                "Sexp::as_structural_kind must reject non-structural outer shape {outer:?}",
            );
        }
    }

    #[test]
    fn sexp_as_structural_kind_agrees_with_shape_as_structural_kind_for_every_variant() {
        // COMPOSITION-LAW CONTRACT: `s.as_structural_kind() ==
        // s.shape().as_structural_kind()` for every reachable Sexp
        // outer shape. The value-level projection and the shape-level
        // projection MUST agree bit-for-bit — the substrate's
        // (Sexp value, StructuralKind marker) pairing binds at TWO
        // typed methods (one on `Sexp`, one on `SexpShape`) that must
        // stay in lockstep. Sweeps every outer shape (residual + atom
        // + quote-family) so a drift on ANY arm surfaces immediately.
        // Sibling-shape pin to the (Sexp → SexpShape → label) path-
        // uniformity test
        // `sexp_shape_method_label_composes_with_sexp_type_name_for_every_outer_shape`
        // — where that test pins the label-projection composition,
        // this one pins the structural-carving-marker projection
        // composition.
        let samples = [
            Sexp::Nil,
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("a")]),
            Sexp::symbol("foo"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::float(7.5),
            Sexp::boolean(true),
            Sexp::Quote(Box::new(Sexp::Nil)),
            Sexp::Quasiquote(Box::new(Sexp::Nil)),
            Sexp::Unquote(Box::new(Sexp::Nil)),
            Sexp::UnquoteSplice(Box::new(Sexp::Nil)),
        ];
        for s in &samples {
            assert_eq!(
                s.as_structural_kind(),
                s.shape().as_structural_kind(),
                "Sexp::as_structural_kind and Sexp::shape().as_structural_kind must agree at {s:?}",
            );
        }
    }

    #[test]
    fn sexp_as_structural_kind_partitions_outer_shapes_jointly_with_as_atom_and_as_quote_form() {
        // PARTITION-TOTAL CONTRACT (value-level): pin that for every
        // reachable Sexp outer shape, EXACTLY ONE of `as_atom`,
        // `as_quote_form`, `as_structural_kind` returns `Some(_)`.
        // Post-lift the three carving-marker projections at the value
        // level form a partition of the `Sexp` variant algebra —
        // symmetric with the partition-total invariant pinned at the
        // shape level by
        // `sexp_shape_partition_is_total_across_atom_quote_structural_carvings`
        // (in `error.rs`). A regression that drifts any carving's
        // membership (an `as_atom` arm that accepts a non-atom, an
        // `as_quote_form` arm that misses a quote-family wrapper, an
        // `as_structural_kind` arm that swaps its Nil/List
        // membership) surfaces here immediately, so the value-level
        // partition invariant is a TYPED THEOREM (rustc-enforced
        // exhaustiveness through the joint sweep) rather than a
        // runtime `matches!` assertion.
        let samples = [
            Sexp::Nil,
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("a")]),
            Sexp::symbol("foo"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::float(7.5),
            Sexp::boolean(true),
            Sexp::Quote(Box::new(Sexp::Nil)),
            Sexp::Quasiquote(Box::new(Sexp::Nil)),
            Sexp::Unquote(Box::new(Sexp::Nil)),
            Sexp::UnquoteSplice(Box::new(Sexp::Nil)),
        ];
        for s in &samples {
            let hits = [
                s.as_atom().is_some(),
                s.as_quote_form().is_some(),
                s.as_structural_kind().is_some(),
            ];
            let hit_count: usize = hits.iter().filter(|b| **b).count();
            assert_eq!(
                hit_count, 1,
                "value-level carvings must partition Sexp variants — {s:?} matched {hit_count} carvings (as_atom/as_quote_form/as_structural_kind = {hits:?})",
            );
        }
    }

    #[test]
    fn sexp_as_structural_kind_composes_with_label_via_structural_kind_label() {
        // CROSS-PROJECTION COHERENCE: pin that
        // `s.as_structural_kind().map(StructuralKind::label)` agrees
        // with `s.shape().label()` for every residual-carving Sexp
        // (and returns `None` for every non-residual Sexp). Composes
        // the new value-level projection with the closed-set
        // `StructuralKind::label` projection (which itself composes
        // through `sexp_shape().label()`) so the label vocabulary
        // stays load-bearing at ONE canonical site
        // (`SexpShape::label`) rather than a parallel per-projection
        // literal table.
        let residual = [
            (Sexp::Nil, "nil"),
            (Sexp::List(vec![]), "list"),
            (Sexp::List(vec![Sexp::symbol("a")]), "list"),
        ];
        for (sexp, expected_label) in &residual {
            let via_carving = sexp.as_structural_kind().map(StructuralKind::label);
            assert_eq!(
                via_carving,
                Some(*expected_label),
                "structural-carving-marker label drifted at {sexp:?}"
            );
            assert_eq!(
                via_carving,
                Some(sexp.shape().label()),
                "as_structural_kind.map(label) must equal shape().label() for residual sample {sexp:?}"
            );
        }
        for non_residual in [
            Sexp::symbol("foo"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::float(7.5),
            Sexp::boolean(true),
            Sexp::Quote(Box::new(Sexp::Nil)),
            Sexp::Quasiquote(Box::new(Sexp::Nil)),
            Sexp::Unquote(Box::new(Sexp::Nil)),
            Sexp::UnquoteSplice(Box::new(Sexp::Nil)),
        ] {
            assert_eq!(
                non_residual.as_structural_kind().map(StructuralKind::label),
                None,
                "non-residual Sexp must project to None on as_structural_kind.map(label) — {non_residual:?}"
            );
        }
    }

    #[test]
    fn sexp_as_atom_kind_projects_each_atom_variant_to_canonical_atom_kind() {
        // PER-VARIANT TRUTH-TABLE (atomic axis): pin byte-for-byte per-
        // Sexp-atom-arm mapping — Symbol payload → Some(AtomKind::Symbol),
        // Keyword payload → Some(AtomKind::Keyword), Str payload →
        // Some(AtomKind::Str), Int payload → Some(AtomKind::Int), Float
        // payload → Some(AtomKind::Float), Bool payload →
        // Some(AtomKind::Bool). Value-level peer of the shape-level
        // sweep `as_atom_kind_projects_each_atom_shape_to_canonical_atom_kind_and_rejects_non_atom_shapes`
        // in error.rs — each atomic Sexp value's carving-marker
        // projection must land on the matching AtomKind arm the shape-
        // level projection lands on. A future thirteenth Atom variant
        // extends both this sweep + the composition body via the
        // as_atom + Atom::kind primitives, with rustc enforcing the
        // match arms in lockstep.
        assert_eq!(Sexp::symbol("foo").as_atom_kind(), Some(AtomKind::Symbol));
        assert_eq!(Sexp::keyword("k").as_atom_kind(), Some(AtomKind::Keyword));
        assert_eq!(Sexp::string("s").as_atom_kind(), Some(AtomKind::Str));
        assert_eq!(Sexp::int(7).as_atom_kind(), Some(AtomKind::Int));
        assert_eq!(Sexp::float(7.5).as_atom_kind(), Some(AtomKind::Float));
        assert_eq!(Sexp::boolean(true).as_atom_kind(), Some(AtomKind::Bool));
        // Empty-payload edge cases (empty-string vs Symbol vs Keyword)
        // — pin the projection ignores payload content entirely (it
        // reads only the outer variant discriminant), so a body that
        // gates on payload emptiness fails loudly.
        assert_eq!(Sexp::symbol("").as_atom_kind(), Some(AtomKind::Symbol));
        assert_eq!(Sexp::string("").as_atom_kind(), Some(AtomKind::Str));
    }

    #[test]
    fn sexp_as_atom_kind_rejects_non_atom_outer_shapes() {
        // KERNEL: every non-atom outer shape (Nil, List, every quote-
        // family wrapper) projects to `None`. Sibling kernel-pin to
        // `sexp_as_structural_kind_rejects_non_structural_outer_shapes`
        // on the residual axis. Together the two kernel pins bracket
        // the atomic-carving membership from BOTH sides of the
        // partition — the atomic-arm membership from
        // `sexp_as_atom_kind_projects_each_atom_variant_to_canonical_atom_kind`
        // and the non-atomic-arm kernel from THIS test.
        for non_atom in [
            Sexp::Nil,
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("a")]),
            Sexp::Quote(Box::new(Sexp::Nil)),
            Sexp::Quasiquote(Box::new(Sexp::Nil)),
            Sexp::Unquote(Box::new(Sexp::Nil)),
            Sexp::UnquoteSplice(Box::new(Sexp::Nil)),
        ] {
            assert_eq!(
                non_atom.as_atom_kind(),
                None,
                "non-atom Sexp must project to None on as_atom_kind — {non_atom:?}"
            );
        }
    }

    #[test]
    fn sexp_as_atom_kind_agrees_with_as_atom_map_kind_for_every_variant() {
        // COMPOSITION-LAW CONTRACT (atomic-axis peer of the shape-
        // agreement law): `s.as_atom_kind() == s.as_atom().map(Atom::kind)`
        // for every reachable Sexp outer shape. Pre-lift the atomic
        // carving marker at the value level was reachable via this
        // two-step composition through the Atom algebra; post-lift the
        // new projection MUST agree bit-for-bit — the substrate's
        // (Sexp value, AtomKind marker) pairing binds at TWO
        // compositions (this Atom-axis composition AND the shape-axis
        // composition pinned by the sibling test below) that must stay
        // in lockstep. Sweeps every outer shape (atom + residual +
        // quote-family) so a drift on ANY arm surfaces immediately.
        let samples = [
            Sexp::Nil,
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("a")]),
            Sexp::symbol("foo"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::float(7.5),
            Sexp::boolean(true),
            Sexp::Quote(Box::new(Sexp::Nil)),
            Sexp::Quasiquote(Box::new(Sexp::Nil)),
            Sexp::Unquote(Box::new(Sexp::Nil)),
            Sexp::UnquoteSplice(Box::new(Sexp::Nil)),
        ];
        for s in &samples {
            assert_eq!(
                s.as_atom_kind(),
                s.as_atom().map(Atom::kind),
                "Sexp::as_atom_kind and Sexp::as_atom().map(Atom::kind) must agree at {s:?}",
            );
        }
    }

    #[test]
    fn sexp_as_atom_kind_agrees_with_shape_as_atom_kind_for_every_variant() {
        // COMPOSITION-LAW CONTRACT (shape-axis peer): `s.as_atom_kind()
        // == s.shape().as_atom_kind()` for every reachable Sexp outer
        // shape. Sibling to
        // `sexp_as_structural_kind_agrees_with_shape_as_structural_kind_for_every_variant`
        // on the atomic axis. Pre-lift the atomic carving marker at
        // the value level was reachable via this two-step composition
        // through the shape algebra; post-lift the new projection MUST
        // agree bit-for-bit — the substrate's (Sexp value, AtomKind
        // marker) pairing binds at THREE typed methods (Sexp::as_atom_kind,
        // Sexp::as_atom + Atom::kind composition, Sexp::shape +
        // SexpShape::as_atom_kind composition) that must ALL stay in
        // lockstep.
        let samples = [
            Sexp::Nil,
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("a")]),
            Sexp::symbol("foo"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::float(7.5),
            Sexp::boolean(true),
            Sexp::Quote(Box::new(Sexp::Nil)),
            Sexp::Quasiquote(Box::new(Sexp::Nil)),
            Sexp::Unquote(Box::new(Sexp::Nil)),
            Sexp::UnquoteSplice(Box::new(Sexp::Nil)),
        ];
        for s in &samples {
            assert_eq!(
                s.as_atom_kind(),
                s.shape().as_atom_kind(),
                "Sexp::as_atom_kind and Sexp::shape().as_atom_kind must agree at {s:?}",
            );
        }
    }

    #[test]
    fn sexp_as_atom_kind_partitions_outer_shapes_jointly_with_as_quote_form_and_as_structural_kind()
    {
        // PARTITION-TOTAL CONTRACT (value-level, marker-only axis):
        // pin that for every reachable Sexp outer shape, EXACTLY ONE
        // of `as_atom_kind`, `as_quote_form`, `as_structural_kind`
        // returns `Some(_)`. Post-lift ALL THREE carving-marker
        // projections at the value level form a partition of the
        // `Sexp` variant algebra using ONLY the marker-only siblings —
        // symmetric with the shape-level partition-total invariant
        // pinned by
        // `sexp_shape_partition_is_total_across_atom_quote_structural_carvings`
        // (in error.rs). The pre-existing value-level partition pin
        // `sexp_as_structural_kind_partitions_outer_shapes_jointly_with_as_atom_and_as_quote_form`
        // uses `as_atom().is_some()` on the atomic axis (the
        // structural-lift projection); THIS pin uses `as_atom_kind()
        // .is_some()` (the marker-only projection). Both partition
        // invariants must hold — they pin the atomic axis's TWO
        // value-level projections (structural + marker) as jointly
        // partition-consistent with the residual and quote-family
        // siblings. A regression that drifts any carving's
        // marker-only membership (an `as_atom_kind` arm that accepts
        // a non-atom, an `as_quote_form` arm that misses a quote-
        // family wrapper, an `as_structural_kind` arm that swaps its
        // Nil/List membership) surfaces here immediately.
        let samples = [
            Sexp::Nil,
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("a")]),
            Sexp::symbol("foo"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::float(7.5),
            Sexp::boolean(true),
            Sexp::Quote(Box::new(Sexp::Nil)),
            Sexp::Quasiquote(Box::new(Sexp::Nil)),
            Sexp::Unquote(Box::new(Sexp::Nil)),
            Sexp::UnquoteSplice(Box::new(Sexp::Nil)),
        ];
        for s in &samples {
            let hits = [
                s.as_atom_kind().is_some(),
                s.as_quote_form().is_some(),
                s.as_structural_kind().is_some(),
            ];
            let hit_count: usize = hits.iter().filter(|b| **b).count();
            assert_eq!(
                hit_count, 1,
                "value-level marker-only carvings must partition Sexp variants — {s:?} matched {hit_count} carvings (as_atom_kind/as_quote_form/as_structural_kind = {hits:?})",
            );
        }
    }

    #[test]
    fn sexp_as_atom_kind_composes_with_label_via_atom_kind_label() {
        // CROSS-PROJECTION COHERENCE: pin that
        // `s.as_atom_kind().map(AtomKind::label)` agrees with
        // `s.shape().label()` for every atomic Sexp (and returns
        // `None` for every non-atomic Sexp). Sibling to
        // `sexp_as_structural_kind_composes_with_label_via_structural_kind_label`
        // on the atomic axis. Composes the new value-level marker
        // projection with the closed-set `AtomKind::label` projection
        // (which itself composes through `sexp_shape().label()`) so
        // the label vocabulary stays load-bearing at ONE canonical
        // site (`SexpShape::label`) rather than a parallel per-
        // projection literal table.
        let atomic = [
            (Sexp::symbol("foo"), "symbol"),
            (Sexp::keyword("k"), "keyword"),
            (Sexp::string("s"), "string"),
            (Sexp::int(7), "int"),
            (Sexp::float(7.5), "float"),
            (Sexp::boolean(true), "bool"),
        ];
        for (sexp, expected_label) in &atomic {
            let via_carving = sexp.as_atom_kind().map(AtomKind::label);
            assert_eq!(
                via_carving,
                Some(*expected_label),
                "atomic-carving-marker label drifted at {sexp:?}"
            );
            assert_eq!(
                via_carving,
                Some(sexp.shape().label()),
                "as_atom_kind.map(label) must equal shape().label() for atomic sample {sexp:?}"
            );
        }
        for non_atomic in [
            Sexp::Nil,
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("a")]),
            Sexp::Quote(Box::new(Sexp::Nil)),
            Sexp::Quasiquote(Box::new(Sexp::Nil)),
            Sexp::Unquote(Box::new(Sexp::Nil)),
            Sexp::UnquoteSplice(Box::new(Sexp::Nil)),
        ] {
            assert_eq!(
                non_atomic.as_atom_kind().map(AtomKind::label),
                None,
                "non-atomic Sexp must project to None on as_atom_kind.map(label) — {non_atomic:?}"
            );
        }
    }

    #[test]
    fn sexp_as_unquote_form_projects_each_variant_to_canonical_unquote_form() {
        // PER-VARIANT TRUTH-TABLE (unquote-subset axis): pin byte-for-
        // byte per-Sexp-substitution-arm mapping — `Sexp::Unquote(inner)`
        // → `Some(UnquoteForm::Unquote)`, `Sexp::UnquoteSplice(inner)`
        // → `Some(UnquoteForm::Splice)`. Value-level peer of the shape-
        // level sweep
        // `as_unquote_form_projects_each_unquote_shape_to_canonical_unquote_form_and_rejects_non_unquote_shapes`
        // in error.rs — each substitution-wrapper Sexp value's carving-
        // marker projection must land on the matching UnquoteForm arm
        // the shape-level projection lands on. A future third UnquoteForm
        // variant (e.g. `,~` reverse-unquote) extends both this sweep +
        // the composition body via the as_unquote + QuoteForm::as_unquote_form
        // primitives, with rustc enforcing the match arms in lockstep.
        assert_eq!(
            Sexp::Unquote(Box::new(Sexp::symbol("x"))).as_unquote_form(),
            Some(UnquoteForm::Unquote)
        );
        assert_eq!(
            Sexp::UnquoteSplice(Box::new(Sexp::symbol("xs"))).as_unquote_form(),
            Some(UnquoteForm::Splice)
        );
        // Inner-payload invariance edge cases — pin the projection
        // ignores inner payload content entirely (it reads only the
        // outer wrapper variant discriminant), so a body that gates on
        // inner payload shape fails loudly.
        assert_eq!(
            Sexp::Unquote(Box::new(Sexp::Nil)).as_unquote_form(),
            Some(UnquoteForm::Unquote)
        );
        assert_eq!(
            Sexp::UnquoteSplice(Box::new(Sexp::List(vec![]))).as_unquote_form(),
            Some(UnquoteForm::Splice)
        );
        assert_eq!(
            Sexp::Unquote(Box::new(Sexp::List(vec![
                Sexp::symbol("nested"),
                Sexp::int(42),
            ])))
            .as_unquote_form(),
            Some(UnquoteForm::Unquote)
        );
    }

    #[test]
    fn sexp_as_unquote_form_rejects_non_unquote_subset_outer_shapes() {
        // KERNEL: every non-unquote-subset outer shape (Nil, every Atom
        // variant, List, AND the two non-substitution quote-family
        // wrappers `Sexp::Quote` and `Sexp::Quasiquote`) projects to
        // `None`. Sibling kernel-pin to
        // `sexp_as_atom_kind_rejects_non_atom_outer_shapes` and
        // `sexp_as_structural_kind_rejects_non_structural_outer_shapes`
        // on the substitution axis. The two non-substitution quote-
        // family wrappers ARE quote-family (`as_quote_form` accepts
        // them) but NOT substitution-subset (`as_unquote_form` must
        // reject them) — pin the 2-of-4 subset gate operates at the
        // value level exactly as the shape-level
        // `QuoteForm::as_unquote_form` gate operates on the closed-set
        // marker enum.
        for non_unquote in [
            Sexp::Nil,
            Sexp::symbol("foo"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::float(7.5),
            Sexp::boolean(true),
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("a")]),
            Sexp::Quote(Box::new(Sexp::Nil)),
            Sexp::Quasiquote(Box::new(Sexp::Nil)),
        ] {
            assert_eq!(
                non_unquote.as_unquote_form(),
                None,
                "non-substitution-subset Sexp must project to None on as_unquote_form — {non_unquote:?}"
            );
        }
    }

    #[test]
    fn sexp_as_unquote_form_agrees_with_as_unquote_map_marker_for_every_variant() {
        // COMPOSITION-LAW CONTRACT (parent-projection peer): pin
        // `s.as_unquote_form() == s.as_unquote().map(|(uf, _)| uf)` for
        // every reachable Sexp outer shape. Pre-lift the substitution
        // carving marker at the value level was reachable via this
        // two-step composition through the parent [`Sexp::as_unquote`]
        // projection (discarding the wrapped inner); post-lift the new
        // marker-only projection MUST agree bit-for-bit — the
        // substrate's (Sexp value, UnquoteForm marker) pairing binds at
        // FOUR compositions (this parent-projection composition AND the
        // shape-axis composition AND the quote-family + subset-gate
        // composition, all pinned by the sibling tests below) that must
        // stay in lockstep. Sweeps every outer shape (atom + residual +
        // quote-family) so a drift on ANY arm surfaces immediately.
        let samples = [
            Sexp::Nil,
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("a")]),
            Sexp::symbol("foo"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::float(7.5),
            Sexp::boolean(true),
            Sexp::Quote(Box::new(Sexp::Nil)),
            Sexp::Quasiquote(Box::new(Sexp::Nil)),
            Sexp::Unquote(Box::new(Sexp::Nil)),
            Sexp::UnquoteSplice(Box::new(Sexp::Nil)),
        ];
        for s in &samples {
            assert_eq!(
                s.as_unquote_form(),
                s.as_unquote().map(|(uf, _)| uf),
                "Sexp::as_unquote_form and Sexp::as_unquote().map(|(uf, _)| uf) must agree at {s:?}",
            );
        }
    }

    #[test]
    fn sexp_as_unquote_form_agrees_with_shape_as_unquote_form_for_every_variant() {
        // COMPOSITION-LAW CONTRACT (shape-axis peer): `s.as_unquote_form()
        // == s.shape().as_unquote_form()` for every reachable Sexp outer
        // shape. Sibling to
        // `sexp_as_atom_kind_agrees_with_shape_as_atom_kind_for_every_variant`
        // and
        // `sexp_as_structural_kind_agrees_with_shape_as_structural_kind_for_every_variant`
        // on the substitution axis. Pre-lift the substitution carving
        // marker at the value level was reachable via this two-step
        // composition through the shape algebra; post-lift the new
        // projection MUST agree bit-for-bit — the substrate's (Sexp
        // value, UnquoteForm marker) pairing binds at FOUR typed methods
        // (Sexp::as_unquote_form, Sexp::as_unquote + `|(uf, _)| uf`
        // composition, Sexp::shape + SexpShape::as_unquote_form
        // composition, Sexp::as_quote_form +
        // QuoteForm::as_unquote_form composition) that must ALL stay
        // in lockstep.
        let samples = [
            Sexp::Nil,
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("a")]),
            Sexp::symbol("foo"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::float(7.5),
            Sexp::boolean(true),
            Sexp::Quote(Box::new(Sexp::Nil)),
            Sexp::Quasiquote(Box::new(Sexp::Nil)),
            Sexp::Unquote(Box::new(Sexp::Nil)),
            Sexp::UnquoteSplice(Box::new(Sexp::Nil)),
        ];
        for s in &samples {
            assert_eq!(
                s.as_unquote_form(),
                s.shape().as_unquote_form(),
                "Sexp::as_unquote_form and Sexp::shape().as_unquote_form must agree at {s:?}",
            );
        }
    }

    #[test]
    fn sexp_as_unquote_form_agrees_with_as_quote_form_and_quote_form_as_unquote_form_for_every_variant(
    ) {
        // COMPOSITION-LAW CONTRACT (parent-family + subset-gate peer):
        // pin `s.as_unquote_form() ==
        // s.as_quote_form().and_then(|(qf, _)| qf.as_unquote_form())`
        // for every reachable Sexp outer shape. Value-level peer of the
        // shape-level route
        // `as_unquote_form_routes_through_as_quote_form_and_quote_form_as_unquote_form_via_composition`
        // in error.rs — where that test pins the shape-level
        // `SexpShape::as_unquote_form` routes through the shape-level
        // `SexpShape::as_quote_form` + `QuoteForm::as_unquote_form`
        // subset gate, THIS test pins the value-level
        // `Sexp::as_unquote_form` routes through the value-level
        // `Sexp::as_quote_form` + the SAME subset gate. Pre-lift the
        // substitution carving marker at the value level was reachable
        // via this three-step composition through the parent quote-
        // family projection [`Sexp::as_quote_form`] composed with the
        // 2-of-4 subset gate [`QuoteForm::as_unquote_form`]; post-lift
        // the new marker-only projection MUST agree bit-for-bit — the
        // subset-gate composition (which the pre-existing
        // [`Sexp::as_unquote`] projection ALSO routes through, per its
        // body `let (qf, inner) = self.as_quote_form()?;
        // qf.as_unquote_form().map(|uf| (uf, inner))`) must land the
        // same marker as the new value-level projection.
        let samples = [
            Sexp::Nil,
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("a")]),
            Sexp::symbol("foo"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::float(7.5),
            Sexp::boolean(true),
            Sexp::Quote(Box::new(Sexp::Nil)),
            Sexp::Quasiquote(Box::new(Sexp::Nil)),
            Sexp::Unquote(Box::new(Sexp::Nil)),
            Sexp::UnquoteSplice(Box::new(Sexp::Nil)),
        ];
        for s in &samples {
            assert_eq!(
                s.as_unquote_form(),
                s.as_quote_form().and_then(|(qf, _)| qf.as_unquote_form()),
                "Sexp::as_unquote_form and Sexp::as_quote_form().and_then(|(qf, _)| qf.as_unquote_form()) must agree at {s:?}",
            );
        }
    }

    #[test]
    fn sexp_as_unquote_form_composes_with_marker_via_unquote_form_marker() {
        // CROSS-PROJECTION COHERENCE: pin that
        // `s.as_unquote_form().map(UnquoteForm::marker)` agrees with
        // `s.shape().label()` for every substitution-subset Sexp (and
        // returns `None` for every non-substitution-subset Sexp).
        // Sibling to `sexp_as_atom_kind_composes_with_label_via_atom_kind_label`
        // on the substitution axis. Composes the new value-level
        // marker projection with the closed-set `UnquoteForm::marker`
        // projection (which itself composes through
        // `to_quote_form().prefix()` — see `UnquoteForm::marker`'s
        // docstring for the composition route) so the marker vocabulary
        // (`","` / `",@"`) stays load-bearing at ONE canonical site
        // (`QuoteForm::prefix`'s Unquote/UnquoteSplice arms) rather
        // than a parallel per-projection literal table.
        //
        // Note: `UnquoteForm::marker` returns the READER prefix (`,` or
        // `,@`) which is ALSO the canonical `SexpShape::label` for the
        // Unquote / UnquoteSplice arms — the shape-label vocabulary
        // was pinned to the reader-prefix vocabulary in the
        // `SexpShape::label` truth-table (Unquote → "unquote",
        // UnquoteSplice → "unquote-splice"). This test uses
        // `UnquoteForm::marker` = reader prefix directly (`,` /
        // `,@`), NOT the shape label — the two are distinct
        // vocabularies, both derived from the closed-set carving
        // marker, both stable across the lift.
        let substitution = [
            (
                Sexp::Unquote(Box::new(Sexp::symbol("x"))),
                UnquoteForm::Unquote,
            ),
            (
                Sexp::UnquoteSplice(Box::new(Sexp::symbol("xs"))),
                UnquoteForm::Splice,
            ),
        ];
        for (sexp, expected_uf) in &substitution {
            let via_carving = sexp.as_unquote_form().map(UnquoteForm::marker);
            assert_eq!(
                via_carving,
                Some(expected_uf.marker()),
                "substitution-carving-marker string drifted at {sexp:?}"
            );
        }
        for non_substitution in [
            Sexp::Nil,
            Sexp::symbol("foo"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::float(7.5),
            Sexp::boolean(true),
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("a")]),
            Sexp::Quote(Box::new(Sexp::Nil)),
            Sexp::Quasiquote(Box::new(Sexp::Nil)),
        ] {
            assert_eq!(
                non_substitution.as_unquote_form().map(UnquoteForm::marker),
                None,
                "non-substitution-subset Sexp must project to None on as_unquote_form.map(marker) — {non_substitution:?}"
            );
        }
    }

    #[test]
    fn sexp_as_unquote_form_narrows_as_quote_form_to_substitution_subset() {
        // SUBSET-GATE CONTRACT (value-level): pin that at every
        // reachable Sexp outer shape, `as_unquote_form().is_some()`
        // implies `as_quote_form().is_some()` (subset containment) AND
        // `as_quote_form().is_some() && !as_unquote_form().is_some()`
        // holds exactly for the two non-substitution quote-family
        // wrappers (`Sexp::Quote` and `Sexp::Quasiquote`) — the 2-of-4
        // subset gate at the VALUE level, symmetric with the shape-
        // level subset gate pinned by the sibling
        // `QuoteForm::as_unquote_form` truth-table in error.rs. Pins the
        // (substitution-subset ⊂ quote-family) inclusion as an invariant
        // on the value algebra so a regression that widens
        // `as_unquote_form` beyond its 2-of-4 subset (e.g. an emitter
        // that starts accepting `Sexp::Quote` as substitution) surfaces
        // immediately as a subset-inclusion drift.
        let samples = [
            (Sexp::Nil, false, false),
            (Sexp::List(vec![]), false, false),
            (Sexp::List(vec![Sexp::symbol("a")]), false, false),
            (Sexp::symbol("foo"), false, false),
            (Sexp::keyword("k"), false, false),
            (Sexp::string("s"), false, false),
            (Sexp::int(7), false, false),
            (Sexp::float(7.5), false, false),
            (Sexp::boolean(true), false, false),
            // Quote-family, NOT substitution-subset
            (Sexp::Quote(Box::new(Sexp::Nil)), true, false),
            (Sexp::Quasiquote(Box::new(Sexp::Nil)), true, false),
            // Quote-family AND substitution-subset
            (Sexp::Unquote(Box::new(Sexp::Nil)), true, true),
            (Sexp::UnquoteSplice(Box::new(Sexp::Nil)), true, true),
        ];
        for (s, quote_expected, unquote_expected) in &samples {
            let quote_hit = s.as_quote_form().is_some();
            let unquote_hit = s.as_unquote_form().is_some();
            assert_eq!(
                quote_hit, *quote_expected,
                "as_quote_form membership drifted at {s:?}"
            );
            assert_eq!(
                unquote_hit, *unquote_expected,
                "as_unquote_form membership drifted at {s:?}"
            );
            // Subset containment: substitution ⊂ quote-family.
            assert!(
                !unquote_hit || quote_hit,
                "subset containment violated at {s:?}: as_unquote_form Some but as_quote_form None",
            );
        }
    }

    #[test]
    fn sexp_as_quote_form_marker_projects_each_variant_to_canonical_quote_form() {
        // PER-VARIANT TRUTH-TABLE (quote-family axis): pin byte-for-byte
        // per-Sexp-quote-family-arm mapping — `Sexp::Quote(inner)`
        // → `Some(QuoteForm::Quote)`, `Sexp::Quasiquote(inner)`
        // → `Some(QuoteForm::Quasiquote)`, `Sexp::Unquote(inner)`
        // → `Some(QuoteForm::Unquote)`, `Sexp::UnquoteSplice(inner)`
        // → `Some(QuoteForm::UnquoteSplice)`. Value-level marker-only
        // peer of the pre-existing tuple projection
        // `Sexp::as_quote_form` — each quote-family-wrapper Sexp value's
        // carving-marker projection must land on the matching QuoteForm
        // arm the parent projection's tuple carries. A future fifth
        // QuoteForm variant (e.g. `,~` reverse-unquote) extends both
        // this sweep + the composition body via the as_quote_form
        // primitive, with rustc enforcing the match arms in lockstep.
        assert_eq!(
            Sexp::Quote(Box::new(Sexp::symbol("x"))).as_quote_form_marker(),
            Some(QuoteForm::Quote)
        );
        assert_eq!(
            Sexp::Quasiquote(Box::new(Sexp::symbol("x"))).as_quote_form_marker(),
            Some(QuoteForm::Quasiquote)
        );
        assert_eq!(
            Sexp::Unquote(Box::new(Sexp::symbol("x"))).as_quote_form_marker(),
            Some(QuoteForm::Unquote)
        );
        assert_eq!(
            Sexp::UnquoteSplice(Box::new(Sexp::symbol("xs"))).as_quote_form_marker(),
            Some(QuoteForm::UnquoteSplice)
        );
        // Inner-payload invariance edge cases — pin the projection
        // ignores inner payload content entirely (it reads only the
        // outer wrapper variant discriminant), so a body that gates on
        // inner payload shape fails loudly.
        assert_eq!(
            Sexp::Quote(Box::new(Sexp::Nil)).as_quote_form_marker(),
            Some(QuoteForm::Quote)
        );
        assert_eq!(
            Sexp::Quasiquote(Box::new(Sexp::List(vec![]))).as_quote_form_marker(),
            Some(QuoteForm::Quasiquote)
        );
        assert_eq!(
            Sexp::Unquote(Box::new(Sexp::List(vec![
                Sexp::symbol("nested"),
                Sexp::int(42),
            ])))
            .as_quote_form_marker(),
            Some(QuoteForm::Unquote)
        );
        assert_eq!(
            Sexp::UnquoteSplice(Box::new(Sexp::Quote(Box::new(Sexp::symbol("y")))))
                .as_quote_form_marker(),
            Some(QuoteForm::UnquoteSplice)
        );
    }

    #[test]
    fn sexp_as_quote_form_marker_rejects_non_quote_family_outer_shapes() {
        // KERNEL: every non-quote-family outer shape (Nil, every Atom
        // variant, List — empty and non-empty) projects to `None`.
        // Sibling kernel-pin to
        // `sexp_as_atom_kind_rejects_non_atom_outer_shapes`,
        // `sexp_as_structural_kind_rejects_non_structural_outer_shapes`,
        // and `sexp_as_unquote_form_rejects_non_unquote_subset_outer_shapes`
        // on the quote-family axis. A body that widens the projection to
        // any non-quote-family arm (e.g. `Sexp::List` starts returning
        // `Some(QuoteForm::Quote)`) surfaces as a `None` expectation
        // failure at the specific offending variant.
        for non_quote in [
            Sexp::Nil,
            Sexp::symbol("foo"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::float(7.5),
            Sexp::boolean(true),
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("a")]),
            Sexp::List(vec![Sexp::symbol("a"), Sexp::int(1)]),
        ] {
            assert_eq!(
                non_quote.as_quote_form_marker(),
                None,
                "non-quote-family Sexp must project to None on as_quote_form_marker — {non_quote:?}"
            );
        }
    }

    #[test]
    fn sexp_as_quote_form_marker_agrees_with_as_quote_form_map_marker_for_every_variant() {
        // COMPOSITION-LAW CONTRACT (parent-projection peer): pin
        // `s.as_quote_form_marker() == s.as_quote_form().map(|(qf, _)| qf)`
        // for every reachable Sexp outer shape. Pre-lift the quote-
        // family carving marker at the value level was reachable via
        // this two-step composition through the parent
        // [`Sexp::as_quote_form`] projection (discarding the wrapped
        // inner via `.map(|(qf, _)| qf)`); post-lift the new marker-
        // only projection MUST agree bit-for-bit — the substrate's
        // (Sexp value, QuoteForm marker) pairing binds at THREE
        // compositions (this parent-projection composition AND the
        // shape-axis composition, both pinned in this module, AND the
        // direct match in the new method's body) that must stay in
        // lockstep. Sweeps every outer shape (atom + residual +
        // quote-family) so a drift on ANY arm surfaces immediately.
        let samples = [
            Sexp::Nil,
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("a")]),
            Sexp::symbol("foo"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::float(7.5),
            Sexp::boolean(true),
            Sexp::Quote(Box::new(Sexp::Nil)),
            Sexp::Quasiquote(Box::new(Sexp::Nil)),
            Sexp::Unquote(Box::new(Sexp::Nil)),
            Sexp::UnquoteSplice(Box::new(Sexp::Nil)),
        ];
        for s in &samples {
            assert_eq!(
                s.as_quote_form_marker(),
                s.as_quote_form().map(|(qf, _)| qf),
                "Sexp::as_quote_form_marker and Sexp::as_quote_form().map(|(qf, _)| qf) must agree at {s:?}",
            );
        }
    }

    #[test]
    fn sexp_as_quote_form_marker_agrees_with_shape_as_quote_form_for_every_variant() {
        // COMPOSITION-LAW CONTRACT (shape-axis peer):
        // `s.as_quote_form_marker() == s.shape().as_quote_form()` for
        // every reachable Sexp outer shape. Sibling to
        // `sexp_as_atom_kind_agrees_with_shape_as_atom_kind_for_every_variant`,
        // `sexp_as_structural_kind_agrees_with_shape_as_structural_kind_for_every_variant`,
        // and `sexp_as_unquote_form_agrees_with_shape_as_unquote_form_for_every_variant`
        // on the quote-family axis. Pre-lift the quote-family carving
        // marker at the value level was reachable via this two-step
        // composition through the shape algebra (`shape().as_quote_form()`,
        // walking the full 12-variant [`SexpShape`](crate::error::SexpShape)
        // closed set to arrive at the 4-of-12 carving marker); post-
        // lift the new projection MUST agree bit-for-bit — the
        // substrate's (Sexp value, QuoteForm marker) pairing now binds
        // at ONE typed method on the value algebra, with both
        // compositions (this shape-axis peer and the parent-projection
        // peer pinned above) staying in lockstep.
        use crate::error::SexpShape;
        let samples = [
            Sexp::Nil,
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("a")]),
            Sexp::symbol("foo"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::float(7.5),
            Sexp::boolean(true),
            Sexp::Quote(Box::new(Sexp::Nil)),
            Sexp::Quasiquote(Box::new(Sexp::Nil)),
            Sexp::Unquote(Box::new(Sexp::Nil)),
            Sexp::UnquoteSplice(Box::new(Sexp::Nil)),
        ];
        for s in &samples {
            let via_value: Option<QuoteForm> = s.as_quote_form_marker();
            let via_shape: Option<QuoteForm> = SexpShape::as_quote_form(s.shape());
            assert_eq!(
                via_value, via_shape,
                "Sexp::as_quote_form_marker and Sexp::shape().as_quote_form must agree at {s:?}",
            );
        }
    }

    #[test]
    fn sexp_as_quote_form_marker_composes_with_prefix_via_quote_form_prefix() {
        // CROSS-PROJECTION COHERENCE: pin that
        // `s.as_quote_form_marker().map(QuoteForm::prefix)` agrees with
        // the reader-prefix vocabulary carried on [`QuoteForm::prefix`]
        // for every quote-family Sexp (and returns `None` for every
        // non-quote-family Sexp). Sibling to
        // `sexp_as_unquote_form_composes_with_marker_via_unquote_form_marker`
        // on the quote-family axis. Composes the new value-level marker
        // projection with the closed-set [`QuoteForm::prefix`]
        // projection so the reader/writer prefix vocabulary (`'` / `` ` ``
        // / `,` / `,@`) stays load-bearing at ONE canonical site
        // ([`QuoteForm::prefix`]'s four arms) rather than a parallel
        // per-projection literal table on the value algebra.
        let quote_family = [
            (Sexp::Quote(Box::new(Sexp::symbol("x"))), QuoteForm::Quote),
            (
                Sexp::Quasiquote(Box::new(Sexp::symbol("x"))),
                QuoteForm::Quasiquote,
            ),
            (
                Sexp::Unquote(Box::new(Sexp::symbol("x"))),
                QuoteForm::Unquote,
            ),
            (
                Sexp::UnquoteSplice(Box::new(Sexp::symbol("xs"))),
                QuoteForm::UnquoteSplice,
            ),
        ];
        for (sexp, expected_qf) in &quote_family {
            let via_carving = sexp.as_quote_form_marker().map(QuoteForm::prefix);
            assert_eq!(
                via_carving,
                Some(expected_qf.prefix()),
                "quote-family carving-marker prefix drifted at {sexp:?}"
            );
        }
        for non_quote in [
            Sexp::Nil,
            Sexp::symbol("foo"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::float(7.5),
            Sexp::boolean(true),
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("a")]),
        ] {
            assert_eq!(
                non_quote.as_quote_form_marker().map(QuoteForm::prefix),
                None,
                "non-quote-family Sexp must project to None on as_quote_form_marker.map(prefix) — {non_quote:?}"
            );
        }
    }

    #[test]
    fn sexp_as_quote_form_marker_extends_as_unquote_form_to_full_quote_family() {
        // SUPERSET-GATE CONTRACT (value-level): pin that at every
        // reachable Sexp outer shape,
        // `as_unquote_form().is_some()` implies
        // `as_quote_form_marker().is_some()` (the 2-of-12 substitution
        // subset is a proper subset of the 4-of-12 quote family) AND
        // `as_quote_form_marker().is_some() && !as_unquote_form().is_some()`
        // holds exactly for the two non-substitution quote-family
        // wrappers (`Sexp::Quote` and `Sexp::Quasiquote`) — the value-
        // level image of the 2-of-4 subset gate
        // [`QuoteForm::as_unquote_form`], mirroring
        // `sexp_as_unquote_form_narrows_as_quote_form_to_substitution_subset`
        // from the substitution-axis side. Pins the (substitution-
        // subset ⊂ quote-family) inclusion as an invariant on the
        // value algebra where the SUPERSET side is now a NAMED typed
        // method — so a regression that widens either projection
        // beyond its cell (e.g. `as_quote_form_marker` starts accepting
        // `Sexp::List`, or `as_unquote_form` starts accepting
        // `Sexp::Quote`) surfaces immediately as a subset-inclusion
        // drift. Also pin that
        // `as_unquote_form() == as_quote_form_marker().and_then(
        //     QuoteForm::as_unquote_form)` — the value-level projection
        // composes with the 2-of-4 subset gate at the marker algebra
        // level, so the substrate's (Sexp value, UnquoteForm marker)
        // pairing derives from the (Sexp value, QuoteForm marker)
        // pairing at ONE composition rather than two parallel value-
        // level projections.
        let samples = [
            (Sexp::Nil, false, false),
            (Sexp::List(vec![]), false, false),
            (Sexp::List(vec![Sexp::symbol("a")]), false, false),
            (Sexp::symbol("foo"), false, false),
            (Sexp::keyword("k"), false, false),
            (Sexp::string("s"), false, false),
            (Sexp::int(7), false, false),
            (Sexp::float(7.5), false, false),
            (Sexp::boolean(true), false, false),
            // Quote-family, NOT substitution-subset
            (Sexp::Quote(Box::new(Sexp::Nil)), true, false),
            (Sexp::Quasiquote(Box::new(Sexp::Nil)), true, false),
            // Quote-family AND substitution-subset
            (Sexp::Unquote(Box::new(Sexp::Nil)), true, true),
            (Sexp::UnquoteSplice(Box::new(Sexp::Nil)), true, true),
        ];
        for (s, quote_expected, unquote_expected) in &samples {
            let quote_hit = s.as_quote_form_marker().is_some();
            let unquote_hit = s.as_unquote_form().is_some();
            assert_eq!(
                quote_hit, *quote_expected,
                "as_quote_form_marker membership drifted at {s:?}"
            );
            assert_eq!(
                unquote_hit, *unquote_expected,
                "as_unquote_form membership drifted at {s:?}"
            );
            // Superset containment: substitution ⊂ quote-family.
            assert!(
                !unquote_hit || quote_hit,
                "subset containment violated at {s:?}: as_unquote_form Some but as_quote_form_marker None",
            );
            // Composition through the 2-of-4 subset gate:
            // `s.as_unquote_form() == s.as_quote_form_marker().and_then(QuoteForm::as_unquote_form)`.
            assert_eq!(
                s.as_unquote_form(),
                s.as_quote_form_marker()
                    .and_then(QuoteForm::as_unquote_form),
                "as_unquote_form and as_quote_form_marker + QuoteForm::as_unquote_form composition disagree at {s:?}",
            );
        }
    }

    #[test]
    fn sexp_shape_method_label_composes_with_sexp_type_name_for_every_outer_shape() {
        // COMPOSITION-LAW CONTRACT: `s.shape().label() ==
        // crate::domain::sexp_type_name(&s)` for every reachable Sexp
        // outer shape. Post-lift `sexp_type_name` routes through
        // `s.shape().label()` directly (no longer through the free-
        // function `sexp_shape`). Pin the composition law so a future
        // refactor that drifts either projection (e.g. a label typo
        // in `SexpShape::label`, a change in `sexp_type_name`'s
        // delegation) surfaces here immediately.
        let samples = [
            Sexp::Nil,
            Sexp::symbol("foo"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::float(7.5),
            Sexp::boolean(true),
            Sexp::List(vec![]),
            Sexp::Quote(Box::new(Sexp::Nil)),
            Sexp::Quasiquote(Box::new(Sexp::Nil)),
            Sexp::Unquote(Box::new(Sexp::Nil)),
            Sexp::UnquoteSplice(Box::new(Sexp::Nil)),
        ];
        for s in &samples {
            assert_eq!(
                s.shape().label(),
                crate::domain::sexp_type_name(s),
                "Sexp::shape().label() must equal domain::sexp_type_name for {s:?}",
            );
        }
    }

    #[test]
    fn sexp_type_name_method_projects_each_outer_arm_to_canonical_label() {
        // PER-ARM CONTRACT: pin that the inherent `Sexp::type_name()`
        // method projects each reachable outer Sexp shape to its
        // canonical `&'static str` label. Pre-lift the projection
        // lived as a free function `domain::sexp_type_name`; post-
        // lift the canonical site is the inherent method on the
        // `Sexp` algebra and the free function delegates. A
        // regression that drifts a per-arm label (e.g. a typo in
        // `SexpShape::label`, a stale arm in `Sexp::shape`'s match,
        // a change in the body away from `self.shape().label()`)
        // surfaces here immediately. Sweeps every outer shape and
        // every atomic payload kind so all 8 `SexpShape` variants
        // are covered.
        assert_eq!(Sexp::Nil.type_name(), "nil");
        assert_eq!(Sexp::symbol("foo").type_name(), "symbol");
        assert_eq!(Sexp::keyword("k").type_name(), "keyword");
        assert_eq!(Sexp::string("s").type_name(), "string");
        assert_eq!(Sexp::int(7).type_name(), "int");
        assert_eq!(Sexp::float(7.5).type_name(), "float");
        assert_eq!(Sexp::boolean(true).type_name(), "bool");
        assert_eq!(Sexp::List(vec![]).type_name(), "list");
        assert_eq!(Sexp::Quote(Box::new(Sexp::Nil)).type_name(), "quote");
        assert_eq!(
            Sexp::Quasiquote(Box::new(Sexp::Nil)).type_name(),
            "quasiquote",
        );
        assert_eq!(Sexp::Unquote(Box::new(Sexp::Nil)).type_name(), "unquote");
        assert_eq!(
            Sexp::UnquoteSplice(Box::new(Sexp::Nil)).type_name(),
            "unquote-splice",
        );
    }

    #[test]
    fn sexp_type_name_method_composes_through_shape_label_for_every_outer_shape() {
        // COMPOSITION-LAW CONTRACT: `s.type_name() == s.shape().label()`
        // for every reachable Sexp outer shape — the method body is
        // structurally derived through `Self::shape` + `SexpShape::label`
        // rather than re-matching `Sexp` arms directly. Pin the
        // composition law so a future refactor that re-inlines the
        // match (and gains its own drift surface) surfaces here
        // immediately. Sibling-shape pin to the existing
        // `sexp_shape_method_label_composes_with_sexp_type_name_for_every_outer_shape`
        // pin (which pins the inverse direction: the free function
        // routes through the inherent method).
        let samples = [
            Sexp::Nil,
            Sexp::symbol("foo"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::float(7.5),
            Sexp::boolean(true),
            Sexp::List(vec![]),
            Sexp::Quote(Box::new(Sexp::Nil)),
            Sexp::Quasiquote(Box::new(Sexp::Nil)),
            Sexp::Unquote(Box::new(Sexp::Nil)),
            Sexp::UnquoteSplice(Box::new(Sexp::Nil)),
        ];
        for s in &samples {
            assert_eq!(
                s.type_name(),
                s.shape().label(),
                "Sexp::type_name() must compose through Sexp::shape().label() for {s:?}",
            );
        }
    }

    #[test]
    fn sexp_type_name_method_agrees_with_domain_sexp_type_name_for_every_outer_shape() {
        // LIFTED-BOUNDARY CONTRACT: pin that the inherent
        // `Sexp::type_name()` method agrees with the free-function
        // delegate `crate::domain::sexp_type_name` for every
        // reachable outer shape. Pre-lift the dispatcher lived as a
        // free function in `domain.rs`; post-lift the canonical site
        // is the inherent method on the `Sexp` algebra and the free
        // function is a one-line delegate. Pin that the delegation
        // stays byte-for-byte equivalent across every outer arm so
        // a regression where the free function drifts from the
        // inherent method (or vice versa) surfaces here immediately.
        // Mirrors `sexp_witness_method_agrees_with_domain_sexp_witness_for_every_outer_shape`
        // for the canonical-label-only peer projection.
        let samples = [
            Sexp::Nil,
            Sexp::symbol("foo"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::int(-1),
            Sexp::float(7.5),
            Sexp::boolean(true),
            Sexp::boolean(false),
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("op"), Sexp::int(1), Sexp::int(2)]),
            Sexp::Quote(Box::new(Sexp::symbol("payload"))),
            Sexp::Quasiquote(Box::new(Sexp::List(vec![Sexp::symbol("foo")]))),
            Sexp::Unquote(Box::new(Sexp::symbol("x"))),
            Sexp::UnquoteSplice(Box::new(Sexp::symbol("xs"))),
        ];
        for s in &samples {
            assert_eq!(
                s.type_name(),
                crate::domain::sexp_type_name(s),
                "Sexp::type_name() must equal domain::sexp_type_name for {s:?}",
            );
        }
    }

    #[test]
    fn sexp_witness_method_pairs_shape_with_display_for_every_outer_shape() {
        // LIFTED-BOUNDARY CONTRACT: pin that the inherent
        // `Sexp::witness()` method projects each reachable outer Sexp
        // shape to a `SexpWitness` whose `shape` field equals
        // `s.shape()` AND whose `display` field equals
        // `s.to_string()` for every variant + payload combination.
        // Pre-lift the projection lived as a free function in
        // `domain.rs`; post-lift the canonical site is the inherent
        // method on the `Sexp` algebra. A regression where the method
        // drifts EITHER half of the joint identity (a stale `shape`
        // projection that re-inlines without composing through
        // `Sexp::shape`, a `display` projection that diverges from
        // `Sexp::Display`) surfaces here immediately. Sweeps every
        // outer shape, every atomic payload kind, and every
        // quote-family wrapper.
        let samples = [
            Sexp::Nil,
            Sexp::symbol("foo"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::int(-1),
            Sexp::float(7.5),
            Sexp::boolean(true),
            Sexp::boolean(false),
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("op"), Sexp::int(1), Sexp::int(2)]),
            Sexp::Quote(Box::new(Sexp::symbol("payload"))),
            Sexp::Quasiquote(Box::new(Sexp::List(vec![Sexp::symbol("foo")]))),
            Sexp::Unquote(Box::new(Sexp::symbol("x"))),
            Sexp::UnquoteSplice(Box::new(Sexp::symbol("xs"))),
        ];
        for s in &samples {
            let w = s.witness();
            assert_eq!(
                w.shape,
                s.shape(),
                "Sexp::witness().shape drifted from Sexp::shape() for {s:?}",
            );
            assert_eq!(
                w.display,
                s.to_string(),
                "Sexp::witness().display drifted from Sexp::Display for {s:?}",
            );
        }
    }

    #[test]
    fn sexp_witness_method_agrees_with_domain_sexp_witness_for_every_outer_shape() {
        // LIFTED-BOUNDARY CONTRACT: pin that the inherent
        // `Sexp::witness()` method agrees with the free-function
        // delegate `crate::domain::sexp_witness` for every reachable
        // outer shape. Pre-lift the dispatcher lived as a free
        // function in `domain.rs`; post-lift the canonical site is
        // the inherent method on the `Sexp` algebra and the free
        // function is a one-line delegate. Pin that the delegation
        // stays byte-for-byte equivalent across every outer arm so
        // a regression where the free function drifts from the
        // inherent method (or vice versa) surfaces here immediately.
        // Mirrors `sexp_shape_method_agrees_with_domain_sexp_shape_for_every_outer_shape`
        // for the joint-identity peer projection. Catches a future
        // "consolidation" that removes the free function without
        // updating the method, or vice versa.
        let samples = [
            Sexp::Nil,
            Sexp::symbol("foo"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::int(-1),
            Sexp::float(7.5),
            Sexp::float(0.0),
            Sexp::boolean(true),
            Sexp::boolean(false),
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("op"), Sexp::int(1), Sexp::int(2)]),
            Sexp::Quote(Box::new(Sexp::symbol("payload"))),
            Sexp::Quasiquote(Box::new(Sexp::List(vec![Sexp::symbol("foo")]))),
            Sexp::Unquote(Box::new(Sexp::symbol("x"))),
            Sexp::UnquoteSplice(Box::new(Sexp::symbol("xs"))),
        ];
        for s in &samples {
            let via_method = s.witness();
            let via_delegate = crate::domain::sexp_witness(s);
            assert_eq!(
                via_method.shape, via_delegate.shape,
                "Sexp::witness().shape drifted from domain::sexp_witness().shape at {s:?}",
            );
            assert_eq!(
                via_method.display, via_delegate.display,
                "Sexp::witness().display drifted from domain::sexp_witness().display at {s:?}",
            );
        }
    }

    #[test]
    fn sexp_witness_method_routes_through_shape_and_display_projections() {
        // PATH-UNIFORMITY CONTRACT: the lifted `Sexp::witness()` body
        // composes the two algebra-level projections `Sexp::shape()`
        // (structural identity) + `Sexp::Display` (renderable
        // identity) into ONE `SexpWitness::new(shape, display)`
        // value. Pin that the composition agrees bit-for-bit with
        // the direct `SexpWitness::new(s.shape(), s.to_string())`
        // construction across a sweep covering every outer shape.
        // A regression in EITHER projection direction (a
        // `Sexp::witness` arm that bypasses `Sexp::shape` and
        // re-inlines the dispatch, a `Sexp::witness` arm that
        // bypasses `Sexp::Display` and re-formats the literal) is
        // structurally impossible — the typed joint primitive
        // composes through the typed primitive halves once.
        // Sibling shape to `sexp_shape_method_routes_atom_arm_through_atom_kind_sexp_shape_projection`
        // for the joint-identity axis.
        let samples = [
            Sexp::Nil,
            Sexp::symbol("x"),
            Sexp::keyword("kw"),
            Sexp::string("text"),
            Sexp::int(0),
            Sexp::float(2.5),
            Sexp::boolean(true),
            Sexp::List(vec![Sexp::symbol("f"), Sexp::int(1)]),
            Sexp::Quote(Box::new(Sexp::symbol("q"))),
            Sexp::Quasiquote(Box::new(Sexp::symbol("qq"))),
            Sexp::Unquote(Box::new(Sexp::symbol("uq"))),
            Sexp::UnquoteSplice(Box::new(Sexp::symbol("uqs"))),
        ];
        for s in &samples {
            let via_method = s.witness();
            let via_composed = crate::error::SexpWitness::new(s.shape(), s.to_string());
            assert_eq!(
                via_method.shape, via_composed.shape,
                "Sexp::witness drifted shape from SexpWitness::new(s.shape(), s.to_string()) at {s:?}",
            );
            assert_eq!(
                via_method.display, via_composed.display,
                "Sexp::witness drifted display from SexpWitness::new(s.shape(), s.to_string()) at {s:?}",
            );
        }
    }

    #[test]
    fn sexp_witness_distinguishes_int_atom_from_symbol_with_identical_display() {
        // STRUCTURAL-IDENTITY CONTRACT: `Sexp::int(5)` and
        // `Sexp::symbol("5")` Display-render identically (`"5"`) but
        // are STRUCTURALLY DISTINCT — one is `SexpShape::Int`, the
        // other is `SexpShape::Symbol`. Pin that `Sexp::witness()`
        // carries the structural identity through the `shape` slot
        // so the rejection diagnostic distinguishes the two even
        // when the rendered literal collides. Mirrors the
        // free-function-delegate sibling test
        // `sexp_witness_distinguishes_int_atom_from_symbol_with_same_display`
        // in `domain.rs::tests` — that test pins the delegate; this
        // one pins the inherent method on the algebra. Both stay
        // load-bearing across the lifted boundary.
        let w_int = Sexp::int(5).witness();
        let w_sym = Sexp::symbol("5").witness();
        assert_eq!(
            w_int.display, w_sym.display,
            "display collision precondition"
        );
        assert_ne!(
            w_int.shape, w_sym.shape,
            "Sexp::witness must distinguish Int from Symbol via shape even when display collides",
        );
        assert_eq!(w_int.shape, crate::error::SexpShape::Int);
        assert_eq!(w_sym.shape, crate::error::SexpShape::Symbol);
    }

    #[test]
    fn sexp_as_x_family_routes_through_atom_as_x_for_every_atomic_variant() {
        // LIFTED-BOUNDARY CONTRACT: pin that the six `Sexp::as_X`
        // consumer-side projections equal the two-step composition
        // `s.as_atom().and_then(Atom::as_X)` for every atomic payload
        // variant. Pre-lift the six methods opened the same `Self::Atom
        // (Atom::X(s)) => Some(s)` inline arm; post-lift they delegate
        // through the typed projection family on the closed-set `Atom`
        // algebra. A regression that drifts the outer arm (e.g. re-
        // inlines one variant's match without updating the typed
        // projection) surfaces as an inequality here. Sweeps every
        // atomic variant + every consumer projection, AND pins the
        // `Sexp::as_float` widening specialization (`Atom::Int(n)` →
        // `Some(n as f64)`) lives at the consumer layer.
        let cases: &[Atom] = &[
            Atom::Symbol("name".into()),
            Atom::Keyword("kw".into()),
            Atom::Str("body".into()),
            Atom::Int(42),
            Atom::Int(-7),
            Atom::Float(1.5),
            Atom::Float(1.0),
            Atom::Bool(true),
            Atom::Bool(false),
        ];
        for atom in cases {
            let sexp = Sexp::Atom(atom.clone());

            assert_eq!(
                sexp.as_symbol(),
                sexp.as_atom().and_then(Atom::as_symbol),
                "Sexp::as_symbol drifted from as_atom().and_then(Atom::as_symbol) for {atom:?}",
            );
            assert_eq!(
                sexp.as_keyword(),
                sexp.as_atom().and_then(Atom::as_keyword),
                "Sexp::as_keyword drifted from as_atom().and_then(Atom::as_keyword) for {atom:?}",
            );
            assert_eq!(
                sexp.as_string(),
                sexp.as_atom().and_then(Atom::as_string),
                "Sexp::as_string drifted from as_atom().and_then(Atom::as_string) for {atom:?}",
            );
            assert_eq!(
                sexp.as_int(),
                sexp.as_atom().and_then(Atom::as_int),
                "Sexp::as_int drifted from as_atom().and_then(Atom::as_int) for {atom:?}",
            );
            assert_eq!(
                sexp.as_bool(),
                sexp.as_atom().and_then(Atom::as_bool),
                "Sexp::as_bool drifted from as_atom().and_then(Atom::as_bool) for {atom:?}",
            );

            // `Sexp::as_float` specializes through the widening composition
            // `s.as_atom().and_then(|a| a.as_float().or_else(|| a.as_int()
            // .map(|n| n as f64)))` so the algebra-level `Atom::as_float`
            // stays strict and the typed-identity distinction `Int(1)` vs
            // `Float(1.0)` is preserved at the algebra layer.
            let expected_float = sexp
                .as_atom()
                .and_then(|a| a.as_float().or_else(|| a.as_int().map(|n| n as f64)));
            assert_eq!(
                sexp.as_float(),
                expected_float,
                "Sexp::as_float drifted from widening composition for {atom:?}",
            );
        }
    }

    #[test]
    fn sexp_as_float_widens_int_to_float_at_consumer_layer_only() {
        // CONSUMER-LAYER WIDENING CONTRACT: pin that the `Sexp::as_float`
        // consumer DOES widen `Atom::Int(n)` to `Some(n as f64)` (the
        // load-bearing widening at the numeric-kwarg boundary the
        // `extract_float` extractor depends on) AND that the algebra-
        // level `Atom::as_float` does NOT (the strict typed-identity
        // discipline pinned at `atom_as_float_returns_payload_iff_float_variant_strict_no_int_widening`).
        // The widening lives at the CONSUMER layer ONLY; a regression
        // that drifts the widening into the algebra layer (e.g. re-
        // adds an `Atom::Int(n) => Some(n as f64)` arm at
        // `Atom::as_float`) would silently coerce `Int(1)` slots into
        // the `Float` track at every `Atom` consumer that bypasses
        // `Sexp`, breaking the typed-identity discipline at the
        // canonical-form rendering surfaces (Display, JSON,
        // iac-forge).
        let int_sexp = Sexp::int(7);
        assert_eq!(
            int_sexp.as_float(),
            Some(7.0),
            "Sexp::as_float must widen Atom::Int to f64 at the consumer layer",
        );
        assert_eq!(
            Atom::Int(7).as_float(),
            None,
            "Atom::as_float must stay strict at the algebra layer",
        );

        // The widening sweeps the int domain — pin a few canonical
        // values so a regression that loses the `as f64` cast (e.g. an
        // accidental `usize` round-trip) surfaces directly.
        for n in [-42i64, -1, 0, 1, 42] {
            assert_eq!(
                Sexp::int(n).as_float(),
                Some(n as f64),
                "Sexp::as_float widening drifted for Int({n})",
            );
        }
    }

    #[test]
    fn sexp_to_json_method_projects_each_outer_arm_to_canonical_json() {
        // LIFTED-BOUNDARY CONTRACT: pin that the inherent
        // `Sexp::to_json()` method projects each reachable outer Sexp
        // shape to a `serde_json::Value` byte-identical to the
        // pre-lift inline rule at `crate::domain::sexp_to_json`'s
        // outer match — Nil → Null, Atom → `Atom::to_json` (composed
        // through the typed-algebra projection), List(kwargs) →
        // Object keyed by kebab→camel, List(other) → Array, and
        // each quote-family wrapper → recurse on inner (the wrapper
        // is structurally erased into JSON). A regression that
        // drifts ANY outer arm (e.g. emits Nil as `"nil"` instead of
        // Null, swaps List(kwargs) for Array unconditionally, drops
        // a quote-family arm's recursion) surfaces here. Pre-lift
        // the dispatcher lived as a free function in `domain.rs`;
        // post-lift the canonical site is the inherent method on
        // the `Sexp` algebra (same posture as the prior
        // `Sexp::shape` (121bb60) and `Sexp::witness` (a427e3b)
        // lifts).
        assert_eq!(
            Sexp::Nil.to_json().expect("nil to_json"),
            serde_json::Value::Null,
        );
        assert_eq!(
            Sexp::symbol("foo").to_json().expect("symbol to_json"),
            serde_json::Value::String("foo".into()),
        );
        assert_eq!(
            Sexp::keyword("k").to_json().expect("keyword to_json"),
            serde_json::Value::String(":k".into()),
        );
        assert_eq!(
            Sexp::string("body").to_json().expect("string to_json"),
            serde_json::Value::String("body".into()),
        );
        assert_eq!(
            Sexp::int(7).to_json().expect("int to_json"),
            serde_json::json!(7),
        );
        assert_eq!(
            Sexp::float(1.5).to_json().expect("float to_json"),
            serde_json::json!(1.5),
        );
        assert_eq!(
            Sexp::boolean(true).to_json().expect("true to_json"),
            serde_json::Value::Bool(true),
        );

        // List(kwargs) → Object with kebab→camel keys.
        let kwargs = Sexp::List(vec![
            Sexp::keyword("point-type"),
            Sexp::symbol("Gate"),
            Sexp::keyword("must-reach"),
            Sexp::boolean(true),
        ]);
        assert_eq!(
            kwargs.to_json().expect("kwargs list to_json"),
            serde_json::json!({"pointType": "Gate", "mustReach": true}),
        );

        // List(non-kwargs) → Array.
        let arr = Sexp::List(vec![Sexp::int(1), Sexp::int(2), Sexp::int(3)]);
        assert_eq!(
            arr.to_json().expect("non-kwargs list to_json"),
            serde_json::json!([1, 2, 3]),
        );

        // Empty list → Array (kwargs guard rejects empty lists).
        let empty = Sexp::List(vec![]);
        assert_eq!(
            empty.to_json().expect("empty list to_json"),
            serde_json::json!([]),
        );

        // Quote-family wrappers strip and recurse.
        let payload = Sexp::List(vec![Sexp::keyword("k"), Sexp::int(42)]);
        let expected = serde_json::json!({"k": 42});
        for wrapped in [
            Sexp::Quote(Box::new(payload.clone())),
            Sexp::Quasiquote(Box::new(payload.clone())),
            Sexp::Unquote(Box::new(payload.clone())),
            Sexp::UnquoteSplice(Box::new(payload.clone())),
        ] {
            assert_eq!(
                wrapped.to_json().expect("quote-family to_json"),
                expected,
                "quote-family wrapper {wrapped:?} drifted from inner-recursion shape",
            );
        }
    }

    #[test]
    fn sexp_to_json_method_agrees_with_domain_sexp_to_json_for_every_outer_shape() {
        // LIFTED-BOUNDARY CONTRACT: pin that the inherent
        // `Sexp::to_json()` method agrees with the free-function
        // delegate `crate::domain::sexp_to_json` for every reachable
        // outer shape. Pre-lift the dispatcher lived as a free
        // function in `domain.rs`; post-lift the canonical site is
        // the inherent method and the free function is a one-line
        // delegate. Pin that the delegation stays byte-for-byte
        // equivalent across every outer arm so a regression where
        // the free function drifts from the inherent method (or
        // vice versa) surfaces here immediately. Mirrors
        // `sexp_shape_method_agrees_with_domain_sexp_shape_for_every_outer_shape`
        // and
        // `sexp_witness_method_agrees_with_domain_sexp_witness_for_every_outer_shape`
        // for the JSON canonical-form projection peer.
        let samples = [
            Sexp::Nil,
            Sexp::symbol("foo"),
            Sexp::keyword("k"),
            Sexp::string("s"),
            Sexp::int(7),
            Sexp::int(-1),
            Sexp::float(7.5),
            Sexp::float(0.0),
            Sexp::boolean(true),
            Sexp::boolean(false),
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("op"), Sexp::int(1), Sexp::int(2)]),
            Sexp::List(vec![
                Sexp::keyword("point-type"),
                Sexp::symbol("Gate"),
                Sexp::keyword("must-reach"),
                Sexp::boolean(true),
            ]),
            Sexp::Quote(Box::new(Sexp::symbol("payload"))),
            Sexp::Quasiquote(Box::new(Sexp::List(vec![Sexp::symbol("foo")]))),
            Sexp::Unquote(Box::new(Sexp::symbol("x"))),
            Sexp::UnquoteSplice(Box::new(Sexp::symbol("xs"))),
        ];
        for s in &samples {
            let via_method = s.to_json().expect("method projection must succeed");
            let via_delegate =
                crate::domain::sexp_to_json(s).expect("delegate projection must succeed");
            assert_eq!(
                via_method, via_delegate,
                "Sexp::to_json drifted from domain::sexp_to_json at {s:?}",
            );
        }
    }

    #[test]
    fn sexp_to_json_method_routes_atom_arm_through_atom_to_json() {
        // PATH-UNIFORMITY CONTRACT: the lifted `Sexp::to_json()`
        // body composes through the typed-algebra primitive
        // [`Atom::to_json`] at the Atom arm — `Sexp::Atom(a).to_json()
        // == Ok(a.to_json())` for every atomic payload variant. A
        // regression in EITHER direction (a `Sexp::to_json` arm
        // that bypasses `Atom::to_json` and re-inlines a per-variant
        // mapping, or an `Atom::to_json` projection that diverges
        // from the rendering the outer arm depends on) is
        // structurally impossible — the typed JSON primitive composes
        // through the typed primitive halves once. Sibling-shape pin
        // to `sexp_to_json_atom_arms_route_through_atom_to_json` in
        // `domain.rs` (the free-function-delegate peer that pinned
        // the same identity at the pre-lift site).
        let cases: &[Atom] = &[
            Atom::Symbol("name".into()),
            Atom::Keyword("kw".into()),
            Atom::Str("body".into()),
            Atom::Int(7),
            Atom::Int(-3),
            Atom::Float(2.5),
            Atom::Float(1.0),
            Atom::Bool(true),
            Atom::Bool(false),
        ];
        for atom in cases {
            let via_method = Sexp::Atom(atom.clone())
                .to_json()
                .expect("atom must serialize through Sexp::to_json");
            let via_atom = atom.to_json();
            assert_eq!(
                via_method, via_atom,
                "Sexp::to_json Atom arm drifted from Atom::to_json for {atom:?}",
            );
        }
    }

    #[test]
    fn sexp_to_json_method_routes_quote_family_arms_through_inner_recursion() {
        // PATH-UNIFORMITY CONTRACT: the four quote-family arms each
        // strip the wrapper and recurse on the projected `inner`
        // (via `Self::expect_quote_form`), NOT on the outer `self`.
        // Pin that this binding semantic is observable across all
        // four wrappers: `wrap_qf(inner).to_json() == inner.to_json()`
        // for every `QuoteForm` variant. A regression that lifted
        // the recursion onto `self` (the outer wrapper) instead of
        // the projected inner would infinite-loop or surface as a
        // structural mismatch here. Sibling shape to
        // `sexp_to_json_routes_quote_family_arms_through_as_quote_form_typed_marker`
        // in `domain.rs::tests` (the free-function-delegate peer)
        // — both pin the same invariant at the lifted boundary.
        let inner = Sexp::List(vec![Sexp::keyword("k"), Sexp::int(42)]);
        let expected = inner.to_json().expect("inner serializes");
        for wrap in [
            Sexp::Quote(Box::new(inner.clone())),
            Sexp::Quasiquote(Box::new(inner.clone())),
            Sexp::Unquote(Box::new(inner.clone())),
            Sexp::UnquoteSplice(Box::new(inner.clone())),
        ] {
            let via_method = wrap
                .to_json()
                .expect("quote-family wrapper must serialize via Sexp::to_json");
            assert_eq!(
                via_method, expected,
                "Sexp::to_json drifted from inner-recursion shape at {wrap:?}",
            );
        }
    }

    #[test]
    fn sexp_to_json_method_rejects_duplicate_kwargs_at_lifted_boundary() {
        // TYPED-ENTRY CONTRACT: the duplicate-keyword rejection at
        // the kwargs-list arm fires at the inherent method directly,
        // not at the delegate — the canonical typed-entry gate lives
        // on the algebra. Pin that two `:k` entries in the same
        // kwargs list collapse to `LispError::DuplicateKwarg { key }`
        // with `key == "notify-ref"` (the kebab spelling, before
        // kebab→camel conversion — the diagnostic surface matches
        // the spelling the operator typed). The error type
        // discriminator is checked via debug-format substring so a
        // future LispError variant rename doesn't silently break
        // this pin. Mirrors `sexp_to_json_nested_duplicate_emits_structural_variant`
        // in `domain.rs::tests` (the free-function delegate peer at
        // the pre-lift site) at the lifted boundary.
        let dup = Sexp::List(vec![
            Sexp::keyword("notify-ref"),
            Sexp::string("a"),
            Sexp::keyword("notify-ref"),
            Sexp::string("b"),
        ]);
        let err = dup.to_json().expect_err("duplicate kwarg must reject");
        let rendered = format!("{err:?}");
        assert!(
            rendered.contains("DuplicateKwarg"),
            "expected DuplicateKwarg variant, got {rendered}",
        );
        assert!(
            rendered.contains("notify-ref"),
            "expected diagnostic to name the kebab-spelled duplicate key, got {rendered}",
        );
    }

    // ── Sexp::from_json: the inverse JSON-projection on the algebra ─────
    //
    // `Sexp::from_json` lifts the `domain::json_to_sexp` free-function
    // dispatcher onto the inherent-method canonical site on the [`Sexp`]
    // algebra — sibling-lift posture to the prior `sexp_to_json` →
    // `Sexp::to_json` (875ee3b), `sexp_witness` → `Sexp::witness`
    // (a427e3b), and `sexp_shape` → `Sexp::shape` (121bb60). The tests
    // below pin the per-arm contract on the new canonical site directly;
    // the free function delegates so the existing path-uniformity tests
    // at `domain::json_to_sexp_*` continue to pass post-lift unchanged.

    #[test]
    fn sexp_from_json_projects_each_outer_arm_to_canonical_sexp() {
        // LIFTED-BOUNDARY CONTRACT: pin that the inherent
        // `Sexp::from_json` associated function projects each reachable
        // outer `serde_json::Value` shape to a `Sexp` byte-identical to
        // the pre-lift inline rule at `crate::domain::json_to_sexp`'s
        // outer match — Null → Nil, Bool → boolean, Number(i64) → int,
        // Number(f64-only) → float, String → string, Array → List(map),
        // Object → List of alternating `:k v` pairs in iteration order
        // via `camel_to_kebab` on each key. A regression that drifts ANY
        // outer arm (e.g. emits Null as Sexp::string(""), swaps Array
        // for a kwargs-shaped List, drops the camel→kebab projection on
        // Object keys) surfaces here. Pre-lift the dispatcher lived as a
        // free function in `domain.rs`; post-lift the canonical site is
        // the inherent associated function on the `Sexp` algebra.
        assert_eq!(Sexp::from_json(&serde_json::Value::Null), Sexp::Nil);
        assert_eq!(
            Sexp::from_json(&serde_json::Value::Bool(true)),
            Sexp::boolean(true),
        );
        assert_eq!(
            Sexp::from_json(&serde_json::Value::Bool(false)),
            Sexp::boolean(false),
        );
        assert_eq!(Sexp::from_json(&serde_json::json!(42)), Sexp::int(42));
        assert_eq!(Sexp::from_json(&serde_json::json!(-1)), Sexp::int(-1));
        assert_eq!(Sexp::from_json(&serde_json::json!(0)), Sexp::int(0));
        // Float that does NOT fit i64 falls through to the float arm.
        assert_eq!(Sexp::from_json(&serde_json::json!(1.5)), Sexp::float(1.5));
        assert_eq!(
            Sexp::from_json(&serde_json::Value::String("body".into())),
            Sexp::string("body"),
        );

        // Array → List with each element projected recursively.
        let arr = serde_json::json!([1, "x", true, null]);
        assert_eq!(
            Sexp::from_json(&arr),
            Sexp::List(vec![
                Sexp::int(1),
                Sexp::string("x"),
                Sexp::boolean(true),
                Sexp::Nil,
            ]),
        );

        // Object → List of alternating `:k v` pairs, JSON key projected
        // through camel→kebab so the kwarg authoring shape is recovered.
        // The iteration order of the JSON object is implementation-
        // defined here (no `preserve_order` feature on `serde_json`), so
        // pin the SET of (kebab-key, value) pairs rather than the
        // sequence — order-uniformity vs. the delegate is pinned in the
        // path-uniformity test below.
        let obj = serde_json::json!({"pointType": "Gate", "mustReach": true});
        let result = Sexp::from_json(&obj);
        let items = match &result {
            Sexp::List(items) => items.clone(),
            other => panic!("expected List, got {other:?}"),
        };
        assert_eq!(items.len(), 4);
        let mut pairs: Vec<(String, Sexp)> = items
            .chunks_exact(2)
            .map(|c| (c[0].as_keyword().expect("kw").to_string(), c[1].clone()))
            .collect();
        pairs.sort_by(|a, b| a.0.cmp(&b.0));
        assert_eq!(
            pairs,
            vec![
                ("must-reach".to_string(), Sexp::boolean(true)),
                ("point-type".to_string(), Sexp::string("Gate")),
            ],
        );
    }

    #[test]
    fn sexp_from_json_agrees_with_domain_json_to_sexp_for_every_outer_shape() {
        // PATH-UNIFORMITY GUARD: pin that the free-function delegate
        // `crate::domain::json_to_sexp(v) == Sexp::from_json(v)` for
        // every reachable `serde_json::Value` outer shape. Post-lift the
        // free function delegates to the inherent associated function;
        // this test pins the delegation byte-for-byte so a future
        // regression that drifts the delegate (e.g. inlines a stale
        // pre-lift body, swaps the iteration order at one site) fires
        // here, parallel to `sexp_to_json_method_agrees_with_domain_
        // sexp_to_json_for_every_outer_shape`'s posture for the forward
        // direction.
        let shapes = [
            serde_json::Value::Null,
            serde_json::Value::Bool(true),
            serde_json::Value::Bool(false),
            serde_json::json!(7),
            serde_json::json!(-3),
            serde_json::json!(2.5),
            serde_json::Value::String("body".into()),
            serde_json::json!([1, 2, 3]),
            serde_json::json!({"camelCase": "v", "another-key": 5}),
            serde_json::json!({"nested": {"inner": [1, 2]}}),
            serde_json::json!([]),
            serde_json::json!({}),
        ];
        for v in &shapes {
            assert_eq!(
                Sexp::from_json(v),
                crate::domain::json_to_sexp(v),
                "delegate drifted from inherent associated function for {v}",
            );
        }
    }

    #[test]
    fn sexp_from_json_object_keys_route_through_camel_to_kebab() {
        // KEY-PROJECTION CONTRACT: pin that JSON object keys land in
        // the resulting `Sexp::List` as `Sexp::keyword(camel_to_kebab(k))`
        // — the inverse of `Sexp::to_json`'s kebab→camel projection.
        // A regression that drops the projection (writes the JSON key
        // verbatim, breaking the kwarg round-trip), substitutes a
        // different camel→kebab implementation at this site, or routes
        // through `kebab_to_camel` (the wrong direction) surfaces here.
        let obj = serde_json::json!({
            "pointType": 1,
            "mustReach": 2,
            "already-kebab": 3,
            "withABC": 4,
        });
        let result = Sexp::from_json(&obj);
        let items = match &result {
            Sexp::List(items) => items,
            other => panic!("expected List, got {other:?}"),
        };
        // Even-position elements are keywords; odd-position elements are
        // values. Pin the keyword spellings against the camel→kebab
        // projection (camel boundaries become `-`; consecutive uppercase
        // each get a leading `-` per the implementation in
        // `domain::camel_to_kebab`).
        let kws: Vec<&str> = items
            .iter()
            .step_by(2)
            .map(|s| s.as_keyword().expect("even position must be keyword"))
            .collect();
        // Match the order JSON preserve_order gives us — sortable for
        // stability; the contract is just that each key landed through
        // camel→kebab, not the insertion order itself.
        let mut sorted = kws.clone();
        sorted.sort();
        assert_eq!(
            sorted,
            vec!["already-kebab", "must-reach", "point-type", "with-a-b-c"],
        );
    }

    #[test]
    fn sexp_from_json_number_arm_routes_through_atom_from_json_number() {
        // LIFTED-BOUNDARY CONTRACT: pin that the outer `Sexp::from_json`'s
        // `serde_json::Value::Number(_)` arm delegates through the
        // typed-algebra method `Atom::from_json_number` for every
        // reachable `serde_json::Number` shape (i64-backed, finite
        // f64-backed, and the empty structural-impossibility residual —
        // although `serde_json::Number`'s closed-set discriminator
        // excludes the last case in practice, so it's exercised only
        // via the direct algebra method). Pre-lift the outer arm
        // carried its own inline three-branch cascade (`n.as_i64` then
        // `n.as_f64` then `Self::int(0)` typed floor); post-lift the
        // arm collapses to `Self::Atom(Atom::from_json_number(n))` and
        // the per-variant numeric-axis body binds at ONE typed
        // projection on the [`Atom`] algebra. A regression that drifts
        // the outer arm (e.g. re-inlines ONE variant's rendering
        // without updating `Atom::from_json_number`, or introduces a
        // spurious f64→JValue::Null re-wrap) surfaces as an inequality
        // here. The sweep covers every Number shape the substrate
        // encounters in practice.
        //
        // Sibling-shape pin to `sexp_to_json_atom_arms_route_through_atom_to_json`
        // (in `crate::domain::tests`) — where that pin closes the
        // FORWARD `Sexp::Atom → JValue` routing through
        // `Atom::to_json`, THIS pin closes the INVERSE
        // `JValue::Number → Sexp::Atom` routing through
        // `Atom::from_json_number`. Together the two pins pin the
        // round-trip closure `Sexp::from_json ∘ Sexp::to_json` for
        // the numeric-axis subset AT the algebra layer rather than
        // per consumer.
        let number_shapes: Vec<serde_json::Number> = vec![
            0i64.into(),
            1i64.into(),
            (-1i64).into(),
            42i64.into(),
            i64::MAX.into(),
            i64::MIN.into(),
            serde_json::Number::from_f64(1.5).unwrap(),
            serde_json::Number::from_f64(-2.5).unwrap(),
            serde_json::Number::from_f64(1.234_567_890_123).unwrap(),
        ];
        for n in &number_shapes {
            let via_outer = Sexp::from_json(&serde_json::Value::Number(n.clone()));
            let via_algebra = Sexp::Atom(Atom::from_json_number(n));
            assert_eq!(
                via_outer, via_algebra,
                "Sexp::from_json Number arm drifted from \
                 Sexp::Atom(Atom::from_json_number(n)) for {n:?}",
            );
        }
    }

    // ── Sexp::is_kwargs_list: the kwargs-shape predicate on the algebra ─
    //
    // `Sexp::is_kwargs_list` lifts the `pub(crate) domain::is_kwargs_list`
    // free function onto the inherent-method canonical site on the
    // [`Sexp`] algebra — sibling-shape predicate peer of [`Sexp::is_list`]
    // narrowing the structural witness to the kwargs-shaped sub-cohort.
    // The tests below pin the per-arm contract on the new canonical site
    // directly; the `pub(crate)` free function has zero remaining callers
    // post-lift and is removed in the same patch so the substrate's
    // "kwargs-shape predicate" lives at exactly one canonical site on the
    // algebra rather than splitting across a `domain.rs` helper and the
    // `Sexp::to_json` call site.

    #[test]
    fn sexp_is_kwargs_list_method_returns_true_for_canonical_kwargs_shape() {
        // PER-ARM CONTRACT (true cell): pin that a `Sexp::List` whose
        // even-indexed items are all keywords and whose length is non-zero
        // even returns `true` — the canonical kwargs shape `(:k v :k v …)`.
        // Covers the two-arity and four-arity baseline cases plus a mixed
        // payload (keyword odd index — even-index check is keyword-only,
        // odd-index payload is unconstrained per the kwargs convention).
        // A regression that drifts the predicate (incorrect parity check,
        // wrong keyword-position check, off-by-one in the step) surfaces
        // here immediately.
        let two = Sexp::List(vec![Sexp::keyword("k"), Sexp::int(1)]);
        assert!(two.is_kwargs_list());
        let four = Sexp::List(vec![
            Sexp::keyword("k1"),
            Sexp::int(1),
            Sexp::keyword("k2"),
            Sexp::string("v2"),
        ]);
        assert!(four.is_kwargs_list());
        // Odd-position values can themselves be keywords; the convention
        // only constrains the EVEN positions.
        let mixed = Sexp::List(vec![
            Sexp::keyword("k1"),
            Sexp::keyword("v-is-keyword-too"),
            Sexp::keyword("k2"),
            Sexp::Nil,
        ]);
        assert!(mixed.is_kwargs_list());
    }

    #[test]
    fn sexp_is_kwargs_list_method_returns_false_for_non_list_outer_shapes_and_violating_lists() {
        // PER-ARM CONTRACT (false cell): pin that every non-`Self::List`
        // outer shape (Nil, every Atom payload variant, every quote-family
        // wrapper) returns `false`, and that every `Self::List` violating
        // the kwargs convention (empty, odd length, non-keyword at any
        // even index) also returns `false`. A regression that returns
        // `true` for a wrong shape (e.g. claiming a Nil or a non-kwargs
        // list satisfies the predicate, opening the door to a
        // `Sexp::to_json` arm misrouting) surfaces here immediately.
        // Non-list outer shapes:
        assert!(!Sexp::Nil.is_kwargs_list());
        assert!(!Sexp::symbol("s").is_kwargs_list());
        assert!(!Sexp::keyword("k").is_kwargs_list());
        assert!(!Sexp::string("body").is_kwargs_list());
        assert!(!Sexp::int(0).is_kwargs_list());
        assert!(!Sexp::float(0.0).is_kwargs_list());
        assert!(!Sexp::boolean(true).is_kwargs_list());
        assert!(!Sexp::Quote(Box::new(Sexp::keyword("k"))).is_kwargs_list());
        assert!(!Sexp::Quasiquote(Box::new(Sexp::keyword("k"))).is_kwargs_list());
        assert!(!Sexp::Unquote(Box::new(Sexp::keyword("k"))).is_kwargs_list());
        assert!(!Sexp::UnquoteSplice(Box::new(Sexp::keyword("k"))).is_kwargs_list());
        // List arm violations:
        assert!(!Sexp::List(vec![]).is_kwargs_list()); // empty
        assert!(!Sexp::List(vec![Sexp::keyword("k")]).is_kwargs_list()); // odd length 1
        assert!(
            !Sexp::List(vec![Sexp::keyword("k1"), Sexp::int(1), Sexp::keyword("k2")])
                .is_kwargs_list()
        ); // odd length 3
        assert!(!Sexp::List(vec![Sexp::int(1), Sexp::int(2)]).is_kwargs_list()); // non-keyword at even 0
        assert!(!Sexp::List(vec![
            Sexp::keyword("k1"),
            Sexp::int(1),
            Sexp::symbol("not-kw"),
            Sexp::int(2)
        ])
        .is_kwargs_list()); // non-keyword at even 2
    }

    #[test]
    fn sexp_is_kwargs_list_method_composes_through_as_list_and_atom_as_keyword() {
        // COMPOSITION LAW: pin that the lifted predicate composes through
        // the already-lifted `Self::as_list` (structural projection onto
        // `&[Sexp]`) and `Atom::as_keyword` (typed projection onto the
        // keyword payload) primitives — a regression that re-inlines the
        // body without routing through the algebra-level soft-projection
        // family becomes detectable here. Sweeps every reachable outer
        // shape (Nil, every Atom variant, every quote-family wrapper, a
        // selection of List shapes covering the true + false cells) and
        // asserts the predicate's value agrees with the by-hand
        // `as_list().is_some_and(...)` recomposition.
        fn by_hand(s: &Sexp) -> bool {
            s.as_list().is_some_and(|items| {
                !items.is_empty()
                    && items.len().is_multiple_of(2)
                    && items.iter().step_by(2).all(|e| e.as_keyword().is_some())
            })
        }
        let cases = [
            Sexp::Nil,
            Sexp::symbol("s"),
            Sexp::keyword("k"),
            Sexp::string("body"),
            Sexp::int(7),
            Sexp::float(2.5),
            Sexp::boolean(false),
            Sexp::Quote(Box::new(Sexp::keyword("k"))),
            Sexp::Quasiquote(Box::new(Sexp::keyword("k"))),
            Sexp::Unquote(Box::new(Sexp::keyword("k"))),
            Sexp::UnquoteSplice(Box::new(Sexp::keyword("k"))),
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::int(1)]),
            Sexp::List(vec![Sexp::keyword("k"), Sexp::int(1)]),
            Sexp::List(vec![
                Sexp::keyword("k1"),
                Sexp::int(1),
                Sexp::keyword("k2"),
                Sexp::int(2),
            ]),
            Sexp::List(vec![Sexp::int(1), Sexp::int(2)]),
            Sexp::List(vec![Sexp::keyword("k1"), Sexp::int(1), Sexp::symbol("x")]),
        ];
        for s in &cases {
            assert_eq!(
                s.is_kwargs_list(),
                by_hand(s),
                "predicate drifted from as_list ∘ atom_as_keyword composition for {s}",
            );
        }
    }

    #[test]
    fn sexp_to_json_object_arm_routes_through_is_kwargs_list_method() {
        // CALLSITE-CONTRACT: pin that `Sexp::to_json`'s kwargs-vs-array
        // bifurcation routes through the lifted `Sexp::is_kwargs_list`
        // method — the kwargs-shape witness that gates the
        // `serde_json::Value::Object` arm vs the `serde_json::Value::Array`
        // arm at the `Sexp::List` outer shape. The pin walks the gate
        // both directions: a kwargs-shaped list must project as `Object`
        // (and the inherent predicate must agree, `true`); a non-kwargs
        // list (empty, odd-length, or even-index non-keyword) must
        // project as `Array` (and the predicate must agree, `false`). A
        // regression that decouples the two paths (e.g. `to_json` routes
        // through a re-inlined check while `is_kwargs_list` continues to
        // delegate, or vice versa) surfaces here.
        // Kwargs-shaped: Object projection, predicate true.
        let kw = Sexp::List(vec![Sexp::keyword("foo-bar"), Sexp::int(1)]);
        assert!(kw.is_kwargs_list());
        assert!(matches!(
            kw.to_json().expect("kwargs list projects"),
            serde_json::Value::Object(_)
        ));
        // Non-kwargs (empty list): Array projection, predicate false.
        let empty = Sexp::List(vec![]);
        assert!(!empty.is_kwargs_list());
        assert!(matches!(
            empty.to_json().expect("empty list projects"),
            serde_json::Value::Array(arr) if arr.is_empty(),
        ));
        // Non-kwargs (positional): Array projection, predicate false.
        let positional = Sexp::List(vec![Sexp::int(1), Sexp::int(2), Sexp::int(3)]);
        assert!(!positional.is_kwargs_list());
        assert!(matches!(
            positional.to_json().expect("positional list projects"),
            serde_json::Value::Array(arr) if arr.len() == 3,
        ));
        // Non-kwargs (even-index non-keyword): Array projection.
        let mixed = Sexp::List(vec![
            Sexp::keyword("k"),
            Sexp::int(1),
            Sexp::symbol("x"),
            Sexp::int(2),
        ]);
        assert!(!mixed.is_kwargs_list());
        assert!(matches!(
            mixed.to_json().expect("mixed list projects"),
            serde_json::Value::Array(_)
        ));
    }

    #[test]
    fn sexp_from_json_round_trips_to_json_for_canonical_subset() {
        // ROUND-TRIP LAW: pin `Sexp::to_json(s)?.from_json() == s` for
        // the round-trippable subset of Sexp shapes — Nil, Atom::Str
        // (the lossless atomic floor that absorbs Symbol/Keyword on
        // re-projection, so this test stays inside the lossless cell),
        // Atom::Int, Atom::Float, Atom::Bool, and recursively
        // Sexp::List of round-trippable elements. Pin that the inverse
        // composes byte-for-byte against the forward projection inside
        // the lossless cell — the round-trip law's structural anchor
        // documented at `Sexp::from_json`'s docstring.
        let cases = [
            Sexp::Nil,
            Sexp::string("body"),
            Sexp::int(42),
            Sexp::float(1.5),
            Sexp::boolean(true),
            Sexp::List(vec![Sexp::int(1), Sexp::string("x"), Sexp::Nil]),
            // Empty list → empty array → empty list. Round-trips cleanly.
            Sexp::List(vec![]),
        ];
        for s in &cases {
            let projected = s
                .to_json()
                .expect("round-trippable Sexp must project to JSON");
            let recovered = Sexp::from_json(&projected);
            assert_eq!(recovered, *s, "round-trip drifted at {s}");
        }
    }

    // ── Atom typed-construct family + Sexp outer-constructor routing ─────
    //
    // The six `Atom::{symbol, keyword, string, int, float, boolean}`
    // typed-construct methods are the section sibling of the existing
    // six `Atom::as_{symbol, keyword, string, int, float, bool}` soft-
    // projection family — closing the (construct, project) algebra dual
    // on the closed-set `Atom` algebra. The six `Sexp::{symbol, ...,
    // boolean}` outer constructors now route through
    // `Self::Atom(Atom::X(_))` so the `impl Into<String>` ergonomy +
    // tuple-variant constructor pair lives at ONE site per kind on the
    // `Atom` algebra. Pin the four structural laws:
    //   (a) each `Atom::X` constructor produces the canonical tuple
    //       variant payload byte-for-byte (`Atom::symbol("foo") ==
    //       Atom::Symbol("foo".into())`, etc.) — pre-lift behavior
    //       under the new construction face;
    //   (b) the (construct, kind-project) round-trip
    //       `Atom::X(_).kind() == AtomKind::X` for every (kind, payload)
    //       pair — the typed-construct family pairs section-for-
    //       retraction with the `Atom::kind` projection;
    //   (c) the (construct, soft-project) round-trip
    //       `Atom::X(payload).as_X() == Some(payload)` for every kind —
    //       the typed-construct family pairs section-for-retraction
    //       with the `Atom::as_X` family it now siblings;
    //   (d) the outer-constructor composition law `Sexp::X(p) ==
    //       Sexp::Atom(Atom::X(p))` for every kind — the `Sexp` outer
    //       constructors route through the typed `Atom` constructors
    //       rather than re-deriving the `Self::Atom(Atom::X(_))` pair
    //       inline.

    #[test]
    fn atom_typed_constructors_emit_canonical_tuple_variant_for_every_kind() {
        // STRUCTURAL CONSTRUCT CONTRACT: each `Atom::X` constructor
        // emits the matching `Atom::Variant(payload)` tuple-variant
        // value byte-for-byte. A regression that drifts ONE arm (e.g.
        // a typo routing `Atom::keyword(s)` to `Self::Symbol(s.into())`
        // — type-checks but silently mis-classifies every kwarg key
        // authored through the algebra-level constructor) surfaces
        // here. The `impl Into<String>` arms also accept `String`
        // payloads — pinned alongside `&str` so the `.into()` ergonomy
        // is exercised across both source types.
        assert_eq!(Atom::symbol("foo"), Atom::Symbol("foo".into()));
        assert_eq!(
            Atom::symbol(String::from("seph.1")),
            Atom::Symbol("seph.1".into()),
        );
        assert_eq!(Atom::symbol(""), Atom::Symbol(String::new()));
        assert_eq!(Atom::keyword("parent"), Atom::Keyword("parent".into()));
        assert_eq!(
            Atom::keyword(String::from("attr")),
            Atom::Keyword("attr".into()),
        );
        assert_eq!(Atom::keyword(""), Atom::Keyword(String::new()));
        assert_eq!(Atom::string("body"), Atom::Str("body".into()));
        assert_eq!(
            Atom::string(String::from("with\nnewline")),
            Atom::Str("with\nnewline".into()),
        );
        assert_eq!(Atom::string(""), Atom::Str(String::new()));
        assert_eq!(Atom::int(0), Atom::Int(0));
        assert_eq!(Atom::int(42), Atom::Int(42));
        assert_eq!(Atom::int(-7), Atom::Int(-7));
        assert_eq!(Atom::int(i64::MIN), Atom::Int(i64::MIN));
        assert_eq!(Atom::int(i64::MAX), Atom::Int(i64::MAX));
        assert_eq!(Atom::float(0.0), Atom::Float(0.0));
        assert_eq!(Atom::float(1.5), Atom::Float(1.5));
        assert_eq!(Atom::float(-2.5), Atom::Float(-2.5));
        // NaN compares unequal to itself; pin via `to_bits` round-trip,
        // matching the `Hash for Atom` Float-arm posture
        // (`f.to_bits().hash(...)`).
        assert_eq!(Atom::float(f64::NAN).kind(), AtomKind::Float);
        match Atom::float(f64::NAN) {
            Atom::Float(n) => assert!(n.is_nan()),
            _ => panic!("Atom::float must emit Atom::Float"),
        }
        assert_eq!(Atom::float(f64::INFINITY), Atom::Float(f64::INFINITY));
        assert_eq!(Atom::boolean(true), Atom::Bool(true));
        assert_eq!(Atom::boolean(false), Atom::Bool(false));
    }

    #[test]
    fn atom_typed_constructors_round_trip_through_kind_projection() {
        // SECTION LAW (construct → kind): every typed constructor's
        // output projects through `Atom::kind` to its matching
        // `AtomKind` variant. The `(construct, kind-project)` pair
        // forms a deterministic surjection from the construct face
        // onto the closed-set `AtomKind` algebra — six (kind,
        // representative payload) probes sweep `AtomKind::ALL` so a
        // future seventh atomic kind landing on the algebra extends
        // BOTH the construct face AND this sweep in lockstep (rustc-
        // enforced through the closed-set match below).
        for kind in AtomKind::ALL {
            let constructed = match kind {
                AtomKind::Symbol => Atom::symbol("foo"),
                AtomKind::Keyword => Atom::keyword("parent"),
                AtomKind::Str => Atom::string("body"),
                AtomKind::Int => Atom::int(42),
                AtomKind::Float => Atom::float(1.5),
                AtomKind::Bool => Atom::boolean(true),
            };
            assert_eq!(
                constructed.kind(),
                kind,
                "Atom typed constructor for {kind:?} drifted from its closed-set kind projection",
            );
        }
    }

    #[test]
    fn atom_typed_constructors_round_trip_through_per_variant_soft_projection() {
        // RETRACTION LAW (construct → soft-project): every typed
        // constructor's output projects through its matching `Atom::as_X`
        // soft projection to `Some(payload)` — the (construct, soft-
        // project) pair forms an `Iso(payload, Atom::Variant(payload))`
        // on the typed-payload axis. Sibling-axis to the
        // `(construct, kind-project)` pair above and to the
        // `Sexp::as_quote_form / QuoteForm::wrap` round-trip on the
        // outer-shape axis (`QuoteForm::wrap(inner).as_quote_form()
        // == Some((qf, &inner))`). The retraction's load-bearing
        // contract is what the substrate's named-form NAME gate
        // (`split_name_slot` → `as_symbol_or_string`) depends on at
        // every typed-domain dispatcher.
        assert_eq!(Atom::symbol("foo").as_symbol(), Some("foo"));
        assert_eq!(Atom::symbol("").as_symbol(), Some(""));
        assert_eq!(Atom::keyword("parent").as_keyword(), Some("parent"));
        assert_eq!(Atom::keyword("").as_keyword(), Some(""));
        assert_eq!(Atom::string("body").as_string(), Some("body"));
        assert_eq!(Atom::string("").as_string(), Some(""));
        assert_eq!(Atom::int(42).as_int(), Some(42));
        assert_eq!(Atom::int(0).as_int(), Some(0));
        assert_eq!(Atom::int(i64::MIN).as_int(), Some(i64::MIN));
        assert_eq!(Atom::float(1.5).as_float(), Some(1.5));
        assert_eq!(Atom::float(0.0).as_float(), Some(0.0));
        assert_eq!(Atom::boolean(true).as_bool(), Some(true));
        assert_eq!(Atom::boolean(false).as_bool(), Some(false));
    }

    #[test]
    fn sexp_outer_constructors_route_through_atom_typed_construct_family() {
        // OUTER-CONSTRUCTOR COMPOSITION LAW: pin that each `Sexp::X`
        // outer constructor emits `Sexp::Atom(Atom::X(_))` byte-for-byte
        // — a regression that re-inlines the pre-lift body
        // `Self::Atom(Atom::Variant(s.into()))` and drifts ONE arm
        // (e.g. a future copy-edit that swaps `Sexp::symbol` to route
        // through `Atom::Keyword` after a refactor) becomes detectable
        // at this site. Sibling-shape pin to the `Sexp::as_X` family's
        // structural-lift composition through `Sexp::as_atom +
        // Atom::as_X` on the projection axis (sweep posture in
        // `sexp_as_symbol_or_string_routes_through_atom_as_symbol_or_string_via_as_atom_composition`).
        assert_eq!(Sexp::symbol("foo"), Sexp::Atom(Atom::symbol("foo")));
        assert_eq!(Sexp::symbol(""), Sexp::Atom(Atom::symbol("")));
        assert_eq!(
            Sexp::symbol(String::from("seph.1")),
            Sexp::Atom(Atom::symbol("seph.1")),
        );
        assert_eq!(Sexp::keyword("parent"), Sexp::Atom(Atom::keyword("parent")),);
        assert_eq!(Sexp::string("body"), Sexp::Atom(Atom::string("body")));
        assert_eq!(Sexp::int(42), Sexp::Atom(Atom::int(42)));
        assert_eq!(Sexp::int(i64::MIN), Sexp::Atom(Atom::int(i64::MIN)));
        assert_eq!(Sexp::float(1.5), Sexp::Atom(Atom::float(1.5)));
        assert_eq!(Sexp::boolean(true), Sexp::Atom(Atom::boolean(true)));
        assert_eq!(Sexp::boolean(false), Sexp::Atom(Atom::boolean(false)));
    }

    #[test]
    fn atom_typed_constructors_partition_atom_kind_across_constructed_payloads() {
        // PARTITION LAW: every typed constructor's output projects to
        // `Some(_)` on its matching soft projection AND to `None` on
        // every other soft projection. The (construct, soft-project)
        // matrix is the diagonal of `AtomKind::ALL × AtomKind::ALL`:
        // on-diagonal cells return `Some`, off-diagonal cells return
        // `None`. Pin the full matrix so a regression that conflates
        // two construct arms (e.g. a future `Atom::keyword(s)` typo
        // routing to `Self::Symbol(s.into())` — type-checks, passes
        // the kind-projection sweep above iff the typo also drifts
        // `Atom::kind`, but fails THIS sweep because the off-diagonal
        // `Atom::keyword(s).as_symbol() == None` cell flips to `Some`)
        // surfaces structurally. The matrix's diagonal-restriction
        // form rebuilds the closed-set partition law every soft-
        // projection sweep above pins per-axis into ONE joint pin
        // across the (construct, project) algebra dual.
        let constructed = [
            (AtomKind::Symbol, Atom::symbol("foo")),
            (AtomKind::Keyword, Atom::keyword("parent")),
            (AtomKind::Str, Atom::string("body")),
            (AtomKind::Int, Atom::int(42)),
            (AtomKind::Float, Atom::float(1.5)),
            (AtomKind::Bool, Atom::boolean(true)),
        ];
        for (built_kind, a) in &constructed {
            assert_eq!(
                a.as_symbol().is_some(),
                *built_kind == AtomKind::Symbol,
                "as_symbol partition row drifted for {built_kind:?}",
            );
            assert_eq!(
                a.as_keyword().is_some(),
                *built_kind == AtomKind::Keyword,
                "as_keyword partition row drifted for {built_kind:?}",
            );
            assert_eq!(
                a.as_string().is_some(),
                *built_kind == AtomKind::Str,
                "as_string partition row drifted for {built_kind:?}",
            );
            assert_eq!(
                a.as_int().is_some(),
                *built_kind == AtomKind::Int,
                "as_int partition row drifted for {built_kind:?}",
            );
            assert_eq!(
                a.as_float().is_some(),
                *built_kind == AtomKind::Float,
                "as_float partition row drifted for {built_kind:?}",
            );
            assert_eq!(
                a.as_bool().is_some(),
                *built_kind == AtomKind::Bool,
                "as_bool partition row drifted for {built_kind:?}",
            );
        }
    }

    // ── Sexp quote-family typed-construct algebra ────────────────────────
    //
    // `Sexp::quote` / `Sexp::quasiquote` / `Sexp::unquote` /
    // `Sexp::unquote_splice` are the outer-Sexp typed-construct family for
    // the four homoiconic prefix wrappers, section-for-retraction with the
    // `Sexp::as_quote_form` soft-projection sibling. Each routes through
    // `QuoteForm::X.wrap(inner)` so the (marker, `Sexp::* tuple-variant
    // constructor + `Box::new`) welded triple lives at ONE site on the
    // closed-set `QuoteForm` algebra. Pin FOUR structural laws:
    //   (a) the canonical-tuple emission
    //       `Sexp::quote(inner) == Sexp::Quote(Box::new(inner))` for
    //       every wrapper marker — the typed constructor pairs section-
    //       for-retraction with the tuple-variant constructor;
    //   (b) the composition law
    //       `Sexp::X_variant(inner) == QuoteForm::X.wrap(inner)` for
    //       every marker — the outer typed constructor routes through
    //       the inner-algebra `QuoteForm::wrap` typed dispatch;
    //   (c) the round-trip law
    //       `Sexp::X_variant(inner).as_quote_form() == Some((QuoteForm::X,
    //       &inner))` for every marker — the (construct, soft-project)
    //       algebra dual closes on the outer [`Sexp`] algebra with
    //       marker + inner-body cross-projection preserved;
    //   (d) the outer-shape pairing
    //       `Sexp::X_variant(inner).shape() == QuoteForm::X.sexp_shape()`
    //       for every marker — the construct family composes coherently
    //       through the outer-shape projection on the typed-shape
    //       lattice, so a regression that drifts ONE marker's outer-
    //       shape pairing from `QuoteForm::sexp_shape` surfaces here.

    #[test]
    fn sexp_quote_family_constructors_emit_canonical_tuple_variant_for_every_marker() {
        // STRUCTURAL CONSTRUCT CONTRACT: each `Sexp::X_variant`
        // constructor emits the matching `Sexp::X(Box::new(inner))`
        // tuple-variant value byte-for-byte. A regression that drifts
        // ONE arm (e.g. a typo routing `Sexp::unquote(inner)` to
        // `Sexp::UnquoteSplice(Box::new(inner))` — type-checks but
        // silently mis-classifies every macro-template substitution
        // authored through the algebra-level constructor) surfaces
        // here. Sibling-shape pin to the `Atom` typed-construct
        // family's canonical-tuple-variant test posture
        // (`atom_typed_constructors_emit_canonical_tuple_variant_for_every_kind`).
        let payloads = [
            Sexp::Nil,
            Sexp::symbol("x"),
            Sexp::keyword("k"),
            Sexp::string("body"),
            Sexp::int(42),
            Sexp::boolean(true),
            Sexp::List(vec![Sexp::symbol("op"), Sexp::int(1)]),
        ];
        for inner in &payloads {
            assert_eq!(
                Sexp::quote(inner.clone()),
                Sexp::Quote(Box::new(inner.clone())),
                "Sexp::quote drifted from canonical tuple variant for {inner:?}",
            );
            assert_eq!(
                Sexp::quasiquote(inner.clone()),
                Sexp::Quasiquote(Box::new(inner.clone())),
                "Sexp::quasiquote drifted from canonical tuple variant for {inner:?}",
            );
            assert_eq!(
                Sexp::unquote(inner.clone()),
                Sexp::Unquote(Box::new(inner.clone())),
                "Sexp::unquote drifted from canonical tuple variant for {inner:?}",
            );
            assert_eq!(
                Sexp::unquote_splice(inner.clone()),
                Sexp::UnquoteSplice(Box::new(inner.clone())),
                "Sexp::unquote_splice drifted from canonical tuple variant for {inner:?}",
            );
        }
    }

    #[test]
    fn sexp_quote_family_constructors_route_through_quote_form_wrap() {
        // COMPOSITION LAW: pin that each `Sexp::X_variant` outer
        // constructor emits `QuoteForm::X.wrap(inner)` byte-for-byte —
        // a regression that re-inlines the pre-lift body
        // `Self::X(Box::new(inner))` and drifts ONE arm (e.g. a future
        // copy-edit that swaps `Sexp::quote` to route through
        // `QuoteForm::Quasiquote` after a refactor) becomes detectable
        // at this site. Sibling-shape pin to the `Sexp::X_atom` family's
        // composition-through-`Atom::X` posture
        // (`sexp_outer_constructors_route_through_atom_typed_construct_family`).
        let inner = Sexp::List(vec![Sexp::symbol("op"), Sexp::int(1)]);
        assert_eq!(
            Sexp::quote(inner.clone()),
            QuoteForm::Quote.wrap(inner.clone())
        );
        assert_eq!(
            Sexp::quasiquote(inner.clone()),
            QuoteForm::Quasiquote.wrap(inner.clone()),
        );
        assert_eq!(
            Sexp::unquote(inner.clone()),
            QuoteForm::Unquote.wrap(inner.clone())
        );
        assert_eq!(
            Sexp::unquote_splice(inner.clone()),
            QuoteForm::UnquoteSplice.wrap(inner.clone()),
        );
    }

    #[test]
    fn sexp_quote_family_constructors_round_trip_through_as_quote_form() {
        // ROUND-TRIP LAW (construct → soft-project): every quote-family
        // typed constructor's output projects through `Sexp::as_quote_form`
        // to `Some((matching QuoteForm, &inner))`. Sweeps `QuoteForm::ALL`
        // paired with a representative inner payload — the four
        // (construct, project) pairs form an `Iso(inner, Sexp::X(inner))`
        // on the typed-marker axis at the outer [`Sexp`] algebra. A
        // regression that drifts ONE marker's construct arm (marker/
        // constructor swap) fails BOTH the marker-projection AND the
        // inner-borrow round-trip. Sibling-shape pin to the `Atom` typed-
        // construct family's per-variant soft-projection round-trip test
        // posture
        // (`atom_typed_constructors_round_trip_through_per_variant_soft_projection`).
        let inner = Sexp::List(vec![Sexp::symbol("op"), Sexp::int(1)]);
        let constructed: [(QuoteForm, Sexp); 4] = [
            (QuoteForm::Quote, Sexp::quote(inner.clone())),
            (QuoteForm::Quasiquote, Sexp::quasiquote(inner.clone())),
            (QuoteForm::Unquote, Sexp::unquote(inner.clone())),
            (
                QuoteForm::UnquoteSplice,
                Sexp::unquote_splice(inner.clone()),
            ),
        ];
        for qf in QuoteForm::ALL {
            let (built_qf, sexp) = constructed
                .iter()
                .find(|(m, _)| *m == qf)
                .expect("QuoteForm::ALL sweep must reach every marker");
            assert_eq!(*built_qf, qf);
            let (proj_qf, proj_inner) = sexp
                .as_quote_form()
                .unwrap_or_else(|| panic!("construct→as_quote_form drifted at {qf:?}"));
            assert_eq!(
                proj_qf, qf,
                "typed-marker round-trip drifted at {qf:?} — construct+project pair broken",
            );
            assert_eq!(
                proj_inner, &inner,
                "inner-body round-trip drifted at {qf:?} — construct+project pair broken",
            );
        }
    }

    #[test]
    fn sexp_quote_family_constructors_compose_with_shape_via_quote_form_sexp_shape() {
        // OUTER-SHAPE COMPOSITION LAW: every quote-family typed
        // constructor's output projects through `Sexp::shape` to the
        // matching `QuoteForm::X.sexp_shape()` — the (construct,
        // outer-shape) composition binds through the closed-set
        // `QuoteForm::sexp_shape` embed already lifted onto the
        // typed-shape lattice. A regression that drifts ONE construct
        // arm's outer-shape from `QuoteForm::sexp_shape` (e.g. a future
        // marker/wrapper swap that surfaces through the typed-shape
        // lattice but not through the tuple-variant emission itself)
        // surfaces here alongside the round-trip pin. Sibling-shape pin
        // to `quote_form_sexp_shape_paired_with_as_quote_form_preserves_pre_lift_pairing_for_every_sexp`
        // on the projection axis — this pin closes the same axis on the
        // outer construct family.
        let inner = Sexp::List(vec![Sexp::symbol("op"), Sexp::int(1)]);
        let constructed: [(QuoteForm, Sexp); 4] = [
            (QuoteForm::Quote, Sexp::quote(inner.clone())),
            (QuoteForm::Quasiquote, Sexp::quasiquote(inner.clone())),
            (QuoteForm::Unquote, Sexp::unquote(inner.clone())),
            (
                QuoteForm::UnquoteSplice,
                Sexp::unquote_splice(inner.clone()),
            ),
        ];
        for (qf, sexp) in &constructed {
            assert_eq!(
                sexp.shape(),
                qf.sexp_shape(),
                "Sexp::X_variant→shape drifted from QuoteForm::sexp_shape at {qf:?}",
            );
        }
    }

    // ── Sexp::list residual-axis typed-construct algebra ─────────────────
    //
    // `Sexp::list(items)` is the residual-axis section-for-retraction
    // sibling of the pre-existing `Sexp::as_list` soft-projection — the
    // (construct, project) algebra dual on the 2-of-12 residual carving of
    // the [`SexpShape`] closed set now closes at ONE constructor + ONE
    // projection on the outer [`Sexp`] algebra, symmetric with the atomic-
    // payload carving's (six `Sexp::X_atom(payload)` constructors +
    // `Sexp::as_atom` / `Sexp::as_atom_kind` projections) and the quote-
    // family carving's (four `Sexp::X_variant(inner)` constructors +
    // `Sexp::as_quote_form` / `Sexp::as_quote_form_marker` projections).
    // [`Sexp::Nil`] is a unit variant with no payload — the residual-axis
    // construct family closes at ONE constructor (the sole payload-bearing
    // residual arm). Pin FIVE structural laws:
    //   (a) the canonical-tuple emission
    //       `Sexp::list(items) == Sexp::List(items.into_iter().collect())`
    //       across representative empty / single-element / multi-element /
    //       heterogeneous-inner samples — the typed constructor pairs
    //       section-for-retraction with the tuple-variant constructor;
    //   (b) the round-trip law
    //       `Sexp::list(items.clone()).as_list() == Some(items.as_slice())`
    //       — the (construct, soft-project) algebra dual closes on the
    //       outer [`Sexp`] algebra with the borrowed-slice cross-
    //       projection preserving identity;
    //   (c) the outer-shape law
    //       `Sexp::list(items).shape() == SexpShape::List` — the residual-
    //       arm outer-shape identity binds through the typed-shape
    //       lattice at ONE arm, symmetric with the quote-family
    //       construct family's `Sexp::X_variant(inner).shape() ==
    //       QuoteForm::X.sexp_shape()`;
    //   (d) the structural-kind law
    //       `Sexp::list(items).as_structural_kind() == Some(
    //       StructuralKind::List)` — the residual carving marker binds
    //       through the closed-set [`StructuralKind`] algebra at ONE
    //       arm, symmetric with the atomic-axis's
    //       `Sexp::X_atom(payload).as_atom_kind() == Some(AtomKind::X)`;
    //   (e) the input-shape flexibility
    //       `Sexp::list(&Vec<Sexp>)` / `Sexp::list([Sexp; N])` /
    //       `Sexp::list(iter::map(...))` all agree with the canonical
    //       tuple-variant emission — the `impl IntoIterator<Item = Sexp>`
    //       bound accepts every reasonable owned-sequence shape without a
    //       per-consumer `.collect::<Vec<Sexp>>()` coercion.

    #[test]
    fn sexp_list_constructor_emits_canonical_tuple_variant_across_representative_inputs() {
        // STRUCTURAL CONSTRUCT CONTRACT: `Sexp::list(items)` emits
        // `Sexp::List(items.into_iter().collect::<Vec<Sexp>>())` byte-
        // for-byte across representative empty, single-element, multi-
        // element, and heterogeneous-inner samples. A regression that
        // drifts the body (e.g. wrapping items in an extra `Sexp::Nil`
        // sentinel, deduplicating, filtering) surfaces here. Sibling-
        // shape pin to the quote-family construct family's canonical-
        // tuple-variant test posture
        // (`sexp_quote_family_constructors_emit_canonical_tuple_variant_for_every_marker`).
        let samples: [Vec<Sexp>; 5] = [
            vec![],
            vec![Sexp::symbol("only")],
            vec![Sexp::symbol("op"), Sexp::int(1), Sexp::int(2)],
            vec![
                Sexp::Nil,
                Sexp::keyword("k"),
                Sexp::string("body"),
                Sexp::boolean(true),
                Sexp::List(vec![Sexp::symbol("nested")]),
            ],
            vec![
                Sexp::Quote(Box::new(Sexp::symbol("x"))),
                Sexp::Quasiquote(Box::new(Sexp::List(vec![
                    Sexp::symbol("template"),
                    Sexp::Unquote(Box::new(Sexp::symbol("var"))),
                ]))),
                Sexp::UnquoteSplice(Box::new(Sexp::symbol("xs"))),
            ],
        ];
        for items in &samples {
            assert_eq!(
                Sexp::list(items.clone()),
                Sexp::List(items.clone()),
                "Sexp::list drifted from canonical Sexp::List(_) tuple variant for {items:?}",
            );
        }
    }

    #[test]
    fn sexp_list_constructor_round_trips_through_as_list() {
        // ROUND-TRIP LAW (section-for-retraction on the residual axis):
        // `Sexp::list(items.clone()).as_list() == Some(items.as_slice())`
        // sweeps the same representative input matrix as the canonical-
        // tuple pin — proves the (construct, soft-project) pair forms an
        // `Iso(Vec<Sexp>, Sexp::List(Vec<Sexp>))` on the residual axis,
        // symmetric with the quote-family axis's `Sexp::X_variant(inner)
        // .as_quote_form() == Some((QuoteForm::X, &inner))` round-trip
        // (pinned by `sexp_quote_family_constructors_round_trip_through_as_quote_form`).
        // A regression that mis-implements `Sexp::list` (e.g. dropping
        // items, cloning off-by-one) fails here on top of the canonical-
        // tuple pin.
        let samples: [Vec<Sexp>; 4] = [
            vec![],
            vec![Sexp::symbol("solo")],
            vec![Sexp::symbol("op"), Sexp::int(1), Sexp::int(2)],
            vec![
                Sexp::Nil,
                Sexp::List(vec![Sexp::symbol("nested"), Sexp::int(7)]),
                Sexp::Quote(Box::new(Sexp::symbol("q"))),
            ],
        ];
        for items in &samples {
            let built = Sexp::list(items.clone());
            assert_eq!(
                built.as_list(),
                Some(items.as_slice()),
                "Sexp::list→as_list round-trip drifted for {items:?}",
            );
        }
    }

    #[test]
    fn sexp_list_constructor_composes_with_shape_via_sexp_shape_list() {
        // OUTER-SHAPE COMPOSITION LAW: every `Sexp::list(items)` output
        // projects through `Sexp::shape` to `SexpShape::List` regardless
        // of inner-item content — the (construct, outer-shape)
        // composition binds through the typed-shape lattice's residual-
        // arm at ONE arm. Sibling-shape pin to the quote-family construct
        // family's outer-shape composition
        // (`sexp_quote_family_constructors_compose_with_shape_via_quote_form_sexp_shape`).
        // A regression that reroutes `Sexp::list` through another shape
        // arm (e.g. wrapping in `Sexp::Quote` after a copy-edit that
        // type-checks) surfaces here alongside the canonical-tuple pin.
        let samples: [Vec<Sexp>; 4] = [
            vec![],
            vec![Sexp::symbol("only")],
            vec![Sexp::int(1), Sexp::int(2), Sexp::int(3)],
            vec![
                Sexp::Nil,
                Sexp::Quote(Box::new(Sexp::symbol("x"))),
                Sexp::List(vec![Sexp::symbol("nested")]),
            ],
        ];
        for items in &samples {
            assert_eq!(
                Sexp::list(items.clone()).shape(),
                SexpShape::List,
                "Sexp::list→shape drifted from SexpShape::List for {items:?}",
            );
        }
    }

    #[test]
    fn sexp_list_constructor_composes_with_as_structural_kind() {
        // STRUCTURAL-KIND COMPOSITION LAW: every `Sexp::list(items)`
        // output projects through `Sexp::as_structural_kind` to
        // `Some(StructuralKind::List)` regardless of inner-item content
        // — the residual carving marker binds through the closed-set
        // `StructuralKind` algebra at ONE arm. Sibling-shape pin to the
        // atomic-axis's `Sexp::X_atom(payload).as_atom_kind() ==
        // Some(AtomKind::X)` marker composition. A regression that
        // reroutes `Sexp::list` through a non-residual arm (e.g. a copy-
        // edit that wraps items in `Sexp::Quote`) surfaces here through
        // the returned marker no longer being `StructuralKind::List`.
        let samples: [Vec<Sexp>; 4] = [
            vec![],
            vec![Sexp::symbol("only")],
            vec![Sexp::keyword("k"), Sexp::string("v")],
            vec![
                Sexp::Nil,
                Sexp::List(vec![Sexp::symbol("nested")]),
                Sexp::Unquote(Box::new(Sexp::symbol("var"))),
            ],
        ];
        for items in &samples {
            assert_eq!(
                Sexp::list(items.clone()).as_structural_kind(),
                Some(StructuralKind::List),
                "Sexp::list→as_structural_kind drifted from Some(StructuralKind::List) for {items:?}",
            );
        }
    }

    #[test]
    fn sexp_list_constructor_accepts_diverse_intoiterator_input_shapes() {
        // INPUT-SHAPE FLEXIBILITY: the `impl IntoIterator<Item = Sexp>`
        // bound accepts every reasonable owned-sequence shape without a
        // per-consumer `.collect::<Vec<Sexp>>()` coercion at the call
        // site — pin that `Vec<Sexp>`, `[Sexp; N]` array, `iter::empty
        // ::<Sexp>()`, and `.map(...)` iterator chains all reach the
        // same canonical tuple-variant output. A regression that
        // narrows the bound (e.g. taking `&[Sexp]` or `Vec<Sexp>` only)
        // fails this pin. The IntoIterator bound is load-bearing for the
        // ergonomy claim in the docstring — consumers threading a `.map`
        // chain through the outer algebra must not need an intermediate
        // `.collect()` before handing the result to `Sexp::list`.
        let expected = Sexp::List(vec![
            Sexp::symbol("a"),
            Sexp::symbol("b"),
            Sexp::symbol("c"),
        ]);
        // Vec<Sexp> — the canonical owned-sequence shape.
        assert_eq!(
            Sexp::list(vec![
                Sexp::symbol("a"),
                Sexp::symbol("b"),
                Sexp::symbol("c"),
            ]),
            expected,
            "Sexp::list drifted for Vec<Sexp> input",
        );
        // [Sexp; N] — array-literal shape (elements moved out of the
        // fixed-size array via the `IntoIterator` impl on `[T; N]`).
        assert_eq!(
            Sexp::list([Sexp::symbol("a"), Sexp::symbol("b"), Sexp::symbol("c"),]),
            expected,
            "Sexp::list drifted for [Sexp; N] input",
        );
        // `iter::empty::<Sexp>()` — the zero-item iterator shape.
        assert_eq!(
            Sexp::list(std::iter::empty::<Sexp>()),
            Sexp::List(vec![]),
            "Sexp::list drifted for iter::empty input",
        );
        // `.map(...)` iterator chain — the composition shape the
        // docstring's ergonomy claim rests on.
        assert_eq!(
            Sexp::list(["a", "b", "c"].iter().map(|s| Sexp::symbol(*s))),
            expected,
            "Sexp::list drifted for iterator-map chain input",
        );
        // `once(head).chain(tail)` — the head-then-rest shape a builder
        // consuming `head_symbol` + the tail slice threads through.
        assert_eq!(
            Sexp::list(
                std::iter::once(Sexp::symbol("a")).chain([Sexp::symbol("b"), Sexp::symbol("c")]),
            ),
            expected,
            "Sexp::list drifted for once+chain input",
        );
    }

    // ── Sexp::call — call-form (symbol-headed list) construct ──────────
    //
    // `Sexp::call(head, args)` is the section-for-retraction dual of the
    // soft-projection `Sexp::as_call() -> Option<(&str, &[Sexp])>` — it
    // embeds a fresh `(head string, item sequence)` pair into a symbol-
    // headed `Sexp::List` value at ONE site on the outer `Sexp` algebra,
    // composing the atomic-payload construct family's `Sexp::symbol` (for
    // the head position) with the residual-axis construct family's
    // `Sexp::list` (for the list wrapper) via `std::iter::once(head_sexp)
    // .chain(args)`. Pre-lift the composition lived inline at every
    // consumer that built a `(defX …)` typed-domain call form, a
    // macroexpander template head, or a synthetic dispatch form —
    // `Sexp::List(vec![Sexp::symbol(head), args...])` or `Sexp::List(
    // std::iter::once(Sexp::symbol(head)).chain(args).collect())` was the
    // welded three-method open coding. Post-lift the closure binds at
    // ONE typed-algebra method.
    //
    // These pins cover:
    //   (a) the composition law
    //       `Sexp::call(head, args) == Sexp::list(std::iter::once(
    //       Sexp::symbol(head)).chain(args))` — the constructor body is
    //       BY DEFINITION the two-method composition;
    //   (b) the round-trip law
    //       `Sexp::call(head, args.clone()).as_call() == Some((head,
    //       args.as_slice()))` — the (construct, project) call-form
    //       algebra dual closes at this pair, symmetric with the
    //       residual-axis's `Sexp::list(items.clone()).as_list() ==
    //       Some(items.as_slice())` round-trip;
    //   (c) the keyword-matched round-trip law
    //       `Sexp::call(head, args.clone()).as_call_to(head) == Some(
    //       args.as_slice())` — the keyword-typed projection recovers
    //       the args tail iff its argument matches the constructor's
    //       head;
    //   (d) the head-symbol composition law
    //       `Sexp::call(head, args).head_symbol() == Some(head)` — the
    //       head-position projection recovers the constructor's head
    //       byte-for-byte;
    //   (e) the outer-shape composition law
    //       `Sexp::call(head, args).shape() == SexpShape::List` — a
    //       call form is a list-shaped `Sexp`;
    //   (f) the structural-kind composition law
    //       `Sexp::call(head, args).as_structural_kind() == Some(
    //       StructuralKind::List)` — the residual carving marker binds
    //       through the closed-set `StructuralKind` algebra at ONE
    //       arm, symmetric with the residual-axis's `Sexp::list(items)
    //       .as_structural_kind() == Some(StructuralKind::List)` marker
    //       composition;
    //   (g) the input-shape flexibility
    //       `Sexp::call("h", Vec<Sexp>)` / `Sexp::call(String, [Sexp;
    //       N])` / `Sexp::call(&String, iter::map(...))` all agree with
    //       the canonical composition emission — the `impl Into<String>`
    //       head bound + `impl IntoIterator<Item = Sexp>` args bound
    //       accept every reasonable input shape without a per-consumer
    //       `.to_string()` / `.collect::<Vec<Sexp>>()` coercion.

    #[test]
    fn sexp_call_constructor_body_matches_canonical_two_method_composition_across_representative_inputs(
    ) {
        // COMPOSITION LAW: `Sexp::call(head, args) == Sexp::list(
        // std::iter::once(Sexp::symbol(head)).chain(args))` for every
        // representative (empty-args, single-arg, multi-arg,
        // heterogeneous-inner, quote-family-wrapping-inner) sample. A
        // regression that drifts the body (e.g. a copy-edit that
        // switches to `Sexp::keyword(head)` for the head position, or
        // that reorders `head` and `args` in the chain) surfaces here
        // BEFORE the projection pins fail. Sibling-shape pin to the
        // residual-axis's canonical-composition test posture
        // (`sexp_list_constructor_emits_canonical_tuple_variant_across_representative_inputs`).
        let samples: [(&str, Vec<Sexp>); 5] = [
            ("defcompiler", vec![]),
            ("defpoint", vec![Sexp::symbol("obs")]),
            (
                "defpoint",
                vec![
                    Sexp::symbol("obs"),
                    Sexp::keyword("class"),
                    Sexp::symbol("Gate"),
                ],
            ),
            (
                "defcheck",
                vec![
                    Sexp::List(vec![Sexp::symbol("crd-in-sync")]),
                    Sexp::keyword("params"),
                    Sexp::int(42),
                    Sexp::string("body"),
                    Sexp::boolean(true),
                ],
            ),
            (
                "defalert-policy",
                vec![
                    Sexp::Quote(Box::new(Sexp::symbol("x"))),
                    Sexp::Quasiquote(Box::new(Sexp::List(vec![
                        Sexp::symbol("template"),
                        Sexp::Unquote(Box::new(Sexp::symbol("var"))),
                    ]))),
                    Sexp::UnquoteSplice(Box::new(Sexp::symbol("xs"))),
                ],
            ),
        ];
        for (head, args) in &samples {
            let expected =
                Sexp::list(std::iter::once(Sexp::symbol(*head)).chain(args.iter().cloned()));
            assert_eq!(
                Sexp::call(*head, args.clone()),
                expected,
                "Sexp::call drifted from Sexp::list(once(symbol(head)).chain(args)) for head={head:?} args={args:?}",
            );
        }
    }

    #[test]
    fn sexp_call_constructor_round_trips_through_as_call() {
        // ROUND-TRIP LAW (section-for-retraction with the call-form
        // soft-projection): `Sexp::call(head, args.clone()).as_call()
        // == Some((head, args.as_slice()))` sweeps the same
        // representative input matrix as the composition-law pin —
        // proves the (construct, soft-project) pair forms an
        // `Iso((&str, Vec<Sexp>), symbol-headed Sexp::List)` on the
        // call-form typed decomposition. Sibling-shape pin to the
        // residual-axis's `Sexp::list(items.clone()).as_list() ==
        // Some(items.as_slice())` round-trip
        // (`sexp_list_constructor_round_trips_through_as_list`).
        let samples: [(&str, Vec<Sexp>); 4] = [
            ("defcompiler", vec![]),
            ("defpoint", vec![Sexp::symbol("solo")]),
            (
                "defmonitor",
                vec![Sexp::symbol("m"), Sexp::int(1), Sexp::int(2)],
            ),
            (
                "defnotify",
                vec![
                    Sexp::Nil,
                    Sexp::List(vec![Sexp::symbol("nested"), Sexp::int(7)]),
                    Sexp::Quote(Box::new(Sexp::symbol("q"))),
                ],
            ),
        ];
        for (head, args) in &samples {
            let built = Sexp::call(*head, args.clone());
            assert_eq!(
                built.as_call(),
                Some((*head, args.as_slice())),
                "Sexp::call→as_call round-trip drifted for head={head:?} args={args:?}",
            );
        }
    }

    #[test]
    fn sexp_call_constructor_round_trips_through_as_call_to_matching_keyword() {
        // KEYWORD-MATCHED ROUND-TRIP LAW: `Sexp::call(head, args
        // .clone()).as_call_to(head) == Some(args.as_slice())` for the
        // head-matched keyword, and `.as_call_to(other)` returns `None`
        // for every other keyword. Pins the (construct, keyword-typed-
        // project) pair on the outer algebra — the same dispatch
        // shape `compile_typed` / `compile_named_from_forms` route
        // through post-macroexpansion.
        let samples: [(&str, Vec<Sexp>); 4] = [
            ("defcompiler", vec![]),
            ("defpoint", vec![Sexp::symbol("obs")]),
            ("defmonitor", vec![Sexp::keyword("k"), Sexp::string("v")]),
            (
                "defalert-policy",
                vec![Sexp::Nil, Sexp::List(vec![Sexp::symbol("body")])],
            ),
        ];
        for (head, args) in &samples {
            let built = Sexp::call(*head, args.clone());
            assert_eq!(
                built.as_call_to(head),
                Some(args.as_slice()),
                "Sexp::call→as_call_to(head) round-trip drifted for head={head:?} args={args:?}",
            );
            // Cross-keyword rejection: every DIFFERENT keyword misses.
            let mismatched = format!("{head}-mismatch");
            assert_eq!(
                built.as_call_to(&mismatched),
                None,
                "Sexp::call→as_call_to(mismatch) leaked args for head={head:?}",
            );
        }
    }

    #[test]
    fn sexp_call_constructor_composes_with_head_symbol_and_shape_and_structural_kind() {
        // OUTER-ALGEBRA PROJECTION COMPOSITIONS: every `Sexp::call(head,
        // args)` output projects through `head_symbol` /
        // `shape` / `as_structural_kind` to the shape-invariants that
        // pin the constructor's structural identity:
        //   * `head_symbol() == Some(head)` — the head-position
        //     projection recovers the constructor's head byte-for-byte;
        //   * `shape() == SexpShape::List` — a call form is a list-
        //     shaped `Sexp` on the residual carving;
        //   * `as_structural_kind() == Some(StructuralKind::List)` — the
        //     residual carving marker binds through the closed-set
        //     `StructuralKind` algebra at ONE arm.
        // A regression that reroutes `Sexp::call` through a non-list
        // arm (e.g. wrapping in `Sexp::Quote` after a copy-edit that
        // type-checks) fails ALL THREE pins simultaneously. Sibling to
        // the residual-axis's `Sexp::list` shape-composition pins
        // (`sexp_list_constructor_composes_with_shape_via_sexp_shape_list`
        // + `sexp_list_constructor_composes_with_as_structural_kind`).
        let samples: [(&str, Vec<Sexp>); 4] = [
            ("head", vec![]),
            ("head", vec![Sexp::symbol("only")]),
            (
                "head",
                vec![Sexp::keyword("k"), Sexp::string("v"), Sexp::boolean(false)],
            ),
            (
                "head",
                vec![
                    Sexp::Nil,
                    Sexp::Quote(Box::new(Sexp::symbol("x"))),
                    Sexp::List(vec![Sexp::symbol("nested")]),
                ],
            ),
        ];
        for (head, args) in &samples {
            let built = Sexp::call(*head, args.clone());
            assert_eq!(
                built.head_symbol(),
                Some(*head),
                "Sexp::call→head_symbol drifted from Some({head:?}) for args={args:?}",
            );
            assert_eq!(
                built.shape(),
                SexpShape::List,
                "Sexp::call→shape drifted from SexpShape::List for head={head:?} args={args:?}",
            );
            assert_eq!(
                built.as_structural_kind(),
                Some(StructuralKind::List),
                "Sexp::call→as_structural_kind drifted from Some(StructuralKind::List) for head={head:?} args={args:?}",
            );
        }
    }

    #[test]
    fn sexp_call_constructor_accepts_diverse_head_and_arg_input_shapes() {
        // INPUT-SHAPE FLEXIBILITY: the `impl Into<String>` head bound
        // absorbs `&str` / `String` / `&String`, and the `impl
        // IntoIterator<Item = Sexp>` args bound absorbs `Vec<Sexp>` /
        // `[Sexp; N]` / `iter::empty()` / `.map(...)` chains — pin that
        // all six representative input shapes reach the same canonical
        // composition output. A regression that narrows either bound
        // (e.g. requiring `String` on the head or `Vec<Sexp>` on the
        // args) fails this pin. The two bounds are load-bearing for the
        // ergonomy claim in the docstring — consumers threading a
        // borrowed head + a `.map` chain must not need `.to_string()` /
        // `.collect()` coercions before handing the pair to
        // `Sexp::call`. Sibling to `Sexp::list`'s input-shape pin
        // (`sexp_list_constructor_accepts_diverse_intoiterator_input_shapes`)
        // and `Sexp::symbol`'s head-string absorption posture.
        let expected = Sexp::List(vec![
            Sexp::symbol("head"),
            Sexp::symbol("a"),
            Sexp::symbol("b"),
        ]);
        // (&str, Vec<Sexp>) — the canonical borrowed-head + owned-args
        // shape.
        assert_eq!(
            Sexp::call("head", vec![Sexp::symbol("a"), Sexp::symbol("b")]),
            expected,
            "Sexp::call drifted for (&str, Vec<Sexp>) input",
        );
        // (String, [Sexp; N]) — the owned-head + array-literal shape.
        assert_eq!(
            Sexp::call(String::from("head"), [Sexp::symbol("a"), Sexp::symbol("b")],),
            expected,
            "Sexp::call drifted for (String, [Sexp; N]) input",
        );
        // (&String, .map(...)) — the borrowed-owned-head + iterator-map
        // chain shape.
        let owned_head = String::from("head");
        assert_eq!(
            Sexp::call(&owned_head, ["a", "b"].iter().map(|s| Sexp::symbol(*s))),
            expected,
            "Sexp::call drifted for (&String, iter::map) input",
        );
        // (&str, iter::empty::<Sexp>()) — the zero-arg iterator shape,
        // pinning the singleton-list emission (`(head)`) via the
        // composition path.
        assert_eq!(
            Sexp::call("head", std::iter::empty::<Sexp>()),
            Sexp::List(vec![Sexp::symbol("head")]),
            "Sexp::call drifted for zero-arg iter::empty input",
        );
        // (&str, once(head_of_args).chain(tail_of_args)) — the head-
        // then-rest args shape a builder decomposing an existing call
        // form via `as_call` and re-emitting through this constructor
        // threads through.
        assert_eq!(
            Sexp::call(
                "head",
                std::iter::once(Sexp::symbol("a")).chain([Sexp::symbol("b")]),
            ),
            expected,
            "Sexp::call drifted for (&str, once+chain) args input",
        );
    }

    #[test]
    fn sexp_call_constructor_body_matches_typed_composition_through_list_and_symbol() {
        // EXPLICIT COMPOSITION-LAW PIN: `Sexp::call(head, args) ==
        // Sexp::list(std::iter::once(Sexp::symbol(head)).chain(args))`
        // BY DEFINITION — the constructor body IS this composition, and
        // the pin exists so a regression that in-lines a hand-authored
        // `Sexp::List(vec![Sexp::symbol(head), args...])` body (which
        // would type-check and pass the projection round-trips) still
        // surfaces here through the composition-path drift. This closes
        // the "the constructor routes through the outer-algebra's
        // atomic + residual construct families" invariant as a typed
        // pin rather than a docstring claim.
        let head = "defpoint";
        let args = vec![
            Sexp::symbol("obs"),
            Sexp::keyword("class"),
            Sexp::List(vec![Sexp::symbol("Gate"), Sexp::symbol("Observability")]),
        ];
        assert_eq!(
            Sexp::call(head, args.clone()),
            Sexp::list(std::iter::once(Sexp::symbol(head)).chain(args.iter().cloned())),
            "Sexp::call body drifted from the Sexp::list ∘ once(Sexp::symbol) ∘ chain composition for head={head:?}",
        );
    }

    // ── Sexp::named_call — named-call-form (symbol-headed + NAME slot)
    //    construct ───────────────────────────────────────────────────────
    //
    // `Sexp::named_call(head, name, spec_args)` is the section-for-
    // retraction dual of the soft-projection `Sexp::as_named_call_to(
    // keyword) -> Option<Result<(&str, &[Sexp])>>` — it embeds a fresh
    // `(head string, NAME string, spec args sequence)` triple into a
    // symbol-headed `(head NAME spec_args…)` `Sexp::List` value at ONE
    // site on the outer `Sexp` algebra, composing the call-form
    // typed constructor `Sexp::call` (which itself composes the atomic
    // `Sexp::symbol` head with the residual `Sexp::list` wrapper) with
    // a NAME-slot `Sexp::symbol` embedding via `std::iter::once(
    // Sexp::symbol(name)).chain(spec_args)`. Pre-lift the composition
    // lived inline at every consumer that built a `(defX NAME …)`
    // typed-domain named authoring form or a synthetic named-dispatch
    // form — `Sexp::List(vec![Sexp::symbol(head), Sexp::symbol(name),
    // spec_args...])` or `Sexp::call(head, std::iter::once(
    // Sexp::symbol(name)).chain(spec_args))` was the welded quadruple
    // open coding. Post-lift the closure binds at ONE typed-algebra
    // method.
    //
    // These pins cover:
    //   (a) the composition law
    //       `Sexp::named_call(head, name, spec_args) == Sexp::call(
    //       head, std::iter::once(Sexp::symbol(name)).chain(spec_args))`
    //       — the constructor body is BY DEFINITION the two-method
    //       composition;
    //   (b) the round-trip law
    //       `Sexp::named_call(head, name, spec_args.clone())
    //       .as_named_call_to(head) == Some(Ok((name, spec_args
    //       .as_slice())))` — the (construct, named-project) named-
    //       call-form algebra dual closes at this pair, symmetric with
    //       the call-form's `Sexp::call(head, args.clone()).as_call()
    //       == Some((head, args.as_slice()))` round-trip;
    //   (c) the call-form projection composition
    //       `Sexp::named_call(head, name, spec_args)
    //       .as_call() == Some((head, [Sexp::symbol(name),
    //       spec_args…].as_slice()))` — the call-form soft-projection
    //       recovers `(head, [name, spec_args…])` with the NAME symbol
    //       as the first arg, threading the constructor's output
    //       through the encompassing call-form projection;
    //   (d) the keyword-matched round-trip law
    //       `Sexp::named_call(head, name, spec_args)
    //       .as_call_to(head) == Some([Sexp::symbol(name),
    //       spec_args…].as_slice())` — the keyword-typed projection
    //       recovers the NAME-headed args tail iff its argument
    //       matches the constructor's head;
    //   (e) the head-symbol composition law
    //       `Sexp::named_call(head, name, spec_args).head_symbol()
    //       == Some(head)` — the head-position projection recovers
    //       the constructor's head byte-for-byte;
    //   (f) the named-form gate composition law
    //       `crate::compile::split_name_slot(&Sexp::named_call(head,
    //       name, spec_args).as_call_to(head).unwrap(), head) == Ok((
    //       name, spec_args.as_slice()))` — the substrate's named-
    //       form arity + NAME-shape gate accepts every output of this
    //       constructor byte-for-byte, closing the section-for-
    //       retraction pair at the gate level as well as the
    //       projection level;
    //   (g) the outer-shape composition law
    //       `Sexp::named_call(head, name, spec_args).shape() ==
    //       SexpShape::List` and `.as_structural_kind() == Some(
    //       StructuralKind::List)` — the residual carving marker binds
    //       through the closed-set `StructuralKind` algebra at ONE
    //       arm, symmetric with `Sexp::call`'s residual-arm marker
    //       composition;
    //   (h) the input-shape flexibility
    //       `Sexp::named_call("h", "n", Vec<Sexp>)` / `Sexp::
    //       named_call(String, String, [Sexp; N])` / `Sexp::
    //       named_call(&str, &String, iter::map(...))` all agree with
    //       the canonical composition emission — the two `impl
    //       Into<String>` bounds + `impl IntoIterator<Item = Sexp>`
    //       args bound accept every reasonable input shape without a
    //       per-consumer `.to_string()` / `.collect::<Vec<Sexp>>()`
    //       coercion.

    #[test]
    fn sexp_named_call_constructor_body_matches_canonical_two_method_composition_across_representative_inputs(
    ) {
        // COMPOSITION LAW: `Sexp::named_call(head, name, spec_args) ==
        // Sexp::call(head, std::iter::once(Sexp::symbol(name)).chain(
        // spec_args))` for every representative (empty-spec-args,
        // single-spec-arg, multi-spec-arg, heterogeneous-inner,
        // quote-family-wrapping-inner) sample. A regression that
        // drifts the body (e.g. a copy-edit that switches to
        // `Sexp::keyword(name)` for the NAME position, or that
        // reorders `name` and `spec_args` in the chain) surfaces here
        // BEFORE the projection pins fail. Sibling-shape pin to
        // `Sexp::call`'s canonical-composition test posture.
        let samples: [(&'static str, &'static str, Vec<Sexp>); 5] = [
            ("defcompiler", "solo", vec![]),
            ("defpoint", "obs", vec![Sexp::keyword("class")]),
            (
                "defmonitor",
                "m",
                vec![
                    Sexp::keyword("severity"),
                    Sexp::symbol("Warning"),
                    Sexp::keyword("threshold"),
                    Sexp::int(42),
                ],
            ),
            (
                "defcheck",
                "coherent",
                vec![
                    Sexp::List(vec![Sexp::symbol("crd-in-sync")]),
                    Sexp::string("body"),
                    Sexp::boolean(true),
                ],
            ),
            (
                "defalert-policy",
                "outage",
                vec![
                    Sexp::Quote(Box::new(Sexp::symbol("x"))),
                    Sexp::Quasiquote(Box::new(Sexp::List(vec![
                        Sexp::symbol("template"),
                        Sexp::Unquote(Box::new(Sexp::symbol("var"))),
                    ]))),
                    Sexp::UnquoteSplice(Box::new(Sexp::symbol("xs"))),
                ],
            ),
        ];
        for (head, name, spec_args) in &samples {
            let expected = Sexp::call(
                *head,
                std::iter::once(Sexp::symbol(*name)).chain(spec_args.iter().cloned()),
            );
            assert_eq!(
                Sexp::named_call(*head, *name, spec_args.clone()),
                expected,
                "Sexp::named_call drifted from Sexp::call(head, once(symbol(name)).chain(spec_args)) for head={head:?} name={name:?} spec_args={spec_args:?}",
            );
        }
    }

    #[test]
    fn sexp_named_call_constructor_round_trips_through_as_named_call_to() {
        // ROUND-TRIP LAW (section-for-retraction with the named-form
        // soft-projection): `Sexp::named_call(head, name, spec_args
        // .clone()).as_named_call_to(head) == Some(Ok((name,
        // spec_args.as_slice())))` sweeps the same representative
        // input matrix — proves the (construct, named-project) pair
        // forms an `Iso((&'static str, &str, Vec<Sexp>),
        // (head-symbol-headed + NAME-symbol-second Sexp::List))` on
        // the named-call-form typed decomposition. Sibling-shape pin
        // to `Sexp::call`'s round-trip through `as_call` posture.
        let samples: [(&'static str, &'static str, Vec<Sexp>); 4] = [
            ("defcompiler", "solo", vec![]),
            ("defpoint", "obs", vec![Sexp::keyword("class")]),
            (
                "defmonitor",
                "m",
                vec![Sexp::keyword("k"), Sexp::string("v")],
            ),
            (
                "defalert-policy",
                "outage",
                vec![Sexp::Nil, Sexp::List(vec![Sexp::symbol("body")])],
            ),
        ];
        for (head, name, spec_args) in &samples {
            let built = Sexp::named_call(*head, *name, spec_args.clone());
            assert_eq!(
                built.as_named_call_to(head).and_then(|res| res.ok()),
                Some((*name, spec_args.as_slice())),
                "Sexp::named_call→as_named_call_to round-trip drifted for head={head:?} name={name:?} spec_args={spec_args:?}",
            );
        }
    }

    #[test]
    fn sexp_named_call_constructor_projects_through_as_call_with_name_first_arg() {
        // CALL-FORM PROJECTION COMPOSITION: `Sexp::named_call(head,
        // name, spec_args).as_call() == Some((head, [Sexp::symbol(
        // name), spec_args…].as_slice()))` — the call-form soft-
        // projection recovers `(head, [name, spec_args…])` with the
        // NAME symbol as the first arg. Sibling-shape pin to the
        // call-form encompassing algebra: the named-call constructor
        // routes cleanly through the call-form projection AS A
        // COMPOSITION.
        let samples: [(&'static str, &'static str, Vec<Sexp>); 3] = [
            ("defcompiler", "solo", vec![]),
            ("defpoint", "obs", vec![Sexp::keyword("class")]),
            (
                "defmonitor",
                "m",
                vec![Sexp::keyword("threshold"), Sexp::int(42)],
            ),
        ];
        for (head, name, spec_args) in &samples {
            let built = Sexp::named_call(*head, *name, spec_args.clone());
            let expected_args: Vec<Sexp> = std::iter::once(Sexp::symbol(*name))
                .chain(spec_args.iter().cloned())
                .collect();
            assert_eq!(
                built.as_call(),
                Some((*head, expected_args.as_slice())),
                "Sexp::named_call→as_call drifted for head={head:?} name={name:?} spec_args={spec_args:?}",
            );
        }
    }

    #[test]
    fn sexp_named_call_constructor_round_trips_through_as_call_to_matching_keyword() {
        // KEYWORD-MATCHED ROUND-TRIP LAW: `Sexp::named_call(head,
        // name, spec_args.clone()).as_call_to(head) == Some([
        // Sexp::symbol(name), spec_args…].as_slice())` for the head-
        // matched keyword, and `.as_call_to(other) == None` for every
        // other keyword. Pins the (construct, keyword-typed-project)
        // pair on the outer algebra threading through the NAMED axis
        // — the same dispatch shape `compile_named_from_forms` routes
        // through post-macroexpansion.
        let samples: [(&'static str, &'static str, Vec<Sexp>); 3] = [
            ("defcompiler", "solo", vec![]),
            ("defpoint", "obs", vec![Sexp::keyword("class")]),
            (
                "defmonitor",
                "m",
                vec![Sexp::keyword("k"), Sexp::string("v")],
            ),
        ];
        for (head, name, spec_args) in &samples {
            let built = Sexp::named_call(*head, *name, spec_args.clone());
            let expected_args: Vec<Sexp> = std::iter::once(Sexp::symbol(*name))
                .chain(spec_args.iter().cloned())
                .collect();
            assert_eq!(
                built.as_call_to(head),
                Some(expected_args.as_slice()),
                "Sexp::named_call→as_call_to(head) round-trip drifted for head={head:?} name={name:?} spec_args={spec_args:?}",
            );
            // Cross-keyword rejection: every DIFFERENT keyword misses.
            let mismatched = format!("{head}-mismatch");
            assert_eq!(
                built.as_call_to(&mismatched),
                None,
                "Sexp::named_call→as_call_to(mismatch) leaked args for head={head:?} name={name:?}",
            );
        }
    }

    #[test]
    fn sexp_named_call_constructor_composes_with_head_symbol_and_shape_and_structural_kind() {
        // OUTER-ALGEBRA PROJECTION COMPOSITIONS: every `Sexp::
        // named_call(head, name, spec_args)` output projects through
        // `head_symbol` / `shape` / `as_structural_kind` to the shape-
        // invariants that pin the constructor's structural identity:
        //   * `head_symbol() == Some(head)` — the head-position
        //     projection recovers the constructor's head byte-for-byte;
        //   * `shape() == SexpShape::List` — a named call form is a
        //     list-shaped `Sexp` on the residual carving;
        //   * `as_structural_kind() == Some(StructuralKind::List)` —
        //     the residual carving marker binds through the closed-
        //     set `StructuralKind` algebra at ONE arm.
        let samples: [(&'static str, &'static str, Vec<Sexp>); 3] = [
            ("head", "n", vec![]),
            ("head", "n", vec![Sexp::keyword("k"), Sexp::string("v")]),
            (
                "head",
                "n",
                vec![
                    Sexp::Nil,
                    Sexp::Quote(Box::new(Sexp::symbol("x"))),
                    Sexp::List(vec![Sexp::symbol("nested")]),
                ],
            ),
        ];
        for (head, name, spec_args) in &samples {
            let built = Sexp::named_call(*head, *name, spec_args.clone());
            assert_eq!(
                built.head_symbol(),
                Some(*head),
                "Sexp::named_call→head_symbol drifted from Some({head:?}) for name={name:?} spec_args={spec_args:?}",
            );
            assert_eq!(
                built.shape(),
                SexpShape::List,
                "Sexp::named_call→shape drifted from SexpShape::List for head={head:?} name={name:?} spec_args={spec_args:?}",
            );
            assert_eq!(
                built.as_structural_kind(),
                Some(StructuralKind::List),
                "Sexp::named_call→as_structural_kind drifted from Some(StructuralKind::List) for head={head:?} name={name:?} spec_args={spec_args:?}",
            );
        }
    }

    #[test]
    fn sexp_named_call_constructor_output_passes_the_split_name_slot_gate() {
        // NAMED-FORM GATE COMPOSITION LAW: `crate::compile::
        // split_name_slot(&Sexp::named_call(head, name, spec_args)
        // .as_call_to(head).unwrap(), head) == Ok((name, spec_args
        // .as_slice()))` — the substrate's named-form arity + NAME-
        // shape gate accepts every output of this constructor byte-
        // for-byte, closing the section-for-retraction pair at the
        // GATE level as well as the projection level. A regression
        // that emits a value the gate rejects (e.g. a
        // `NamedFormNonSymbolName` from a `Sexp::keyword(name)` NAME
        // slot copy-edit) surfaces here even when the projection
        // pins pass.
        let samples: [(&'static str, &'static str, Vec<Sexp>); 4] = [
            ("defcompiler", "solo", vec![]),
            ("defpoint", "obs", vec![Sexp::keyword("class")]),
            (
                "defmonitor",
                "m",
                vec![Sexp::keyword("severity"), Sexp::symbol("Warning")],
            ),
            (
                "defalert-policy",
                "outage",
                vec![
                    Sexp::List(vec![Sexp::symbol("body")]),
                    Sexp::Quote(Box::new(Sexp::symbol("x"))),
                ],
            ),
        ];
        for (head, name, spec_args) in &samples {
            let built = Sexp::named_call(*head, *name, spec_args.clone());
            let args_tail = built
                .as_call_to(head)
                .expect("Sexp::named_call output must pass Sexp::as_call_to(head)");
            let gated = crate::compile::split_name_slot(args_tail, head)
                .expect("Sexp::named_call output must pass split_name_slot");
            assert_eq!(
                gated,
                (*name, spec_args.as_slice()),
                "Sexp::named_call→split_name_slot round-trip drifted for head={head:?} name={name:?} spec_args={spec_args:?}",
            );
        }
    }

    #[test]
    fn sexp_named_call_constructor_accepts_diverse_head_name_and_arg_input_shapes() {
        // INPUT-SHAPE FLEXIBILITY: the two `impl Into<String>` bounds
        // absorb `&str` / `String` / `&String` on both head + NAME
        // positions, and the `impl IntoIterator<Item = Sexp>` spec-
        // args bound absorbs `Vec<Sexp>` / `[Sexp; N]` / `iter::
        // empty()` / `.map(...)` chains — pin that all five
        // representative input shapes reach the same canonical
        // composition output. A regression that narrows any bound
        // fails this pin. Sibling to `Sexp::call`'s input-shape pin.
        let expected = Sexp::List(vec![
            Sexp::symbol("head"),
            Sexp::symbol("name"),
            Sexp::symbol("a"),
            Sexp::symbol("b"),
        ]);
        // (&str, &str, Vec<Sexp>) — the canonical borrowed shape.
        assert_eq!(
            Sexp::named_call("head", "name", vec![Sexp::symbol("a"), Sexp::symbol("b")]),
            expected,
            "Sexp::named_call drifted for (&str, &str, Vec<Sexp>) input",
        );
        // (String, String, [Sexp; N]) — the owned + array-literal
        // shape.
        assert_eq!(
            Sexp::named_call(
                String::from("head"),
                String::from("name"),
                [Sexp::symbol("a"), Sexp::symbol("b")],
            ),
            expected,
            "Sexp::named_call drifted for (String, String, [Sexp; N]) input",
        );
        // (&str, &String, .map(...)) — the borrowed-owned-name +
        // iterator-map chain shape.
        let owned_name = String::from("name");
        assert_eq!(
            Sexp::named_call(
                "head",
                &owned_name,
                ["a", "b"].iter().map(|s| Sexp::symbol(*s))
            ),
            expected,
            "Sexp::named_call drifted for (&str, &String, iter::map) input",
        );
        // (&str, &str, iter::empty::<Sexp>()) — the zero-spec-args
        // iterator shape, pinning the two-element list emission
        // (`(head name)`) via the composition path.
        assert_eq!(
            Sexp::named_call("head", "name", std::iter::empty::<Sexp>()),
            Sexp::List(vec![Sexp::symbol("head"), Sexp::symbol("name")]),
            "Sexp::named_call drifted for zero-spec-args iter::empty input",
        );
        // (&str, &str, once+chain) — the head-then-rest spec-args
        // shape a builder decomposing an existing named call form
        // via `as_named_call_to` and re-emitting through this
        // constructor threads through.
        assert_eq!(
            Sexp::named_call(
                "head",
                "name",
                std::iter::once(Sexp::symbol("a")).chain([Sexp::symbol("b")]),
            ),
            expected,
            "Sexp::named_call drifted for (&str, &str, once+chain) spec-args input",
        );
    }

    #[test]
    fn sexp_named_call_constructor_body_matches_typed_composition_through_call_and_symbol() {
        // EXPLICIT COMPOSITION-LAW PIN: `Sexp::named_call(head, name,
        // spec_args) == Sexp::call(head, std::iter::once(Sexp::symbol(
        // name)).chain(spec_args))` BY DEFINITION — the constructor
        // body IS this composition, and the pin exists so a
        // regression that in-lines a hand-authored `Sexp::List(vec![
        // Sexp::symbol(head), Sexp::symbol(name), spec_args...])`
        // body (which would type-check and pass the projection round-
        // trips) still surfaces here through the composition-path
        // drift. Closes the "the constructor routes through
        // `Sexp::call` + `Sexp::symbol`" invariant as a typed pin
        // rather than a docstring claim.
        let head = "defpoint";
        let name = "observability-stack";
        let spec_args = vec![
            Sexp::keyword("class"),
            Sexp::List(vec![Sexp::symbol("Gate"), Sexp::symbol("Observability")]),
        ];
        assert_eq!(
            Sexp::named_call(head, name, spec_args.clone()),
            Sexp::call(
                head,
                std::iter::once(Sexp::symbol(name)).chain(spec_args.iter().cloned()),
            ),
            "Sexp::named_call body drifted from the Sexp::call ∘ once(Sexp::symbol) ∘ chain composition for head={head:?} name={name:?}",
        );
    }

    #[test]
    fn sexp_quote_form_constructor_body_matches_quote_form_wrap_across_every_marker() {
        // COMPOSITION-LAW PIN: `Sexp::quote_form(marker, inner) ==
        // marker.wrap(inner)` for every `marker: QuoteForm` and every
        // representative `inner: Sexp`. Sweeps `QuoteForm::ALL` × a
        // representative gallery of inner bodies (atomic-payload,
        // residual-Nil, residual-List, quote-family-nested,
        // named-call-shaped) so a regression in the constructor body
        // that inlined a per-variant match arm — e.g. `match marker {
        // QuoteForm::Quote => Sexp::Quote(Box::new(inner)), … }` —
        // that drifts one arm's tuple-variant target from the closed-
        // set `QuoteForm::wrap` marker-to-wrapper mapping fails
        // loudly at the first drifted variant. Pointer-inequality
        // safe: `assert_eq!` compares by value, so the pin binds the
        // structural composition path rather than any borrowed
        // pointer identity.
        let inners: Vec<Sexp> = vec![
            Sexp::symbol("x"),
            Sexp::keyword("k"),
            Sexp::string("hello"),
            Sexp::int(42),
            Sexp::float(2.5),
            Sexp::boolean(true),
            Sexp::Nil,
            Sexp::list(vec![Sexp::symbol("a"), Sexp::int(1)]),
            Sexp::quote(Sexp::symbol("nested")),
            Sexp::named_call(
                "defpoint",
                "observability-stack",
                std::iter::empty::<Sexp>(),
            ),
        ];
        for marker in QuoteForm::ALL {
            for inner in &inners {
                assert_eq!(
                    Sexp::quote_form(marker, inner.clone()),
                    marker.wrap(inner.clone()),
                    "Sexp::quote_form body drifted from QuoteForm::wrap composition at marker={marker:?} inner={inner:?}",
                );
            }
        }
    }

    #[test]
    fn sexp_quote_form_constructor_round_trips_through_as_quote_form_for_every_marker() {
        // ROUND-TRIP LAW PIN (section-for-retraction with the outer-
        // algebra soft-projection): for every `marker: QuoteForm` +
        // representative `inner: Sexp`, `Sexp::quote_form(marker,
        // inner.clone()).as_quote_form() == Some((marker, &inner))`.
        // Proves the (construct, project) pair forms an isomorphism
        // between (QuoteForm × Sexp) and the closed-set 4-of-12 quote-
        // family carving of the outer `Sexp` algebra — a regression
        // that emits a value the projection rejects (unreachable by
        // the closed-set structure, since `QuoteForm::wrap` targets a
        // quote-family arm exactly) or that drifts the marker
        // recovered from the projection (e.g. swapping `Quote` ↔
        // `Quasiquote` in the constructor's dispatch) fails loudly
        // at the first drifted variant.
        for marker in QuoteForm::ALL {
            let inner = Sexp::List(vec![Sexp::keyword("body"), Sexp::string("data")]);
            let wrapped = Sexp::quote_form(marker, inner.clone());
            assert_eq!(
                wrapped.as_quote_form(),
                Some((marker, &inner)),
                "Sexp::quote_form({marker:?}, _).as_quote_form() failed to round-trip — the (construct, project) pair on the outer algebra is not a section-for-retraction of Sexp::as_quote_form",
            );
        }
    }

    #[test]
    fn sexp_quote_form_constructor_composes_with_as_quote_form_marker_and_shape() {
        // MARKER-RECOVERING + OUTER-SHAPE COMPOSITION PIN: for every
        // `marker: QuoteForm` + representative `inner: Sexp`, the
        // constructor's output projects through the marker-only sibling
        // `Sexp::as_quote_form_marker` back to the constructor's marker
        // AND through the outer-shape projection `Sexp::shape` to the
        // canonical `marker.sexp_shape()`. Pins the two independent
        // projection compositions simultaneously so a regression that
        // reroutes through a non-quote-family arm (which the outer-
        // shape lattice would surface as `SexpShape::List` or
        // `SexpShape::Nil`) fails BOTH pins at once.
        for marker in QuoteForm::ALL {
            let inner = Sexp::symbol("body");
            let wrapped = Sexp::quote_form(marker, inner.clone());
            assert_eq!(
                wrapped.as_quote_form_marker(),
                Some(marker),
                "Sexp::quote_form({marker:?}, _).as_quote_form_marker() drifted from Some({marker:?})",
            );
            assert_eq!(
                wrapped.shape(),
                marker.sexp_shape(),
                "Sexp::quote_form({marker:?}, _).shape() drifted from {marker:?}.sexp_shape()",
            );
        }
    }

    #[test]
    fn sexp_quote_form_constructor_specializes_to_each_per_variant_sibling() {
        // PER-VARIANT RESTRICTION LAW PIN: the four per-variant
        // siblings ARE the marker-driven parent specialized on a
        // compile-time-known marker — `Sexp::quote_form(QuoteForm::X,
        // inner) == Sexp::x_variant(inner)` for every X ∈
        // {Quote, Quasiquote, Unquote, UnquoteSplice}. Any regression
        // that drifts the marker-driven parent from its per-variant
        // siblings' single canonical composition site
        // (`QuoteForm::X.wrap(inner)`) fails at the first drifted
        // variant.
        let inner = Sexp::symbol("body");
        assert_eq!(
            Sexp::quote_form(QuoteForm::Quote, inner.clone()),
            Sexp::quote(inner.clone()),
            "Sexp::quote_form(QuoteForm::Quote, _) drifted from Sexp::quote(_)",
        );
        assert_eq!(
            Sexp::quote_form(QuoteForm::Quasiquote, inner.clone()),
            Sexp::quasiquote(inner.clone()),
            "Sexp::quote_form(QuoteForm::Quasiquote, _) drifted from Sexp::quasiquote(_)",
        );
        assert_eq!(
            Sexp::quote_form(QuoteForm::Unquote, inner.clone()),
            Sexp::unquote(inner.clone()),
            "Sexp::quote_form(QuoteForm::Unquote, _) drifted from Sexp::unquote(_)",
        );
        assert_eq!(
            Sexp::quote_form(QuoteForm::UnquoteSplice, inner.clone()),
            Sexp::unquote_splice(inner),
            "Sexp::quote_form(QuoteForm::UnquoteSplice, _) drifted from Sexp::unquote_splice(_)",
        );
    }

    #[test]
    fn sexp_quote_form_constructor_targets_matching_tuple_variant_for_every_marker() {
        // TUPLE-VARIANT-TARGET PIN: `Sexp::quote_form(marker, inner)`
        // must be structurally equal to `Sexp::X(Box::new(inner))` for
        // the X matching the marker — pinned per variant against the
        // hand-authored tuple-variant literal so a regression that
        // reroutes the wrap through an off-by-one closed-set match
        // (e.g. `QuoteForm::Quote → Sexp::Quasiquote`) surfaces at
        // this shape pin even when the round-trip law happens to
        // still project through the projection sibling (it wouldn't —
        // but the pin gives a distinct, tuple-variant-anchored
        // failure signature). Sibling-shape lift to the same-anchor
        // pin the `QuoteForm::wrap` inner algebra already carries.
        let inner = Sexp::string("payload");
        assert_eq!(
            Sexp::quote_form(QuoteForm::Quote, inner.clone()),
            Sexp::Quote(Box::new(inner.clone())),
            "Sexp::quote_form(QuoteForm::Quote, _) drifted from Sexp::Quote(Box::new(_)) canonical tuple-variant shape",
        );
        assert_eq!(
            Sexp::quote_form(QuoteForm::Quasiquote, inner.clone()),
            Sexp::Quasiquote(Box::new(inner.clone())),
            "Sexp::quote_form(QuoteForm::Quasiquote, _) drifted from Sexp::Quasiquote(Box::new(_)) canonical tuple-variant shape",
        );
        assert_eq!(
            Sexp::quote_form(QuoteForm::Unquote, inner.clone()),
            Sexp::Unquote(Box::new(inner.clone())),
            "Sexp::quote_form(QuoteForm::Unquote, _) drifted from Sexp::Unquote(Box::new(_)) canonical tuple-variant shape",
        );
        assert_eq!(
            Sexp::quote_form(QuoteForm::UnquoteSplice, inner.clone()),
            Sexp::UnquoteSplice(Box::new(inner)),
            "Sexp::quote_form(QuoteForm::UnquoteSplice, _) drifted from Sexp::UnquoteSplice(Box::new(_)) canonical tuple-variant shape",
        );
    }

    #[test]
    fn sexp_unquote_form_constructor_body_matches_unquote_form_wrap_across_every_marker() {
        // COMPOSITION-LAW PIN: `Sexp::unquote_form(marker, inner) ==
        // marker.wrap(inner)` for every `marker: UnquoteForm` and every
        // representative `inner: Sexp`. Sweeps `UnquoteForm::ALL` × a
        // representative gallery of inner bodies (atomic-payload,
        // residual-Nil, residual-List, quote-family-nested, unquote-
        // subset-nested, named-call-shaped) so a regression that
        // inlined a per-variant match arm — e.g. `match marker {
        // UnquoteForm::Unquote => Sexp::Unquote(Box::new(inner)),
        // UnquoteForm::Splice => Sexp::UnquoteSplice(Box::new(inner)) }`
        // — that drifts one arm's tuple-variant target from the closed-
        // set `UnquoteForm::wrap` marker-to-wrapper mapping fails
        // loudly at the first drifted variant.
        let inners: Vec<Sexp> = vec![
            Sexp::symbol("x"),
            Sexp::keyword("k"),
            Sexp::string("hello"),
            Sexp::int(42),
            Sexp::float(2.5),
            Sexp::boolean(true),
            Sexp::Nil,
            Sexp::list(vec![Sexp::symbol("a"), Sexp::int(1)]),
            Sexp::quote(Sexp::symbol("nested")),
            Sexp::unquote(Sexp::symbol("subnested")),
            Sexp::named_call(
                "defpoint",
                "observability-stack",
                std::iter::empty::<Sexp>(),
            ),
        ];
        for marker in UnquoteForm::ALL {
            for inner in &inners {
                assert_eq!(
                    Sexp::unquote_form(marker, inner.clone()),
                    marker.wrap(inner.clone()),
                    "Sexp::unquote_form body drifted from UnquoteForm::wrap composition at marker={marker:?} inner={inner:?}",
                );
            }
        }
    }

    #[test]
    fn sexp_unquote_form_constructor_round_trips_through_as_unquote_for_every_marker() {
        // ROUND-TRIP LAW PIN (section-for-retraction with the outer-
        // algebra soft-projection): for every `marker: UnquoteForm` +
        // representative `inner: Sexp`, `Sexp::unquote_form(marker,
        // inner.clone()).as_unquote() == Some((marker, &inner))`.
        // Proves the (construct, project) pair forms an isomorphism
        // between (UnquoteForm × Sexp) and the closed-set 2-of-12
        // template-substitution subset carving of the outer `Sexp`
        // algebra — a regression that emits a value the projection
        // rejects (e.g. drifting to a non-substitution quote-family
        // arm like `Sexp::Quote`, which `as_unquote` filters out via
        // `QuoteForm::as_unquote_form`) or that drifts the marker
        // recovered from the projection (e.g. swapping `Unquote` ↔
        // `Splice`) fails loudly at the first drifted variant.
        for marker in UnquoteForm::ALL {
            let inner = Sexp::List(vec![Sexp::keyword("body"), Sexp::string("data")]);
            let wrapped = Sexp::unquote_form(marker, inner.clone());
            assert_eq!(
                wrapped.as_unquote(),
                Some((marker, &inner)),
                "Sexp::unquote_form({marker:?}, _).as_unquote() failed to round-trip — the (construct, project) pair on the outer algebra is not a section-for-retraction of Sexp::as_unquote",
            );
        }
    }

    #[test]
    fn sexp_unquote_form_constructor_composes_with_as_unquote_form_and_shape() {
        // MARKER-RECOVERING + OUTER-SHAPE COMPOSITION PIN: for every
        // `marker: UnquoteForm` + representative `inner: Sexp`, the
        // constructor's output projects through the marker-only sibling
        // `Sexp::as_unquote_form` back to the constructor's marker AND
        // through the outer-shape projection `Sexp::shape` to the
        // canonical `marker.sexp_shape()`. Pins the two independent
        // projection compositions simultaneously so a regression that
        // reroutes through a non-substitution quote-family arm
        // (`SexpShape::Quote` / `SexpShape::Quasiquote`) or through a
        // non-quote-family arm (`SexpShape::List` / `SexpShape::Nil`)
        // fails BOTH pins at once.
        for marker in UnquoteForm::ALL {
            let inner = Sexp::symbol("body");
            let wrapped = Sexp::unquote_form(marker, inner.clone());
            assert_eq!(
                wrapped.as_unquote_form(),
                Some(marker),
                "Sexp::unquote_form({marker:?}, _).as_unquote_form() drifted from Some({marker:?})",
            );
            assert_eq!(
                wrapped.shape(),
                marker.sexp_shape(),
                "Sexp::unquote_form({marker:?}, _).shape() drifted from {marker:?}.sexp_shape()",
            );
        }
    }

    #[test]
    fn sexp_unquote_form_constructor_routes_through_superset_quote_form_via_to_quote_form() {
        // SUPERSET-ROUTING COMPOSITION-LAW PIN: for every `marker:
        // UnquoteForm` + representative `inner: Sexp`, `Sexp::unquote_form(
        // marker, inner) == Sexp::quote_form(marker.to_quote_form(),
        // inner)`. The subset-algebra construct routes through the
        // SAME closed-set `QuoteForm::wrap` composition site the
        // superset construct routes through — threaded via the typed
        // 2-of-4 subset → superset projection `UnquoteForm::to_quote_form`.
        // A regression that re-implements the subset construct on a
        // parallel dispatch table (rather than composing through the
        // superset construct's composition site) can still project
        // through `as_unquote` correctly on the round-trip pin above,
        // but will fail this pin because the constructed values compare
        // equal only when both routes bind at the same closed-set
        // `QuoteForm::wrap` arm. Structural sibling of the composition
        // law `UnquoteForm::wrap` itself carries at ast.rs:2469 —
        // `self.to_quote_form().wrap(inner)`.
        for marker in UnquoteForm::ALL {
            let inner = Sexp::List(vec![Sexp::symbol("outer"), Sexp::int(7)]);
            assert_eq!(
                Sexp::unquote_form(marker, inner.clone()),
                Sexp::quote_form(marker.to_quote_form(), inner.clone()),
                "Sexp::unquote_form({marker:?}, _) drifted from Sexp::quote_form({:?}, _) — subset-construct did not route through superset-construct via UnquoteForm::to_quote_form",
                marker.to_quote_form(),
            );
        }
    }

    #[test]
    fn sexp_unquote_form_constructor_specializes_to_each_per_variant_sibling() {
        // PER-VARIANT RESTRICTION LAW PIN: the two per-variant siblings
        // ARE the marker-driven parent specialized on a compile-time-
        // known subset marker — `Sexp::unquote_form(UnquoteForm::X,
        // inner) == Sexp::x_variant(inner)` for every X ∈ {Unquote,
        // Splice}. Any regression that drifts the marker-driven parent
        // from its per-variant siblings' single canonical composition
        // site (`UnquoteForm::X.wrap(inner)` → `QuoteForm::X.wrap(inner)`)
        // fails at the first drifted variant.
        let inner = Sexp::symbol("body");
        assert_eq!(
            Sexp::unquote_form(UnquoteForm::Unquote, inner.clone()),
            Sexp::unquote(inner.clone()),
            "Sexp::unquote_form(UnquoteForm::Unquote, _) drifted from Sexp::unquote(_)",
        );
        assert_eq!(
            Sexp::unquote_form(UnquoteForm::Splice, inner.clone()),
            Sexp::unquote_splice(inner),
            "Sexp::unquote_form(UnquoteForm::Splice, _) drifted from Sexp::unquote_splice(_)",
        );
    }

    #[test]
    fn sexp_unquote_form_constructor_targets_matching_tuple_variant_for_every_marker() {
        // TUPLE-VARIANT-TARGET PIN: `Sexp::unquote_form(marker, inner)`
        // must be structurally equal to `Sexp::X(Box::new(inner))` for
        // the X matching the subset marker (`Unquote → Sexp::Unquote`,
        // `Splice → Sexp::UnquoteSplice`) — pinned per variant against
        // the hand-authored tuple-variant literal so a regression that
        // reroutes the wrap through an off-by-one closed-set match
        // (e.g. `UnquoteForm::Unquote → Sexp::UnquoteSplice`, or the
        // subset→superset projection drifting `UnquoteForm::Unquote →
        // QuoteForm::Quote` inside `to_quote_form`) surfaces at this
        // shape pin with a distinct, tuple-variant-anchored failure
        // signature. Sibling-shape lift to the same-anchor pin the
        // `QuoteForm::wrap` inner algebra already carries on the
        // superset 4-of-4 arms.
        let inner = Sexp::string("payload");
        assert_eq!(
            Sexp::unquote_form(UnquoteForm::Unquote, inner.clone()),
            Sexp::Unquote(Box::new(inner.clone())),
            "Sexp::unquote_form(UnquoteForm::Unquote, _) drifted from Sexp::Unquote(Box::new(_)) canonical tuple-variant shape",
        );
        assert_eq!(
            Sexp::unquote_form(UnquoteForm::Splice, inner.clone()),
            Sexp::UnquoteSplice(Box::new(inner)),
            "Sexp::unquote_form(UnquoteForm::Splice, _) drifted from Sexp::UnquoteSplice(Box::new(_)) canonical tuple-variant shape",
        );
    }

    // ── `Atom::KEYWORD_MARKER` — the canonical `:` prefix routed through
    // the four Keyword-round-trip sites (reader-entry classifier, Lisp
    // canonical Display, JSON canonical projection, iac-forge canonical
    // projection). Pins the constant value AND the four sites' composition
    // through it so a regression that re-inlines any single site's byte
    // literal drifts against these pins even when the rendered bytes still
    // agree at that site.

    #[test]
    fn atom_keyword_marker_projects_canonical_colon_byte() {
        assert_eq!(
            Atom::KEYWORD_MARKER,
            ":",
            "KEYWORD_MARKER byte drifted from the substrate-canonical `:` \
             prefix — the reader-round-trip contract at Self::from_lexeme \
             + fmt::Display for Atom + Self::to_json + \
             Self::to_iac_forge_sexpr all bind to this one constant.",
        );
    }

    #[test]
    fn atom_display_keyword_arm_routes_through_keyword_marker_constant() {
        for name in ["parent", "class", "intent", "x", ""] {
            let rendered = Atom::keyword(name).to_string();
            let expected = format!("{}{name}", Atom::KEYWORD_MARKER);
            assert_eq!(
                rendered, expected,
                "fmt::Display for Atom's Keyword arm drifted from the \
                 KEYWORD_MARKER composition at name={name:?}",
            );
        }
    }

    #[test]
    fn atom_to_json_keyword_arm_routes_through_keyword_marker_constant() {
        for name in ["parent", "class", "intent", "x", ""] {
            let projected = Atom::keyword(name).to_json();
            let expected = serde_json::Value::String(format!("{}{name}", Atom::KEYWORD_MARKER));
            assert_eq!(
                projected, expected,
                "Atom::to_json's Keyword arm drifted from the \
                 KEYWORD_MARKER composition at name={name:?}",
            );
        }
    }

    #[test]
    fn atom_from_lexeme_keyword_classifier_routes_through_keyword_marker_constant() {
        for name in ["parent", "class", "intent", "x", ""] {
            let lexeme = format!("{}{name}", Atom::KEYWORD_MARKER);
            let classified = Atom::from_lexeme(&lexeme);
            assert_eq!(
                classified,
                Atom::keyword(name),
                "Atom::from_lexeme's Keyword classifier drifted from the \
                 KEYWORD_MARKER strip at lexeme={lexeme:?}",
            );
        }
    }

    #[test]
    fn atom_keyword_marker_closes_reader_display_round_trip_for_every_name() {
        // The load-bearing round-trip contract:
        //   Atom::from_lexeme(&Atom::keyword(name).to_string())
        //   == Atom::keyword(name)
        // Both sides bind to Atom::KEYWORD_MARKER — the reader-entry
        // classifier strips it via strip_prefix, the canonical-form
        // Display re-emits it via write!. A future refactor that
        // silently drifts ONE site's byte (e.g. by re-inlining `":"` at
        // Display while migrating `strip_prefix` to a different byte)
        // breaks THIS round-trip even when both bytes happen to agree on
        // the surface — because the round-trip binds to the composition
        // through the constant at BOTH endpoints.
        for name in ["parent", "class", "intent", "x", "kebab-cased-name"] {
            let a = Atom::keyword(name);
            let round_tripped = Atom::from_lexeme(&a.to_string());
            assert_eq!(
                round_tripped, a,
                "keyword round-trip through KEYWORD_MARKER drifted at \
                 name={name:?}",
            );
        }
    }

    // ── `Atom::KEYWORD_MARKER_LEAD` — the canonical `:` LEAD `char`
    // of the `Atom::KEYWORD_MARKER` `&'static str` prefix, routed
    // through the SEVEN test-surface sites that pre-lift each extracted
    // the byte via `Atom::KEYWORD_MARKER.chars().next().expect(_)`
    // (or `.unwrap()`) — the Keyword arm of the
    // `Sexp::is_bare_atom_boundary` negative sweep AND the six cross-
    // axis disjointness pins on the sibling marker-byte algebras
    // (`SPLICE_DISCRIMINATOR`, `BOOL_LITERAL_LEAD`, `STR_DELIMITER`,
    // `STR_ESCAPE_LEAD`, `LIST_OPEN` / `LIST_CLOSE`, `COMMENT_LEAD`,
    // `COMMENT_TERM`). Sibling-shape tests to the `atom_bool_literal_lead_*`
    // block below (Bool-family shared LEAD-byte axis) and the
    // `atom_str_delimiter_*` / `atom_str_escape_lead_*` blocks below
    // (Str-payload delimiter + escape-lead axes) — pins the SAME shape
    // on the Keyword-prefix LEAD-byte axis of the closed-set outer
    // [`Atom`] algebra.

    #[test]
    fn atom_keyword_marker_lead_projects_canonical_colon_char() {
        // Pins the constant's exact `char` value so a typo (`';'`,
        // `'.'`, `'!'`) or an accidental redefinition surfaces
        // immediately. Sibling-shape pin to
        // `atom_bool_literal_lead_projects_canonical_hash_char`
        // (the Bool-family shared LEAD-byte axis) and
        // `atom_str_delimiter_projects_canonical_double_quote_char`
        // (the Str-payload delimiter axis) — pins the SAME shape on
        // the Keyword-prefix LEAD-byte axis of the closed-set outer
        // [`Atom`] algebra.
        assert_eq!(
            Atom::KEYWORD_MARKER_LEAD,
            ':',
            "KEYWORD_MARKER_LEAD char drifted from the substrate- \
             canonical `:` LEAD byte — the seven test-surface sites \
             that pre-lift each extracted this byte from \
             Atom::KEYWORD_MARKER via `.chars().next().expect(_)` all \
             bind to this ONE constant.",
        );
    }

    #[test]
    fn atom_keyword_marker_lead_prefixes_keyword_marker() {
        // STRUCTURAL ROUND-TRIP CONTRACT: the `&'static str` prefix
        // `Atom::KEYWORD_MARKER` starts with the `char` LEAD byte
        // `Atom::KEYWORD_MARKER_LEAD` — the projection law that binds
        // the two typed constants on the outer [`Atom`] algebra. A
        // regression that renames the `&'static str` (e.g. `"#:"` for
        // a Racket-compat `#:name` keyword-arg port) OR the `char`
        // (e.g. to `'.'` for a dotted-path prefix) without updating the
        // other fails HERE — the structural invariant that
        // `KEYWORD_MARKER_LEAD` IS the lead byte of `KEYWORD_MARKER`
        // is what makes the seven consumer sites safe to route
        // through the `char` constant instead of the `&'static str`
        // projection. Sibling-shape pin to
        // `atom_bool_literal_lead_prefixes_every_bool_literal_spelling`
        // on the Bool-family axis: where that pin sweeps every `b:
        // bool` spelling to prove BOTH spellings share the lead byte,
        // this pin binds the one-char `KEYWORD_MARKER` prefix to its
        // projected lead byte via a single `starts_with` call.
        //
        // Load-bearing: this pin IS the "the two typed constants
        // project onto each other" invariant that lets the seven
        // consumer sites bind to the `char` constant instead of the
        // `.chars().next().expect(_)` chain on the `&'static str`.
        assert!(
            Atom::KEYWORD_MARKER.starts_with(Atom::KEYWORD_MARKER_LEAD),
            "Atom::KEYWORD_MARKER `{}` does NOT start with \
             Atom::KEYWORD_MARKER_LEAD `{:?}` — the two typed constants \
             have drifted apart on the closed-set outer [`Atom`] \
             algebra; the seven consumer sites that route through the \
             `char` constant instead of the `&'static str` projection \
             would silently disagree with the reader's actual `:foo` \
             classification.",
            Atom::KEYWORD_MARKER,
            Atom::KEYWORD_MARKER_LEAD,
        );
    }

    #[test]
    fn atom_keyword_marker_lead_distinct_from_every_other_algebra_marker() {
        // CROSS-AXIS DISJOINTNESS PIN: `Atom::KEYWORD_MARKER_LEAD`
        // MUST NOT alias any sibling outer-marker `char` on the
        // substrate's other closed-set algebras — the Str-payload
        // delimiter (`Atom::STR_DELIMITER`), Str-payload escape lead
        // (`Atom::STR_ESCAPE_LEAD`), Bool-family shared lead
        // (`Atom::BOOL_LITERAL_LEAD`), the paired list delimiters
        // (`Sexp::LIST_OPEN` / `Sexp::LIST_CLOSE`), the paired line-
        // comment delimiters (`Sexp::COMMENT_LEAD` /
        // `Sexp::COMMENT_TERM`), every `QuoteForm::lead_char`
        // projection, AND `QuoteForm::SPLICE_DISCRIMINATOR`. A
        // collision would silently break the reader's outer dispatch:
        // a `:`-prefixed bare atom `:foo` would collide with whichever
        // marker it aliased. Sibling-shape pin to
        // `atom_bool_literal_lead_distinct_from_every_other_algebra_marker`
        // (the Bool-family LEAD-byte axis) — pins the SAME shape at
        // the Keyword-prefix LEAD-byte axis. A future outer-marker
        // extension that collided with `':'` fails HERE at the cross-
        // axis enumeration.
        assert_ne!(
            Atom::KEYWORD_MARKER_LEAD,
            Atom::STR_DELIMITER,
            "KEYWORD_MARKER_LEAD collides with STR_DELIMITER — a bare \
             `:foo` would ambiguously begin a keyword AND open a \
             string.",
        );
        assert_ne!(
            Atom::KEYWORD_MARKER_LEAD,
            Atom::STR_ESCAPE_LEAD,
            "KEYWORD_MARKER_LEAD collides with STR_ESCAPE_LEAD — the \
             reader's Str-escape lead byte would alias the Keyword- \
             prefix lead byte.",
        );
        assert_ne!(
            Atom::KEYWORD_MARKER_LEAD,
            Atom::BOOL_LITERAL_LEAD,
            "KEYWORD_MARKER_LEAD collides with BOOL_LITERAL_LEAD — a \
             bare `:foo` would ambiguously begin a keyword AND \
             classify as a Bool.",
        );
        assert_ne!(
            Atom::KEYWORD_MARKER_LEAD,
            Sexp::LIST_OPEN,
            "KEYWORD_MARKER_LEAD collides with LIST_OPEN — a bare \
             `:foo` would ambiguously begin a keyword AND open a list.",
        );
        assert_ne!(
            Atom::KEYWORD_MARKER_LEAD,
            Sexp::LIST_CLOSE,
            "KEYWORD_MARKER_LEAD collides with LIST_CLOSE — a bare \
             `:foo` would ambiguously begin a keyword AND close a list.",
        );
        assert_ne!(
            Atom::KEYWORD_MARKER_LEAD,
            Sexp::COMMENT_LEAD,
            "KEYWORD_MARKER_LEAD collides with COMMENT_LEAD — a bare \
             `:foo` would ambiguously begin a keyword AND begin a \
             comment.",
        );
        assert_ne!(
            Atom::KEYWORD_MARKER_LEAD,
            Sexp::COMMENT_TERM,
            "KEYWORD_MARKER_LEAD collides with COMMENT_TERM — the \
             reader's line-comment discard loop would terminate on \
             the SAME byte the from_lexeme keyword-prefix arm binds to.",
        );
        for qf in QuoteForm::ALL {
            assert_ne!(
                Atom::KEYWORD_MARKER_LEAD,
                qf.lead_char(),
                "KEYWORD_MARKER_LEAD collides with QuoteForm::{qf:?}'s \
                 lead_char — a bare `:foo` would ambiguously begin a \
                 keyword AND begin a quote-family prefix.",
            );
        }
        assert_ne!(
            Atom::KEYWORD_MARKER_LEAD,
            QuoteForm::SPLICE_DISCRIMINATOR,
            "KEYWORD_MARKER_LEAD collides with SPLICE_DISCRIMINATOR — \
             the reader's `,@` splice-promotion peek byte would alias \
             the Keyword-prefix lead byte.",
        );
    }

    // ── `Atom::keyword_qualified` — the ONE projection composing
    // `Atom::KEYWORD_MARKER` with a bare keyword name across the three
    // canonical-rendering Keyword-arm sites (JSON, iac-forge, Lisp
    // Display). Pins the composition + the round-trip law with
    // `Atom::from_lexeme` + the path-uniformity at every routed site so
    // a regression that re-inlines any single site's `format!("{}{s}",
    // KEYWORD_MARKER)` composition drifts against these pins even when
    // the rendered bytes still agree at that site.

    #[test]
    fn atom_keyword_qualified_composes_keyword_marker_with_bare_name() {
        // BYTE-COMPOSITION CONTRACT: `Atom::keyword_qualified(name)`
        // renders exactly `Atom::KEYWORD_MARKER ++ name` for every
        // bare-name input — the ONE typed composition of the Keyword-
        // prefix constant with a bare-name payload on the [`Atom`]
        // algebra. Sibling-shape pin to
        // `atom_bool_literal_projects_canonical_scheme_spellings`
        // (the Bool-family canonical-rendering axis): where that pin
        // sweeps the CLOSED `bool` domain to its canonical spellings,
        // this pin sweeps a representative set of bare-name inputs
        // (empty, single-char, dashed, dotted, unicode) through the
        // Keyword-family projection to prove the composition holds
        // uniformly over the open-set bare-name domain.
        for name in [
            "",
            "x",
            "class",
            "parent",
            "point-type",
            "kebab-case-name",
            "dotted.path",
            "with_underscore",
            "α",
        ] {
            let expected = format!("{}{name}", Atom::KEYWORD_MARKER);
            assert_eq!(
                Atom::keyword_qualified(name),
                expected,
                "Atom::keyword_qualified({name:?}) drifted from the \
                 substrate-canonical composition \
                 `Atom::KEYWORD_MARKER ++ name` — the three canonical- \
                 rendering Keyword-arm sites (to_json, to_iac_forge_sexpr, \
                 Display) all bind to this ONE projection.",
            );
        }
    }

    #[test]
    fn atom_keyword_qualified_starts_with_keyword_marker() {
        // STRUCTURAL PREFIX CONTRACT: for every bare-name input,
        // `Atom::keyword_qualified(name).starts_with(Atom::KEYWORD_MARKER)`.
        // The projection MUST begin with the canonical
        // [`Atom::KEYWORD_MARKER`] prefix so
        // [`Atom::from_lexeme`]'s `s.strip_prefix(Self::KEYWORD_MARKER)`
        // classifier gate matches every rendered qualified keyword.
        // Sibling-shape pin to
        // `atom_bool_literal_lead_prefixes_every_bool_literal_spelling`
        // (the Bool-family shared-lead-byte axis): where that pin
        // sweeps every `b: bool` to prove BOTH spellings share the
        // lead byte, this pin sweeps every representative bare-name
        // to prove EVERY qualified rendering starts with the shared
        // Keyword-family prefix.
        for name in ["", "x", "class", "parent", "point-type", "α"] {
            let qualified = Atom::keyword_qualified(name);
            assert!(
                qualified.starts_with(Atom::KEYWORD_MARKER),
                "Atom::keyword_qualified({name:?}) = {qualified:?} does \
                 NOT start with Atom::KEYWORD_MARKER `{}` — the \
                 projection has drifted from its structural prefix \
                 contract; Atom::from_lexeme's `strip_prefix` classifier \
                 gate would silently disagree with the rendered \
                 qualified keyword.",
                Atom::KEYWORD_MARKER,
            );
        }
    }

    #[test]
    fn atom_from_lexeme_inverts_keyword_qualified_on_bare_name() {
        // ROUND-TRIP CONTRACT (typed-EXIT rendering ↔ typed-ENTRY
        // classification): [`Atom::from_lexeme`] is the LEFT-inverse
        // of [`Atom::keyword_qualified`] on the Keyword-payload
        // subset — i.e. `Atom::from_lexeme(&Atom::keyword_qualified(n))
        // == Atom::Keyword(n.to_owned())` for every bare `name` that
        // does NOT itself parse as a Bool spelling, integer, or float
        // (the four typed-entry classification arms preceding the
        // KEYWORD_MARKER-prefix arm at `from_lexeme`).
        //
        // A regression that drifts EITHER the composition (this
        // projection) OR the classification (from_lexeme's
        // strip_prefix arm) surfaces at THIS pin rather than as a
        // silent Keyword-round-trip drift at a downstream consumer.
        // Sibling-shape pin to
        // `atom_from_lexeme_round_trips_through_bool_literal_for_every_bool`
        // (the Bool-family round-trip axis) — pins the SAME shape at
        // the Keyword-family round-trip axis of the closed-set outer
        // [`Atom`] algebra.
        for name in [
            "x",
            "class",
            "parent",
            "point-type",
            "kebab-case-name",
            "dotted.path",
            "with_underscore",
            "α",
        ] {
            let qualified = Atom::keyword_qualified(name);
            let classified = Atom::from_lexeme(&qualified);
            assert_eq!(
                classified,
                Atom::Keyword(name.to_owned()),
                "Atom::from_lexeme({qualified:?}) drifted from \
                 Atom::Keyword({name:?}) — the round-trip law between \
                 Atom::keyword_qualified (typed-EXIT canonical \
                 rendering) and Atom::from_lexeme's strip_prefix arm \
                 (typed-ENTRY classification) has broken on the \
                 Keyword-family axis of the closed-set outer [`Atom`] \
                 algebra.",
            );
        }
    }

    #[test]
    fn atom_display_keyword_arm_agrees_with_keyword_qualified_bytes() {
        // DISPLAY BYTE-IDENTITY PIN: [`fmt::Display for Atom`]'s
        // [`Atom::Keyword`] arm keeps its allocation-free
        // `write!(f, "{}{s}", Self::KEYWORD_MARKER)` composition
        // (Display is called at every canonical-rendering surface
        // that composes via `format!("{sexp}")` — avoiding the
        // allocation is load-bearing on tokenizer-adjacent hot paths
        // like `checks.lisp`'s exhaustive `defcheck` rendering) but
        // MUST produce byte-identical output to
        // [`Atom::keyword_qualified`]. Otherwise the three canonical-
        // rendering surfaces (Display, to_json, to_iac_forge_sexpr)
        // would silently disagree on the qualified-keyword bytes even
        // though two of the three route through the typed projection.
        //
        // Load-bearing: this pin IS the "Display's inline write! and
        // the typed projection agree byte-for-byte" invariant that
        // lets Display keep the zero-alloc path while to_json /
        // to_iac_forge_sexpr collapse onto the ONE algebra site.
        for name in [
            "",
            "x",
            "class",
            "parent",
            "point-type",
            "kebab-case-name",
            "α",
        ] {
            let atom = Atom::Keyword(name.to_owned());
            let via_display = atom.to_string();
            let via_projection = Atom::keyword_qualified(name);
            assert_eq!(
                via_display, via_projection,
                "fmt::Display for Atom's Keyword arm drifted from \
                 Atom::keyword_qualified on name {name:?} — the \
                 write! path and the typed projection have disagreed \
                 on the qualified-keyword bytes.",
            );
        }
    }

    #[test]
    fn atom_to_json_keyword_arm_routes_through_keyword_qualified() {
        // PATH-UNIFORMITY GUARD: [`Atom::to_json`]'s [`Atom::Keyword`]
        // arm's rendered String value MUST equal
        // [`Atom::keyword_qualified`] on the same bare name — the
        // FIRST of the two routed sites is bound to the typed
        // projection. A regression that re-inlines the `format!("{}{s}",
        // Self::KEYWORD_MARKER)` composition at this arm without
        // updating the projection (or vice versa) fails HERE.
        // Sibling-shape pin to
        // `atom_to_iac_forge_sexpr_keyword_arm_routes_through_keyword_qualified`
        // on the iac-forge canonical-attestation-form axis: where that
        // pin binds the iac-forge arm's Symbol payload, this pin binds
        // the JSON arm's String payload.
        for name in ["", "x", "class", "parent", "α"] {
            let atom = Atom::Keyword(name.to_owned());
            let via_json = atom.to_json();
            let expected = serde_json::Value::String(Atom::keyword_qualified(name));
            assert_eq!(
                via_json, expected,
                "Atom::to_json's Keyword arm drifted from \
                 Atom::keyword_qualified on name {name:?} — the JSON \
                 canonical-rendering site has diverged from the typed \
                 algebra projection.",
            );
        }
    }

    // ── `Atom::bool_literal` — the ONE projection routing the closed-set
    // `bool` domain through its canonical Scheme spelling across the two
    // Bool-round-trip sites (reader-entry classifier, Lisp canonical
    // Display). Pins the projection's spellings for BOTH bool values AND
    // both sites' composition through it so a regression that re-inlines
    // any single site's byte literal drifts against these pins even when
    // the rendered bytes still agree at that site.

    #[test]
    fn atom_bool_literal_projects_canonical_scheme_spellings() {
        assert_eq!(
            Atom::bool_literal(true),
            "#t",
            "Atom::bool_literal(true) drifted from the substrate-canonical \
             Scheme spelling `#t` — the reader-round-trip contract at \
             Self::from_lexeme + fmt::Display for Atom both bind to this \
             projection.",
        );
        assert_eq!(
            Atom::bool_literal(false),
            "#f",
            "Atom::bool_literal(false) drifted from the substrate-canonical \
             Scheme spelling `#f` — the reader-round-trip contract at \
             Self::from_lexeme + fmt::Display for Atom both bind to this \
             projection.",
        );
    }

    #[test]
    fn atom_bool_literal_partitions_the_closed_bool_domain_injectively() {
        // Sanity pin on the projection's shape: the two spellings partition
        // the closed-set `bool` domain injectively (`true` and `false` do
        // NOT alias to the same byte) — otherwise `from_lexeme` on either
        // spelling would classify to a single Bool variant, silently
        // collapsing the typed distinction at the reader-entry boundary.
        assert_ne!(
            Atom::bool_literal(true),
            Atom::bool_literal(false),
            "Atom::bool_literal collapsed the closed-set `bool` domain — \
             both bools projected to the same Scheme spelling, breaking \
             the reader-entry classifier's injection property.",
        );
    }

    #[test]
    fn atom_display_bool_arm_routes_through_bool_literal_projection() {
        for b in [true, false] {
            let rendered = Atom::boolean(b).to_string();
            let expected = Atom::bool_literal(b);
            assert_eq!(
                rendered, expected,
                "fmt::Display for Atom's Bool arm drifted from the \
                 bool_literal composition at b={b:?}",
            );
        }
    }

    #[test]
    fn atom_from_lexeme_bool_classifier_routes_through_bool_literal_projection() {
        for b in [true, false] {
            let lexeme = Atom::bool_literal(b);
            let classified = Atom::from_lexeme(lexeme);
            assert_eq!(
                classified,
                Atom::boolean(b),
                "Atom::from_lexeme's Bool classifier drifted from the \
                 bool_literal composition at lexeme={lexeme:?}",
            );
        }
    }

    #[test]
    fn atom_bool_literal_closes_reader_display_round_trip_for_both_variants() {
        // The load-bearing round-trip contract:
        //   Atom::from_lexeme(&Atom::boolean(b).to_string())
        //   == Atom::boolean(b)
        // Both sides bind to Atom::bool_literal — the reader-entry
        // classifier gates on `s == Self::bool_literal(true|false)`, the
        // canonical-form Display re-emits it via
        // `f.write_str(Self::bool_literal(*b))`. A future refactor that
        // silently drifts ONE site's byte (e.g. by re-inlining `"#t"` at
        // Display while migrating the classifier gate to a different
        // spelling) breaks THIS round-trip even when both bytes happen to
        // agree on the surface — because the round-trip binds to the
        // composition through the projection at BOTH endpoints.
        for b in [true, false] {
            let a = Atom::boolean(b);
            let round_tripped = Atom::from_lexeme(&a.to_string());
            assert_eq!(
                round_tripped, a,
                "bool round-trip through bool_literal drifted at b={b:?}",
            );
        }
    }

    #[test]
    fn atom_true_literal_projects_canonical_pound_t_bytes() {
        // Pins the exact `"#t"` bytes at the typed constant. A
        // regression that drifts the constant (e.g. Common-Lisp-compat
        // typo `"T"`, JSON-compat typo `"true"`, Racket-compat typo
        // `"#true"`, or an accidental case swap `"#T"`) fails-loudly
        // here. This is the single site the substrate's canonical-
        // Scheme `true` spelling resolves to; every downstream consumer
        // (`Atom::bool_literal`'s `true`-arm, `Atom::from_lexeme`'s
        // reader-entry gate, `fmt::Display for Atom`'s `Bool(true)`
        // arm, `Atom::BOOL_LITERALS[0]`) routes through this constant.
        // Sibling posture to
        // `macro_def_head_defmacro_keyword_projects_canonical_defmacro_bytes`
        // on the head-keyword algebra.
        assert_eq!(
            Atom::TRUE_LITERAL,
            "#t",
            "Atom::TRUE_LITERAL drifted from the substrate-canonical \
             Scheme spelling `#t` — the reader-entry classifier at \
             Atom::from_lexeme + fmt::Display for Atom + \
             Atom::bool_literal's true-arm ALL bind to this constant."
        );
    }

    #[test]
    fn atom_false_literal_projects_canonical_pound_f_bytes() {
        // Pins the exact `"#f"` bytes at the typed constant. Peer of
        // `atom_true_literal_projects_canonical_pound_t_bytes` on the
        // `false` element of the closed `bool` domain.
        assert_eq!(
            Atom::FALSE_LITERAL,
            "#f",
            "Atom::FALSE_LITERAL drifted from the substrate-canonical \
             Scheme spelling `#f` — the reader-entry classifier at \
             Atom::from_lexeme + fmt::Display for Atom + \
             Atom::bool_literal's false-arm ALL bind to this constant."
        );
    }

    #[test]
    fn atom_bool_literal_routes_through_typed_per_variant_constants() {
        // PATH-UNIFORMITY: the inherent `Atom::bool_literal(b)` method
        // MUST return the per-variant `pub const` byte-for-byte for
        // each `b: bool`. A regression that reverts ONE arm to an
        // inline `"#t"` / `"#f"` 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
        // `macro_def_head_keyword_method_routes_through_typed_constants`
        // on the head-keyword algebra.
        assert_eq!(
            Atom::bool_literal(true),
            Atom::TRUE_LITERAL,
            "Atom::bool_literal(true) drifted from Atom::TRUE_LITERAL — \
             the `true`-arm reverted to an inline literal"
        );
        assert_eq!(
            Atom::bool_literal(false),
            Atom::FALSE_LITERAL,
            "Atom::bool_literal(false) drifted from Atom::FALSE_LITERAL \
             — the `false`-arm reverted to an inline literal"
        );
    }

    #[test]
    fn atom_bool_literals_has_expected_cardinality() {
        // Cardinality contract: `Self::BOOL_LITERALS.len() == 2` —
        // pinned at the declaration site by rustc's forced-arity check
        // on `[&'static str; 2]`. 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. The `N == 2` is pinned by
        // the mathematics of the closed `bool` domain; a future tri-
        // valued-logic extension surfaces at THIS pin. Sibling posture
        // to `macro_def_head_keywords_has_expected_cardinality` on the
        // head-keyword algebra AND to
        // `macro_params_lambda_list_keywords_has_expected_cardinality`
        // on the CL lambda-list-keyword family.
        assert_eq!(
            Atom::BOOL_LITERALS.len(),
            2,
            "Atom::BOOL_LITERALS cardinality drifted from 2 — the \
             closed `bool` domain admits exactly two spellings by \
             construction; a tri-valued extension surfaces here"
        );
    }

    #[test]
    fn atom_bool_literals_align_with_bool_literal_by_index() {
        // ALIGNMENT CONTRACT: `Self::BOOL_LITERALS[i] ==
        // Self::bool_literal([true, false][i])` element-wise. The
        // `[true, false]` sweep order is the canonical declaration
        // order every existing sibling test in the crate uses; a
        // regression that reorders ONE array without reordering the
        // other silently misaligns every `zip([true, false],
        // Self::BOOL_LITERALS)` consumer (LSP completion providers,
        // metric-label emitters, coverage reporters). Sibling posture
        // to `macro_def_head_keywords_align_with_all_by_index` on the
        // head-keyword algebra.
        for (i, b) in [true, false].iter().enumerate() {
            assert_eq!(
                Atom::BOOL_LITERALS[i],
                Atom::bool_literal(*b),
                "Atom::BOOL_LITERALS[{i}] `{kw}` drifted from \
                 Atom::bool_literal({b:?}) `{via_variant}` — the \
                 canonical declaration order of the ALL array and the \
                 bool_literal projection must match element-wise",
                kw = Atom::BOOL_LITERALS[i],
                via_variant = Atom::bool_literal(*b),
            );
        }
    }

    #[test]
    fn atom_bool_literals_pairwise_distinct() {
        // PAIRWISE DISJOINTNESS: the two `&'static str` spellings on
        // the bool-spelling algebra MUST differ so the reader-entry
        // classifier's `s == Self::bool_literal(true|false)` cascade
        // cannot route both bools through the same arm — otherwise
        // `from_lexeme` on either spelling would classify to a single
        // Bool variant, silently collapsing the typed distinction at
        // the reader-entry boundary. Family-wide sweep over
        // `BOOL_LITERALS × BOOL_LITERALS` — supersedes any single
        // per-pair assertion and picks up new spellings mechanically
        // (should the closed `bool` domain ever extend). Sibling
        // posture to `macro_def_head_keywords_pairwise_distinct` on the
        // head-keyword algebra AND to
        // `atom_bool_literal_partitions_the_closed_bool_domain_injectively`
        // on the direct-projection axis.
        for (i, a) in Atom::BOOL_LITERALS.iter().enumerate() {
            for (j, b) in Atom::BOOL_LITERALS.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "Atom::BOOL_LITERALS[{i}] `{a}` collides with \
                     Atom::BOOL_LITERALS[{j}] `{b}` — the reader-entry \
                     classifier's cascade would route two bools through \
                     the same arm"
                );
            }
        }
    }

    #[test]
    fn atom_bool_literals_all_route_through_bool_literal_leading_byte() {
        // Structural round-trip pin composed with the algebra's
        // `Atom::BOOL_LITERAL_LEAD` axis peer: every entry of
        // `Self::BOOL_LITERALS` MUST start with `Self::BOOL_LITERAL_LEAD`.
        // The lead-byte-prefixes-spelling law from
        // `atom_bool_literal_lead_prefixes_every_bool_literal_spelling`
        // sweeps [true, false] through `bool_literal`; THIS test
        // sweeps the same invariant over the `BOOL_LITERALS` array
        // directly, catching a regression where a per-role constant
        // drifts from the shared lead byte (e.g. `FALSE_LITERAL` set
        // to `"~f"` while `bool_literal(false)` still returns
        // `FALSE_LITERAL`, which would preserve the projection
        // contract but break the lead-byte contract). Sibling posture
        // to `macro_def_head_keywords_all_round_trip_through_from_str`
        // on the head-keyword algebra.
        for kw in Atom::BOOL_LITERALS {
            assert!(
                kw.starts_with(Atom::BOOL_LITERAL_LEAD),
                "Atom::BOOL_LITERALS entry `{kw}` does NOT start with \
                 Atom::BOOL_LITERAL_LEAD ({lead:?}) — the per-role \
                 constant drifted from the shared lead byte",
                lead = Atom::BOOL_LITERAL_LEAD,
            );
        }
    }

    // ── `Atom::BOOL_LITERAL_LEAD` — the canonical `'#'` char shared
    // across BOTH `Atom::bool_literal` spellings (`"#t"` for `true`,
    // `"#f"` for `false`). Sibling-shape tests to the
    // `atom_bool_literal_*` block above (the two-char spelling axis
    // of the Bool payload) — where those pins bind the two-char
    // Scheme spelling of each `bool` payload, THESE tests bind the
    // ONE shared lead byte of the two spellings onto the closed-set
    // outer [`Atom`] algebra so a hash-prefix reader-family
    // extension (`#\char`, `#(vector)`, `#|block-comment|#`, `#;
    // datum-comment`) lands at ONE constant on the algebra.

    #[test]
    fn atom_bool_literal_lead_projects_canonical_hash_char() {
        // Pins the constant's exact `char` value so a typo (`'#'`
        // vs. `'$'`, `'@'`, or `'!'`) or an accidental redefinition
        // surfaces immediately. Sibling-shape pin to
        // `atom_str_delimiter_projects_canonical_double_quote_char`
        // (Str-delimiter axis) and
        // `atom_str_escape_lead_projects_canonical_backslash_char`
        // (Str-escape-lead axis) — pins the SAME shape on the
        // Bool-family lead-byte axis of the closed-set [`Atom`]
        // algebra.
        assert_eq!(
            Atom::BOOL_LITERAL_LEAD,
            '#',
            "BOOL_LITERAL_LEAD char drifted from the substrate-\
             canonical `#` Bool-family lead byte — the disjointness \
             contract at is_bare_atom_boundary's negative sweep AND \
             the QuoteForm::SPLICE_DISCRIMINATOR non-collision pin \
             both bind to this ONE constant.",
        );
    }

    #[test]
    fn atom_bool_literal_lead_prefixes_every_bool_literal_spelling() {
        // Structural round-trip pin — the (BOOL_LITERAL_LEAD,
        // bool_literal spelling) pairing binds at ONE algebra layer:
        // for every `b: bool`, `Atom::bool_literal(b)` MUST start
        // with `Atom::BOOL_LITERAL_LEAD`. A regression that drifts
        // EITHER the constant OR the two `bool_literal` arms
        // surfaces here rather than at a silent bool-family reader
        // drift where `#t` / `#f` classify as `Atom::Symbol` instead
        // of `Atom::Bool`.
        //
        // Load-bearing across both `b: bool` values because the
        // structural invariant IS "both spellings share the lead
        // byte" — sweeps the closed `bool` domain so a hypothetical
        // regression that renamed ONE spelling only (e.g. moved
        // `"#f"` to `"~f"`) fails at THIS pin even though the
        // constant AND the sibling spelling both agreed.
        //
        // Sibling-shape peer of
        // `atom_bool_literal_closes_reader_display_round_trip_for_both_variants`
        // one axis over: that test binds the (spelling, typed Bool
        // variant) round-trip through the reader/Display; THIS test
        // binds the (lead byte, spelling) prefix invariant at the
        // atomic-algebra layer directly.
        for b in [true, false] {
            let spelling = Atom::bool_literal(b);
            assert!(
                spelling.starts_with(Atom::BOOL_LITERAL_LEAD),
                "Atom::bool_literal({b:?}) = {spelling:?} does NOT \
                 start with BOOL_LITERAL_LEAD ({:?}) — the structural \
                 invariant \"both bool_literal spellings share the \
                 lead byte\" broke at b={b:?}",
                Atom::BOOL_LITERAL_LEAD,
            );
        }
    }

    #[test]
    fn atom_bool_literal_lead_distinct_from_every_other_algebra_marker() {
        // Cross-axis disjointness pin: BOOL_LITERAL_LEAD's byte MUST
        // NOT alias any other closed-set outer-marker byte the
        // reader's tokenizer specialises on — otherwise a bare `#t`
        // / `#f` lexeme would ambiguously route through the
        // colliding arm AND the bool classifier. Sibling-shape pin
        // to `sexp_comment_term_distinct_from_every_non_whitespace_algebra_marker`
        // (COMMENT_TERM axis) — enumerates every closed-set outer-
        // marker char AND asserts non-collision on the Bool-family
        // lead-byte axis.
        //
        // The enumerated set spans THREE type namespaces and every
        // canonical reader byte the substrate exposes:
        //   * `Sexp::LIST_OPEN` / `LIST_CLOSE` / `COMMENT_LEAD` /
        //     `COMMENT_TERM` — outer-structural + reader-discard
        //   * `Atom::STR_DELIMITER` / `STR_ESCAPE_LEAD` — atomic-
        //     payload delimiter + escape lead
        //   * `Atom::KEYWORD_MARKER`'s lead byte — atomic-payload
        //     prefix marker
        //   * every `QuoteForm::lead_char` projection AND
        //     `QuoteForm::SPLICE_DISCRIMINATOR` — homoiconic
        //     prefix + splice-discriminator
        assert_ne!(
            Atom::BOOL_LITERAL_LEAD,
            Sexp::LIST_OPEN,
            "BOOL_LITERAL_LEAD collides with LIST_OPEN — a bare `#t` \
             would ambiguously open a list AND classify as a Bool.",
        );
        assert_ne!(
            Atom::BOOL_LITERAL_LEAD,
            Sexp::LIST_CLOSE,
            "BOOL_LITERAL_LEAD collides with LIST_CLOSE — a bare `#t` \
             would ambiguously close a list AND classify as a Bool.",
        );
        assert_ne!(
            Atom::BOOL_LITERAL_LEAD,
            Sexp::COMMENT_LEAD,
            "BOOL_LITERAL_LEAD collides with COMMENT_LEAD — a bare \
             `#t` would ambiguously open a line comment AND classify \
             as a Bool.",
        );
        assert_ne!(
            Atom::BOOL_LITERAL_LEAD,
            Sexp::COMMENT_TERM,
            "BOOL_LITERAL_LEAD collides with COMMENT_TERM — the \
             reader's line-comment discard-loop terminator would \
             alias the Bool-family lead byte.",
        );
        assert_ne!(
            Atom::BOOL_LITERAL_LEAD,
            Atom::STR_DELIMITER,
            "BOOL_LITERAL_LEAD collides with STR_DELIMITER — a bare \
             `#t` would ambiguously open a string AND classify as a \
             Bool.",
        );
        assert_ne!(
            Atom::BOOL_LITERAL_LEAD,
            Atom::STR_ESCAPE_LEAD,
            "BOOL_LITERAL_LEAD collides with STR_ESCAPE_LEAD — the \
             reader's Str-escape lead byte would alias the Bool-\
             family lead byte.",
        );
        assert_ne!(
            Atom::BOOL_LITERAL_LEAD,
            Atom::KEYWORD_MARKER_LEAD,
            "BOOL_LITERAL_LEAD collides with KEYWORD_MARKER_LEAD — a \
             bare `#t` would ambiguously begin a keyword AND classify \
             as a Bool.",
        );
        for qf in QuoteForm::ALL {
            assert_ne!(
                Atom::BOOL_LITERAL_LEAD,
                qf.lead_char(),
                "BOOL_LITERAL_LEAD collides with QuoteForm::{qf:?}'s \
                 lead_char — a bare `#t` would ambiguously begin a \
                 quote-family prefix AND classify as a Bool.",
            );
        }
        assert_ne!(
            Atom::BOOL_LITERAL_LEAD,
            QuoteForm::SPLICE_DISCRIMINATOR,
            "BOOL_LITERAL_LEAD collides with SPLICE_DISCRIMINATOR — \
             the reader's `,@` splice-promotion peek byte would alias \
             the Bool-family lead byte.",
        );
    }

    // ── `Atom::STR_DELIMITER` — the canonical `"` char routed through
    // the four Str-round-trip sites inside `crate::reader::tokenize`
    // (string-opening arm, escape-handler self-escape mapping, string-
    // closing arm, bare-atom terminator disjunct). Pins the constant
    // value AND the composition against a byte-identical drift at any
    // one of the four sites. Sibling-shape tests to the
    // `atom_keyword_marker_*` block above (Keyword prefix axis) and
    // the `atom_bool_literal_*` block above (Bool spelling axis).

    #[test]
    fn atom_str_delimiter_projects_canonical_double_quote_char() {
        // Pins the constant's exact `char` value so a typo (`'\''`,
        // `'\`'`, `'#'`) or an accidental redefinition surfaces
        // immediately. Sibling-shape pin to
        // `atom_keyword_marker_projects_canonical_colon_byte` (the
        // Keyword prefix axis) and
        // `atom_bool_literal_projects_canonical_scheme_spellings`
        // (the Bool spelling axis) — pins the SAME shape on the
        // Str-delimiter axis of the closed-set [`Atom`] algebra.
        assert_eq!(
            Atom::STR_DELIMITER,
            '"',
            "STR_DELIMITER char drifted from the substrate-canonical `\"` \
             delimiter — the reader-round-trip contract at \
             crate::reader::tokenize (string-opening arm, escape-handler \
             self-escape, string-closing arm, bare-atom terminator \
             disjunct) all bind to this ONE constant.",
        );
    }

    #[test]
    fn atom_str_delimiter_distinct_from_every_other_atom_marker() {
        // Cross-axis disjointness pin: the Str-delimiter byte
        // (`Atom::STR_DELIMITER`) must NOT alias the Keyword-marker
        // prefix byte (`Atom::KEYWORD_MARKER`) or the two Bool-
        // literal spellings (`Atom::bool_literal(true|false)`) —
        // otherwise a bare `:foo` or `#t` lexeme starting with the
        // Str-delimiter would ambiguously route through the reader's
        // `Token::Str` branch AND the `Token::Atom` classifier's
        // Keyword / Bool arms in `Atom::from_lexeme`. Guards the
        // structural disjointness of the atomic-payload marker
        // family on the closed-set [`Atom`] algebra so a future
        // marker-swap that accidentally collides two axes surfaces
        // at this pin rather than as a silent reader misclassification.
        //
        // `KEYWORD_MARKER` is `":"` (single-char) — its LEAD `char`
        // lives at `Atom::KEYWORD_MARKER_LEAD` on the closed-set outer
        // [`Atom`] algebra AND MUST differ from `STR_DELIMITER`'s
        // (`'"'`) so `:foo` never opens a string. The two
        // `bool_literal` spellings (`"#t"`, `"#f"`) begin with `'#'` —
        // a two-char prefix distinct from the single `'"'`
        // STR_DELIMITER — so a bare `#t` never opens a string either.
        // Pin the byte-level disjointness directly here so any future
        // refactor that swaps a marker to collide with STR_DELIMITER
        // fails loudly.
        assert_ne!(
            Atom::STR_DELIMITER,
            Atom::KEYWORD_MARKER_LEAD,
            "STR_DELIMITER and KEYWORD_MARKER_LEAD share a byte — a \
             bare `{}foo` lexeme would ambiguously open a string AND \
             begin a keyword classification.",
            Atom::KEYWORD_MARKER,
        );
        for b in [true, false] {
            assert!(
                !Atom::bool_literal(b).starts_with(Atom::STR_DELIMITER),
                "bool_literal({b:?}) begins with STR_DELIMITER — a bare \
                 `{}` lexeme would ambiguously open a string AND classify \
                 as a Bool.",
                Atom::bool_literal(b),
            );
        }
    }

    #[test]
    fn atom_str_delimiter_closes_reader_display_round_trip_for_escape_free_str_payloads() {
        // Load-bearing round-trip contract for the reader's four
        // Str-round-trip sites — the reader's string-opening AND
        // string-closing arms both bind to `Atom::STR_DELIMITER`, so
        // wrapping an escape-free payload in the constant's byte on
        // both sides recovers the SAME `Atom::string(s)` value the
        // typed constructor produces. A regression that drifts ONE
        // of the two arms (e.g. re-inlines `'"'` at the opener while
        // migrating the closer to a different delimiter) breaks the
        // opener-must-match-closer contract even when the byte-value
        // at the drifted site still agrees at the surface, because
        // this round-trip binds to the constant at BOTH endpoints.
        //
        // Escape-free payload sweep — the reader's escape-handler
        // arm's self-escape (`\"` → `"`) is pinned separately at
        // `reader_str_escape_self_escape_arm_routes_through_atom_str_delimiter`
        // in `crate::reader::tests`; here we sweep the payloads that
        // do NOT hit the escape-handler branch so the opener/closer
        // pairing is isolated as the load-bearing composition.
        for payload in ["hello", "", "foo bar", "kw", "seph.1", "42"] {
            let source = format!("{}{payload}{}", Atom::STR_DELIMITER, Atom::STR_DELIMITER,);
            let forms = crate::reader::read(&source).unwrap_or_else(|e| {
                panic!(
                    "reader rejected `{source}` composed from \
                     Atom::STR_DELIMITER at payload={payload:?}: {e}"
                )
            });
            assert_eq!(
                forms.len(),
                1,
                "STR_DELIMITER-wrapped payload {payload:?} must read as \
                 exactly one form, got {forms:?}",
            );
            assert_eq!(
                forms[0],
                Sexp::Atom(Atom::string(payload)),
                "STR_DELIMITER-wrapped payload {payload:?} drifted from \
                 the Sexp::Atom(Atom::string(_)) typed-constructor shape",
            );
        }
    }

    // ── `Atom::STR_ESCAPE_LEAD` — the canonical `\` char routed
    // through the TWO Str-escape-lead round-trip sites inside
    // `crate::reader::tokenize` (escape-handler outer arm's escape-lead
    // pattern, escape-handler's self-escape arm's pattern + value pair).
    // Pins the constant value AND the composition against a byte-
    // identical drift at either site. Sibling-shape peer of the
    // `atom_str_delimiter_*` block above on the Str-payload delimiter
    // axis — where those pin the OPENER/CLOSER byte's four round-trip
    // sites, these pin the ESCAPE-LEAD byte's two round-trip sites.
    // The two constants together span the reader's `Token::Str`
    // tokenization boundary.

    #[test]
    fn atom_str_escape_lead_projects_canonical_backslash_char() {
        // Pins the constant's exact `char` value so a typo (`'/'`,
        // `'|'`, `'^'`) or an accidental redefinition surfaces
        // immediately. Sibling-shape pin to
        // `atom_str_delimiter_projects_canonical_double_quote_char`
        // — pins the SAME shape on the Str-escape-lead axis of the
        // closed-set [`Atom`] algebra.
        assert_eq!(
            Atom::STR_ESCAPE_LEAD,
            '\\',
            "STR_ESCAPE_LEAD char drifted from the substrate-canonical \
             `\\` escape lead — the reader-round-trip contract at \
             crate::reader::tokenize (escape-handler outer arm, escape-\
             handler self-escape arm's pattern + value pair) all bind \
             to this ONE constant.",
        );
    }

    #[test]
    fn atom_str_escape_lead_distinct_from_every_other_atom_marker() {
        // Cross-axis disjointness pin: the Str-escape-lead byte
        // (`Atom::STR_ESCAPE_LEAD`) must NOT alias the Str-delimiter
        // (`Atom::STR_DELIMITER`), Keyword-marker prefix
        // (`Atom::KEYWORD_MARKER`), or Bool-literal spellings
        // (`Atom::bool_literal(true|false)`) — otherwise the reader's
        // escape-lead outer arm would ambiguously route the alias
        // byte through the escape-handler branch AND the alias's
        // corresponding classifier arm. Guards the structural
        // disjointness of the atomic-payload marker family on the
        // closed-set [`Atom`] algebra so a future marker-swap that
        // accidentally collides two axes surfaces at this pin rather
        // than as a silent reader misclassification.
        //
        // In particular: `STR_ESCAPE_LEAD` (`'\\'`) MUST differ from
        // `STR_DELIMITER` (`'"'`) so that the reader's `Token::Str`
        // accumulation loop's inner branch dispatch (escape-lead
        // outer arm vs string-closing arm vs passthrough) remains
        // structurally disjoint — collapsing the two would make the
        // opener/closer AND the escape-lead the SAME byte, breaking
        // both dispatch axes at once.
        assert_ne!(
            Atom::STR_ESCAPE_LEAD,
            Atom::STR_DELIMITER,
            "STR_ESCAPE_LEAD and STR_DELIMITER share a byte — the \
             reader's Token::Str inner loop's escape-lead outer arm \
             would ambiguously route through the string-closing arm.",
        );
        assert_ne!(
            Atom::STR_ESCAPE_LEAD,
            Atom::KEYWORD_MARKER_LEAD,
            "STR_ESCAPE_LEAD and KEYWORD_MARKER_LEAD share a byte — a \
             bare `{}foo` lexeme would ambiguously match the escape- \
             lead AND begin a keyword classification.",
            Atom::KEYWORD_MARKER,
        );
        for b in [true, false] {
            assert!(
                !Atom::bool_literal(b).starts_with(Atom::STR_ESCAPE_LEAD),
                "bool_literal({b:?}) begins with STR_ESCAPE_LEAD — a bare \
                 `{}` lexeme would ambiguously match the escape-lead AND \
                 classify as a Bool.",
                Atom::bool_literal(b),
            );
        }
    }

    #[test]
    fn atom_str_escape_lead_closes_reader_self_escape_round_trip_for_backslash_payload() {
        // Load-bearing round-trip contract for the reader's two
        // Str-escape-lead round-trip sites — the reader's escape-lead
        // outer arm AND the escape-handler's self-escape arm both bind
        // to `Atom::STR_ESCAPE_LEAD`, so wrapping the constant's byte
        // TWICE (i.e. the two-byte `\\` sequence) between two
        // `STR_DELIMITER` bytes recovers a Str payload holding ONE
        // `\` byte through the reader. A regression that drifts EITHER
        // of the two arms (outer arm's pattern OR self-escape arm's
        // pattern + value) fails HERE — even when the byte-value at
        // the drifted site still agrees at the surface — because the
        // round-trip binds to the constant at BOTH sites.
        //
        // Sibling-shape pin to
        // `atom_str_delimiter_closes_reader_display_round_trip_for_escape_free_str_payloads`
        // (the Str-payload delimiter axis's opener/closer round-trip)
        // — where that pin sweeps escape-FREE payloads through the
        // opener/closer pair, this pin exercises the SINGLE escape-lead
        // self-escape composition end-to-end.
        let source = format!(
            "{}{}{}{}",
            Atom::STR_DELIMITER,
            Atom::STR_ESCAPE_LEAD,
            Atom::STR_ESCAPE_LEAD,
            Atom::STR_DELIMITER,
        );
        let forms = crate::reader::read(&source).unwrap_or_else(|e| {
            panic!(
                "reader rejected `{source}` composed from \
                 STR_DELIMITER + STR_ESCAPE_LEAD self-escape: {e}"
            )
        });
        assert_eq!(
            forms.len(),
            1,
            "STR_ESCAPE_LEAD-self-escape source must read as exactly one \
             form, got {forms:?}",
        );
        assert_eq!(
            forms[0],
            Sexp::Atom(Atom::string(Atom::STR_ESCAPE_LEAD.to_string())),
            "STR_ESCAPE_LEAD self-escape drifted from the \
             Sexp::Atom(Atom::string(str_escape_lead)) typed-constructor \
             shape — the reader's escape-lead outer arm OR the escape-\
             handler's self-escape arm's pattern + value pair drifted \
             from the Atom::STR_ESCAPE_LEAD constant",
        );
    }

    // ── `Atom::decode_str_escape` — the ONE typed Str-escape decode
    // projection on the closed-set [`Atom`] algebra. Pins the six-arm
    // decode table (three named-escape arms `'n' / 't' / 'r'`, two
    // pattern-equals-value self-escape arms on
    // [`Atom::STR_DELIMITER`] + [`Atom::STR_ESCAPE_LEAD`], one
    // passthrough `other`) AND the reader-level composition through
    // [`crate::reader::tokenize`]'s escape-handler branch. Sibling-shape
    // peer of the `atom_str_escape_lead_*` block above on the same
    // Str-payload tokenization boundary: where those pin the
    // ESCAPE-LEAD byte's two round-trip sites, these pin the escape
    // TABLE's decode arms end-to-end.

    #[test]
    fn atom_decode_str_escape_named_escape_arms_project_canonical_c0_control_bytes() {
        // NAMED-ESCAPE CONTRACT: the three canonical whitespace-
        // shorthand arms map each ASCII letter to its corresponding
        // C0 control byte. Pins the ONE typed projection's arms so a
        // regression that swaps ONE arm's decoded byte (e.g. drifts
        // `'n' → '\r'`, breaking the substrate's canonical newline
        // shorthand) surfaces at this pin rather than at some
        // downstream Str-payload round-trip.
        assert_eq!(
            Atom::decode_str_escape(Atom::NEWLINE_ESCAPE_SOURCE),
            Atom::NEWLINE_ESCAPE_DECODED,
            "decode_str_escape(NEWLINE_ESCAPE_SOURCE) drifted from the \
             substrate-canonical newline (`\\n`) shorthand — the reader's \
             escape-handler branch's `'n' → '\\n'` arm binds to THIS \
             projection.",
        );
        assert_eq!(
            Atom::decode_str_escape(Atom::TAB_ESCAPE_SOURCE),
            Atom::TAB_ESCAPE_DECODED,
            "decode_str_escape(TAB_ESCAPE_SOURCE) drifted from the \
             substrate-canonical tab (`\\t`) shorthand.",
        );
        assert_eq!(
            Atom::decode_str_escape(Atom::CARRIAGE_RETURN_ESCAPE_SOURCE),
            Atom::CARRIAGE_RETURN_ESCAPE_DECODED,
            "decode_str_escape(CARRIAGE_RETURN_ESCAPE_SOURCE) drifted from \
             the substrate-canonical carriage-return (`\\r`) shorthand.",
        );
    }

    #[test]
    fn atom_decode_str_escape_self_escape_arms_route_through_atom_algebra_constants() {
        // SELF-ESCAPE CONTRACT: the two pattern-equals-value arms in
        // the escape table bind through the closed-set [`Atom`]
        // algebra constants at BOTH pattern AND value. Pin that
        // decoding the delimiter byte OR the escape-lead byte from
        // its escaped form recovers the SAME algebra constant — a
        // delimiter-swap on the algebra propagates through pattern
        // AND value at ONE site (the `decode_str_escape` match arm)
        // rather than as scattered inline byte literals. Sibling-
        // shape pin to
        // `reader_str_escape_self_escape_arm_routes_through_atom_str_delimiter`
        // AND
        // `reader_str_escape_lead_outer_arm_and_self_escape_arm_route_through_atom_str_escape_lead`
        // — where those anchor the reader's inner-loop dispatch to
        // the constants, this anchors the algebra-level projection's
        // pattern-equals-value arms to the SAME constants so the
        // reader-round-trip through `decode_str_escape` cannot drift
        // if the constants ever change.
        assert_eq!(
            Atom::decode_str_escape(Atom::STR_DELIMITER),
            Atom::STR_DELIMITER,
            "decode_str_escape(STR_DELIMITER) drifted from the self-\
             escape identity on the Str-payload delimiter axis — the \
             `\\\"` sequence must decode to the STR_DELIMITER byte.",
        );
        assert_eq!(
            Atom::decode_str_escape(Atom::STR_ESCAPE_LEAD),
            Atom::STR_ESCAPE_LEAD,
            "decode_str_escape(STR_ESCAPE_LEAD) drifted from the self-\
             escape identity on the Str-payload escape-lead axis — \
             the `\\\\` sequence must decode to the STR_ESCAPE_LEAD \
             byte.",
        );
    }

    #[test]
    fn atom_decode_str_escape_passthrough_arm_returns_source_byte_unchanged_for_non_named_chars() {
        // PASSTHROUGH CONTRACT: every `esc` NOT bound by the five
        // typed arms (three named + two self-escape) decodes to
        // itself. Pins the total-function property of the projection
        // — every `char` maps to exactly one decoded `char`, and the
        // decode is identity outside the closed-set table. A
        // regression that stripped the `other => other` fallthrough
        // (e.g. swapped it for a diagnostic path or a `Result` return
        // shape) surfaces at this pin. Sweep a representative
        // cross-section of ASCII printable + non-ASCII payload bytes
        // that MUST NOT alias any of the five typed arms — the
        // reader's pre-lift six-arm table pushed each of these
        // through unchanged, and the typed projection must preserve
        // that identity end-to-end.
        for esc in ['a', 'z', '0', '9', '!', '/', '<', '≠', 'π', '🌱'] {
            // Cross-arm disjointness precondition — none of the swept
            // chars may alias the five typed arms; otherwise the sweep
            // conflates passthrough with a typed decode and no longer
            // pins the fallthrough identity.
            assert!(
                !Atom::NAMED_ESCAPE_TABLE.iter().any(|&(src, _)| src == esc)
                    && !Atom::SELF_ESCAPE_TABLE.contains(&esc),
                "passthrough sweep char `{esc}` aliases a typed \
                 escape-table arm — the sweep no longer pins the \
                 `other => other` fallthrough",
            );
            assert_eq!(
                Atom::decode_str_escape(esc),
                esc,
                "decode_str_escape({esc:?}) drifted from the passthrough \
                 identity — every non-named-escape byte must decode to \
                 itself so the reader's `\\{esc}` sequence yields the \
                 payload byte `{esc}`.",
            );
        }
    }

    #[test]
    fn atom_named_escape_per_role_constants_pin_canonical_bytes() {
        // PER-ROLE CANONICAL-BYTE PIN: each of the six per-role
        // `pub const`s carries its exact substrate-canonical byte.
        // A regression that swaps a SOURCE letter (e.g. drifts
        // `NEWLINE_ESCAPE_SOURCE` from `'n'` to `'N'`) or a DECODED
        // C0 control (e.g. drifts `TAB_ESCAPE_DECODED` from `'\t'`
        // to `'\0'`) surfaces at this pin before the round-trip
        // sweep below has a chance to conflate the two. Sibling
        // shape to `atom_str_delimiter_projects_canonical_double_quote_char`
        // on the same closed-set [`Atom`] algebra.
        assert_eq!(
            Atom::NEWLINE_ESCAPE_SOURCE,
            'n',
            "NEWLINE_ESCAPE_SOURCE drifted from the substrate-canonical `n` letter.",
        );
        assert_eq!(
            Atom::NEWLINE_ESCAPE_DECODED,
            '\n',
            "NEWLINE_ESCAPE_DECODED drifted from the substrate-canonical `\\n` C0 control byte.",
        );
        assert_eq!(
            Atom::TAB_ESCAPE_SOURCE,
            't',
            "TAB_ESCAPE_SOURCE drifted from the substrate-canonical `t` letter.",
        );
        assert_eq!(
            Atom::TAB_ESCAPE_DECODED,
            '\t',
            "TAB_ESCAPE_DECODED drifted from the substrate-canonical `\\t` C0 control byte.",
        );
        assert_eq!(
            Atom::CARRIAGE_RETURN_ESCAPE_SOURCE,
            'r',
            "CARRIAGE_RETURN_ESCAPE_SOURCE drifted from the substrate-canonical `r` letter.",
        );
        assert_eq!(
            Atom::CARRIAGE_RETURN_ESCAPE_DECODED,
            '\r',
            "CARRIAGE_RETURN_ESCAPE_DECODED drifted from the substrate-canonical `\\r` C0 control byte.",
        );
    }

    #[test]
    fn atom_named_escape_table_composes_from_per_role_constants_in_declaration_order() {
        // COMPOSITION LAW: the ALL array's rows are exactly the
        // per-role (SOURCE, DECODED) pairings in canonical
        // declaration order. Pins the composition at ONE site so a
        // reorder of ONE row without reordering the per-role
        // `pub const`s silently misaligns every consumer that sweeps
        // the array by index. Sibling posture to
        // `quote_form_iac_forge_tags_align_with_all_by_index` on the
        // outer-tokenizer quote-family axis.
        assert_eq!(
            Atom::NAMED_ESCAPE_TABLE,
            [
                (Atom::NEWLINE_ESCAPE_SOURCE, Atom::NEWLINE_ESCAPE_DECODED),
                (Atom::TAB_ESCAPE_SOURCE, Atom::TAB_ESCAPE_DECODED),
                (
                    Atom::CARRIAGE_RETURN_ESCAPE_SOURCE,
                    Atom::CARRIAGE_RETURN_ESCAPE_DECODED,
                ),
            ],
            "NAMED_ESCAPE_TABLE drifted from its per-role (SOURCE, \
             DECODED) `pub const` composition in canonical declaration \
             order (newline / tab / carriage-return).",
        );
    }

    #[test]
    fn atom_named_escape_table_has_expected_cardinality() {
        // ARITY PIN: the forced-arity `[(char, char); 3]` shape
        // survives at runtime. Pins the closed-set size against a
        // refactor that loosens the array's type to
        // `&'static [(char, char)]` or `Vec<(char, char)>` (which
        // would drop the compile-time arity forcing rustc bakes
        // into `[T; N]` declarations). Sibling posture to
        // `quote_form_iac_forge_tags_has_expected_cardinality` on
        // the outer-tokenizer quote-family axis.
        assert_eq!(
            Atom::NAMED_ESCAPE_TABLE.len(),
            3,
            "NAMED_ESCAPE_TABLE cardinality drifted from the \
             substrate-canonical THREE named-escape arms (newline / \
             tab / carriage-return).",
        );
    }

    #[test]
    fn atom_named_escape_table_sources_pairwise_distinct() {
        // SOURCE DISJOINTNESS: every SOURCE char in the array is
        // distinct from every other SOURCE. A regression that
        // aliased two source letters (e.g. drifts
        // `TAB_ESCAPE_SOURCE` to `'n'`, colliding with
        // `NEWLINE_ESCAPE_SOURCE`) would silently route two escape
        // sequences through the first-matching decoded byte in
        // `decode_str_escape`'s match. Pin the closed-set injective
        // shape on the SOURCE axis. Sibling posture to
        // `quote_form_iac_forge_tags_pairwise_distinct` on the outer
        // quote-family axis.
        let sources: Vec<char> = Atom::NAMED_ESCAPE_TABLE
            .iter()
            .map(|&(src, _)| src)
            .collect();
        for i in 0..sources.len() {
            for j in (i + 1)..sources.len() {
                assert_ne!(
                    sources[i], sources[j],
                    "NAMED_ESCAPE_TABLE SOURCE chars at indices {i} and {j} \
                     alias — every named-escape arm must specialize on a \
                     distinct SOURCE letter.",
                );
            }
        }
    }

    #[test]
    fn atom_named_escape_table_decoded_pairwise_distinct() {
        // DECODED DISJOINTNESS: every DECODED byte in the array is
        // distinct from every other DECODED byte. A regression that
        // aliased two decoded bytes (e.g. drifts
        // `TAB_ESCAPE_DECODED` to `'\n'`, colliding with
        // `NEWLINE_ESCAPE_DECODED`) would silently collapse two
        // canonical whitespace shorthands to the same emitted byte
        // — a `\t` in a Str payload would decode to a newline.
        // Sibling posture to the SOURCE-axis disjointness pin above.
        let decoded: Vec<char> = Atom::NAMED_ESCAPE_TABLE
            .iter()
            .map(|&(_, dec)| dec)
            .collect();
        for i in 0..decoded.len() {
            for j in (i + 1)..decoded.len() {
                assert_ne!(
                    decoded[i], decoded[j],
                    "NAMED_ESCAPE_TABLE DECODED bytes at indices {i} and {j} \
                     alias — every named-escape arm must emit a distinct \
                     DECODED byte.",
                );
            }
        }
    }

    #[test]
    fn atom_named_escape_table_pattern_distinct_from_value_per_row() {
        // PATTERN-DISTINCT-FROM-VALUE INVARIANT: every named-escape
        // row's SOURCE differs from its DECODED byte. This is the
        // structural axis that distinguishes the three named-escape
        // rows from the two pattern-EQUALS-value self-escape arms
        // (`STR_DELIMITER → STR_DELIMITER`,
        // `STR_ESCAPE_LEAD → STR_ESCAPE_LEAD`) EXCLUDED from this
        // array by design. A regression that drifted a named row
        // into pattern-equals-value (e.g. `TAB_ESCAPE_DECODED = 't'`)
        // silently promoted it to a passthrough and lost the
        // canonical whitespace shorthand — pinned HERE at the
        // typed-algebra level.
        for (i, &(src, dec)) in Atom::NAMED_ESCAPE_TABLE.iter().enumerate() {
            assert_ne!(
                src, dec,
                "NAMED_ESCAPE_TABLE row {i} pattern-EQUALS-value — the \
                 named-escape rows are structurally pattern-DISTINCT; \
                 the two pattern-equals-value arms live at \
                 STR_DELIMITER / STR_ESCAPE_LEAD one axis over.",
            );
        }
    }

    #[test]
    fn atom_named_escape_table_disjoint_from_self_escape_algebra_constants() {
        // CROSS-AXIS DISJOINTNESS: no SOURCE or DECODED byte in the
        // named-escape table aliases either of the two self-escape
        // algebra constants (`Self::STR_DELIMITER`,
        // `Self::STR_ESCAPE_LEAD`). A regression that drifted ONE
        // named-escape SOURCE to `'\\'` (colliding with
        // `STR_ESCAPE_LEAD`) or ONE DECODED to `'"'` (colliding
        // with `STR_DELIMITER`) would silently reshuffle the
        // decode-arm dispatch order in `decode_str_escape` (the
        // named arm would fire before the self-escape arm, or vice
        // versa). Pins the two escape-family axes as structurally
        // disjoint sub-vocabularies of the Str-payload tokenization
        // boundary.
        for (i, &(src, dec)) in Atom::NAMED_ESCAPE_TABLE.iter().enumerate() {
            assert_ne!(
                src,
                Atom::STR_DELIMITER,
                "NAMED_ESCAPE_TABLE row {i} SOURCE aliases STR_DELIMITER",
            );
            assert_ne!(
                src,
                Atom::STR_ESCAPE_LEAD,
                "NAMED_ESCAPE_TABLE row {i} SOURCE aliases STR_ESCAPE_LEAD",
            );
            assert_ne!(
                dec,
                Atom::STR_DELIMITER,
                "NAMED_ESCAPE_TABLE row {i} DECODED aliases STR_DELIMITER",
            );
            assert_ne!(
                dec,
                Atom::STR_ESCAPE_LEAD,
                "NAMED_ESCAPE_TABLE row {i} DECODED aliases STR_ESCAPE_LEAD",
            );
        }
    }

    #[test]
    fn atom_decode_str_escape_routes_through_named_escape_table_for_every_row() {
        // PATH-UNIFORMITY PIN: `decode_str_escape` returns the
        // DECODED byte of every `NAMED_ESCAPE_TABLE` row when called
        // with that row's SOURCE. Path-uniformity contract between
        // the projection method and the closed-set algebra — a
        // regression that reverted `decode_str_escape`'s named arms
        // to inline `'n' => '\n'` literals AND drifted the SOURCE
        // per-role `pub const` (or vice versa) fails HERE at the
        // first mismatched row rather than at a distant Str-payload
        // round-trip. Sibling posture to
        // `quote_form_iac_forge_tag_routes_through_typed_per_role_constants`
        // on the outer-tokenizer quote-family axis.
        for (i, &(src, dec)) in Atom::NAMED_ESCAPE_TABLE.iter().enumerate() {
            assert_eq!(
                Atom::decode_str_escape(src),
                dec,
                "decode_str_escape drifted from NAMED_ESCAPE_TABLE row {i} \
                 — the projection's named-escape arm must route through \
                 the per-role (SOURCE, DECODED) `pub const` pairing.",
            );
        }
    }

    #[test]
    fn atom_self_escape_table_composes_from_algebra_constants_in_declaration_order() {
        // COMPOSITION LAW: the ALL array's rows are the two closed-set
        // [`Atom`] algebra constants in canonical declaration order
        // ([`Atom::STR_DELIMITER`], [`Atom::STR_ESCAPE_LEAD`]) matching
        // `decode_str_escape`'s match-arm order. Pins the composition
        // at ONE site so a reorder of ONE row without reordering the
        // constants silently misaligns every consumer that sweeps the
        // array by index. Sibling posture to
        // `atom_named_escape_table_composes_from_per_role_constants_in_declaration_order`
        // one axis over.
        assert_eq!(
            Atom::SELF_ESCAPE_TABLE,
            [Atom::STR_DELIMITER, Atom::STR_ESCAPE_LEAD],
            "SELF_ESCAPE_TABLE drifted from its algebra-constant \
             composition in canonical declaration order \
             (STR_DELIMITER / STR_ESCAPE_LEAD).",
        );
    }

    #[test]
    fn atom_self_escape_table_has_expected_cardinality() {
        // ARITY PIN: the forced-arity `[char; 2]` shape survives at
        // runtime. Pins the closed-set size against a refactor that
        // loosens the array's type to `&'static [char]` or
        // `Vec<char>` (which would drop the compile-time arity
        // forcing rustc bakes into `[T; N]` declarations). Sibling
        // posture to `atom_named_escape_table_has_expected_cardinality`
        // on the peer pattern-DISTINCT-from-value sub-vocabulary.
        assert_eq!(
            Atom::SELF_ESCAPE_TABLE.len(),
            2,
            "SELF_ESCAPE_TABLE cardinality drifted from the substrate-\
             canonical TWO self-escape arms (STR_DELIMITER / \
             STR_ESCAPE_LEAD).",
        );
    }

    #[test]
    fn atom_self_escape_table_pairwise_distinct() {
        // DISJOINTNESS: every byte in the array is distinct from every
        // other byte. A regression that aliased the two self-escape
        // bytes (e.g. adopting `'"'` as ALSO the escape lead in a
        // hypothetical smart-quote reader mode) would silently collapse
        // the two pattern-EQUALS-value arms of `decode_str_escape` to
        // one and lose the ability to escape one delimiter without
        // shadowing the other. Sibling posture to
        // `atom_named_escape_table_sources_pairwise_distinct` on the
        // peer sub-vocabulary.
        for i in 0..Atom::SELF_ESCAPE_TABLE.len() {
            for j in (i + 1)..Atom::SELF_ESCAPE_TABLE.len() {
                assert_ne!(
                    Atom::SELF_ESCAPE_TABLE[i],
                    Atom::SELF_ESCAPE_TABLE[j],
                    "SELF_ESCAPE_TABLE bytes at indices {i} and {j} \
                     alias — every self-escape arm must specialize on \
                     a distinct byte.",
                );
            }
        }
    }

    #[test]
    fn atom_self_escape_table_disjoint_from_named_escape_table() {
        // CROSS-AXIS DISJOINTNESS: no byte in the self-escape table
        // aliases any SOURCE or DECODED byte in the named-escape
        // table. A regression that drifted a self-escape byte into
        // the named vocabulary (e.g. adopted `'n'` as an additional
        // self-escaping delimiter) OR a named byte into the self
        // vocabulary would reshuffle the decode-arm dispatch order in
        // `decode_str_escape` — the two sub-vocabularies must remain
        // structurally disjoint sub-tables of the FIVE non-passthrough
        // arms. Sibling posture (inverse direction) to
        // `atom_named_escape_table_disjoint_from_self_escape_algebra_constants`
        // — where that pin sweeps from the named side outward, this
        // sweeps from the self side outward; both pin the same
        // cross-axis disjointness invariant.
        for (i, &self_byte) in Atom::SELF_ESCAPE_TABLE.iter().enumerate() {
            for (j, &(src, dec)) in Atom::NAMED_ESCAPE_TABLE.iter().enumerate() {
                assert_ne!(
                    self_byte, src,
                    "SELF_ESCAPE_TABLE row {i} aliases NAMED_ESCAPE_TABLE \
                     row {j} SOURCE — the pattern-EQUALS-value and \
                     pattern-DISTINCT-from-value sub-vocabularies must \
                     remain disjoint.",
                );
                assert_ne!(
                    self_byte, dec,
                    "SELF_ESCAPE_TABLE row {i} aliases NAMED_ESCAPE_TABLE \
                     row {j} DECODED — the pattern-EQUALS-value and \
                     pattern-DISTINCT-from-value sub-vocabularies must \
                     remain disjoint.",
                );
            }
        }
    }

    #[test]
    fn atom_decode_str_escape_routes_through_self_escape_table_for_every_row() {
        // PATH-UNIFORMITY PIN: `decode_str_escape` returns the SAME
        // byte for every `SELF_ESCAPE_TABLE` row — the pattern-EQUALS-
        // value invariant is exercised on every row. A regression
        // that reverted `decode_str_escape`'s two self-escape arms to
        // inline `'"' => '"'` / `'\\' => '\\'` literals AND drifted
        // one of the two constants (or vice versa) fails HERE at the
        // first mismatched row rather than at a downstream Str-payload
        // round-trip. Sibling posture to
        // `atom_decode_str_escape_routes_through_named_escape_table_for_every_row`
        // — where that pin exercises the pattern-DISTINCT-from-value
        // path-uniformity contract on the peer sub-vocabulary, this
        // pins the pattern-EQUALS-value axis on the self-escape
        // sub-vocabulary.
        for (i, &esc) in Atom::SELF_ESCAPE_TABLE.iter().enumerate() {
            assert_eq!(
                Atom::decode_str_escape(esc),
                esc,
                "decode_str_escape drifted from SELF_ESCAPE_TABLE row \
                 {i} — the projection's self-escape arm must map \
                 pattern to the SAME byte (definitional identity).",
            );
        }
    }

    #[test]
    fn atom_named_and_self_escape_tables_span_the_five_non_passthrough_arms() {
        // TOTAL-DECODE PIN: the two sub-vocabulary ALL arrays
        // together account for exactly the FIVE non-passthrough arms
        // of [`Atom::decode_str_escape`]. Pins the closed-set
        // decomposition against a refactor that adds a sixth typed
        // arm to `decode_str_escape` without extending one of the
        // ALL arrays (which would leak a stale byte through
        // `other => other` at the sweep sites). The three named arms
        // + two self arms = five typed arms; the sixth branch is the
        // `other => other` passthrough at the algebra's projection.
        assert_eq!(
            Atom::NAMED_ESCAPE_TABLE.len() + Atom::SELF_ESCAPE_TABLE.len(),
            5,
            "NAMED_ESCAPE_TABLE + SELF_ESCAPE_TABLE cardinality drifted \
             from the substrate-canonical FIVE non-passthrough arms of \
             Atom::decode_str_escape.",
        );
    }

    // ── `Atom::ESCAPE_SOURCES` — the closed-set forced-arity ALL array
    // over every escape-SOURCE byte `Atom::decode_str_escape` has a
    // non-passthrough arm for. Cross-sub-vocabulary SPAN peer of
    // `NAMED_ESCAPE_TABLE` (three pattern-DISTINCT-from-value rows'
    // SOURCE column) + `SELF_ESCAPE_TABLE` (two pattern-EQUALS-value
    // rows) at ONE typed `[char; 5]` on the SAME closed-set [`Atom`]
    // algebra. The pins below anchor (a) the SPAN composition against
    // the two peer sub-vocabulary arrays' SOURCE columns in canonical
    // declaration order, (b) the forced-arity cardinality against a
    // refactor that loosens the array to `&[char]`, (c) pairwise
    // disjointness inherited from the two peer sub-vocabularies' own
    // pairwise disjointness + cross-sub-vocabulary disjointness, (d)
    // the "every row hits a non-passthrough arm" closure identity
    // against a refactor that added a stale ESCAPE_SOURCES row without
    // extending `decode_str_escape`, and (e) the load-bearing partition
    // NAMED-source-column prefix / SELF-source-column suffix that the
    // declaration order encodes for consumers that walk the array by
    // index. Sibling-shape to the composition-pin block above for
    // `SELF_ESCAPE_TABLE` — those pins bind the peer sub-vocabulary at
    // the same closed-set algebra; this block binds the SPAN of the
    // two sub-vocabularies at ONE array up.

    #[test]
    fn atom_escape_sources_composes_from_named_and_self_escape_sub_vocabularies_in_declaration_order(
    ) {
        // COMPOSITION LAW: the ALL array's rows are (NAMED_ESCAPE_TABLE
        // SOURCE column, then SELF_ESCAPE_TABLE rows) in canonical
        // declaration order matching `decode_str_escape`'s match-arm
        // order. Pins the SPAN composition at ONE site so a reorder
        // that broke the (named prefix, self suffix) partition (e.g.
        // interleaving the two sub-vocabularies' rows, sorting
        // alphabetically) silently misaligns every consumer that
        // sweeps the array by index. Sibling-shape pin to
        // `atom_self_escape_table_composes_from_algebra_constants_in_declaration_order`
        // one axis over on the peer sub-vocabulary at
        // `Atom::SELF_ESCAPE_TABLE`, and to
        // `atom_named_escape_table_composes_from_per_role_constants_in_declaration_order`
        // on the SOURCE column of the other peer sub-vocabulary at
        // `Atom::NAMED_ESCAPE_TABLE`.
        assert_eq!(
            Atom::ESCAPE_SOURCES,
            [
                Atom::NAMED_ESCAPE_TABLE[0].0,
                Atom::NAMED_ESCAPE_TABLE[1].0,
                Atom::NAMED_ESCAPE_TABLE[2].0,
                Atom::SELF_ESCAPE_TABLE[0],
                Atom::SELF_ESCAPE_TABLE[1],
            ],
            "ESCAPE_SOURCES composition drifted from the canonical \
             (NAMED SOURCE column, then SELF rows) SPAN in declaration \
             order — the SPAN lift must route through the two peer \
             sub-vocabulary arrays' rows in the exact order \
             decode_str_escape's match arms fire on them.",
        );
    }

    #[test]
    fn atom_escape_sources_has_expected_cardinality() {
        // ARITY PIN: the forced-arity `[char; 5]` shape survives at
        // runtime AND matches the two peer sub-vocabularies' summed
        // cardinality. Pins the closed-set size against a refactor
        // that loosens the array's type to `&'static [char]` or
        // `Vec<char>` (which would drop the compile-time arity
        // forcing rustc bakes into `[T; N]` declarations) AND against
        // a refactor that drifted this array's arity without extending
        // one of the two peer sub-vocabularies (which would silently
        // desynchronize the SPAN identity from its two source arrays).
        // Sibling posture to
        // `atom_named_and_self_escape_tables_span_the_five_non_passthrough_arms`
        // — where that pin binds the summed cardinality at ONE
        // assert_eq!, this pin binds the SPAN's OWN cardinality at
        // the ALL array level so a future refactor that added a
        // NAMED_ESCAPE_TABLE row without extending ESCAPE_SOURCES
        // fails HERE at the paired-length equality rather than at a
        // distant sweep site.
        assert_eq!(
            Atom::ESCAPE_SOURCES.len(),
            5,
            "ESCAPE_SOURCES cardinality drifted from the substrate-\
             canonical FIVE non-passthrough arms of \
             Atom::decode_str_escape.",
        );
        assert_eq!(
            Atom::ESCAPE_SOURCES.len(),
            Atom::NAMED_ESCAPE_TABLE.len() + Atom::SELF_ESCAPE_TABLE.len(),
            "ESCAPE_SOURCES cardinality drifted from the SUM of the two \
             peer sub-vocabulary arrays' cardinalities — the SPAN \
             identity is broken.",
        );
    }

    #[test]
    fn atom_escape_sources_pairwise_distinct() {
        // PAIRWISE DISJOINTNESS: every row is distinct from every
        // other row. The closed-set SPAN inherits pairwise
        // disjointness from the two peer sub-vocabularies (each
        // pinned pairwise distinct at their own sibling tests) PLUS
        // the cross-sub-vocabulary disjointness pinned by
        // `atom_self_escape_table_disjoint_from_named_escape_table` —
        // this test closes the disjointness contract at the SPAN
        // level so a future refactor that added a sixth arm whose
        // SOURCE aliased an existing row surfaces HERE rather than
        // at a distant reader round-trip. Sibling posture to
        // `atom_self_escape_table_pairwise_distinct` +
        // `atom_named_escape_table_sources_pairwise_distinct` on the
        // two peer sub-vocabularies.
        for i in 0..Atom::ESCAPE_SOURCES.len() {
            for j in (i + 1)..Atom::ESCAPE_SOURCES.len() {
                assert_ne!(
                    Atom::ESCAPE_SOURCES[i],
                    Atom::ESCAPE_SOURCES[j],
                    "ESCAPE_SOURCES bytes at indices {i} and {j} alias \
                     — every non-passthrough arm must specialize on a \
                     distinct SOURCE byte.",
                );
            }
        }
    }

    #[test]
    fn atom_escape_sources_partitions_into_named_source_prefix_and_self_source_suffix() {
        // PARTITION PIN: the SPAN's canonical declaration order
        // encodes a (named prefix, self suffix) partition —
        // `ESCAPE_SOURCES[0..3]` IS `NAMED_ESCAPE_TABLE`'s SOURCE
        // column, `ESCAPE_SOURCES[3..5]` IS `SELF_ESCAPE_TABLE`. Pin
        // the partition at the index level so a reorder that broke
        // the sub-vocabulary boundary (e.g. moved `STR_DELIMITER` to
        // index 2 to sort alphabetically, or interleaved a self row
        // between two named rows) fails HERE rather than as silent
        // drift where consumers that walk the array by index would
        // route the wrong sub-vocabulary's row through the wrong
        // downstream handler.
        for (i, &(src, _)) in Atom::NAMED_ESCAPE_TABLE.iter().enumerate() {
            assert_eq!(
                Atom::ESCAPE_SOURCES[i],
                src,
                "ESCAPE_SOURCES[{i}] ({}) drifted from \
                 NAMED_ESCAPE_TABLE[{i}].0 ({src}) — the named-prefix \
                 partition is broken.",
                Atom::ESCAPE_SOURCES[i],
            );
        }
        for (i, &self_byte) in Atom::SELF_ESCAPE_TABLE.iter().enumerate() {
            let span_index = Atom::NAMED_ESCAPE_TABLE.len() + i;
            assert_eq!(
                Atom::ESCAPE_SOURCES[span_index],
                self_byte,
                "ESCAPE_SOURCES[{span_index}] ({}) drifted from \
                 SELF_ESCAPE_TABLE[{i}] ({self_byte}) — the self-suffix \
                 partition is broken.",
                Atom::ESCAPE_SOURCES[span_index],
            );
        }
    }

    #[test]
    fn atom_escape_sources_every_row_projects_through_a_non_passthrough_arm_of_decode_str_escape() {
        // NON-PASSTHROUGH-CLOSURE CONTRACT: every row of
        // `ESCAPE_SOURCES` MUST project through a NON-passthrough arm
        // of `decode_str_escape` — the SPAN is definitionally the set
        // of SOURCE bytes for which `decode_str_escape` has a typed
        // arm. Pin the closure structurally so a refactor that added
        // an `ESCAPE_SOURCES` row without extending
        // `decode_str_escape`'s match (or vice versa) surfaces HERE at
        // the first drifted row rather than at a distant sweep-site
        // regression. The row projects through a non-passthrough arm
        // iff EITHER (a) it's a `NAMED_ESCAPE_TABLE` SOURCE and
        // `decode_str_escape` returns the paired DECODED byte
        // (`decode(src) != src`), OR (b) it's a `SELF_ESCAPE_TABLE`
        // row and `decode_str_escape` returns the SAME byte
        // (`decode(esc) == esc` by definitional identity — the arm
        // exists AND fires, but the projection is pattern-EQUALS-
        // value). Both arm-kinds are non-passthrough because they
        // have a TYPED arm in the match; the `other => other`
        // passthrough only fires for chars NOT in the SPAN. Pin the
        // dispatch identity by checking each row lives in exactly ONE
        // of the two peer sub-vocabularies.
        for (i, &esc) in Atom::ESCAPE_SOURCES.iter().enumerate() {
            let in_named = Atom::NAMED_ESCAPE_TABLE.iter().any(|&(src, _)| src == esc);
            let in_self = Atom::SELF_ESCAPE_TABLE.contains(&esc);
            assert!(
                in_named ^ in_self,
                "ESCAPE_SOURCES[{i}] ({esc:?}) must belong to EXACTLY \
                 ONE peer sub-vocabulary (in_named={in_named}, \
                 in_self={in_self}) — the SPAN identity requires each \
                 row to fire a typed non-passthrough arm on either \
                 the pattern-DISTINCT-from-value axis (NAMED) OR the \
                 pattern-EQUALS-value axis (SELF), never both, never \
                 neither.",
            );
            // Consistency check: the arm's projection must agree with
            // the row's sub-vocabulary identity. NAMED rows project to
            // the paired DECODED byte (which the pairwise-distinct pin
            // guarantees differs from SOURCE); SELF rows project to
            // the row byte itself.
            let decoded = Atom::decode_str_escape(esc);
            if in_named {
                assert_ne!(
                    decoded, esc,
                    "ESCAPE_SOURCES[{i}] ({esc:?}) is a NAMED SOURCE — \
                     decode_str_escape MUST project to the paired \
                     DECODED byte (distinct from SOURCE) but returned \
                     {decoded:?}.",
                );
            } else {
                assert_eq!(
                    decoded, esc,
                    "ESCAPE_SOURCES[{i}] ({esc:?}) is a SELF row — \
                     decode_str_escape MUST project to the same byte \
                     (pattern-EQUALS-value by definitional identity) \
                     but returned {decoded:?}.",
                );
            }
        }
    }

    #[test]
    fn atom_decode_str_escape_composes_end_to_end_through_reader_for_every_named_arm() {
        // END-TO-END COMPOSITION CONTRACT: pin that every typed
        // escape-table arm — the three named-escape arms + the two
        // pattern-equals-value self-escape arms + a representative
        // passthrough — decodes through the reader's full
        // escape-handler pipeline via ONE
        // `Atom::decode_str_escape(esc)` call. Wrap each `esc` in a
        // STR_DELIMITER-wrapped, STR_ESCAPE_LEAD-led source, run it
        // through [`crate::reader::read`], and assert the resulting
        // Str payload equals `decode_str_escape(esc).to_string()`.
        // A regression that re-inlined the reader's table (e.g.
        // reverted the escape-handler branch to per-arm literals AND
        // added a sixth named-escape arm to
        // [`Atom::decode_str_escape`] without updating the reader)
        // fails HERE at the first arm whose decode diverges.
        //
        // Sibling-shape pin to
        // `atom_str_escape_lead_closes_reader_self_escape_round_trip_for_backslash_payload`
        // — where that pin exercises the SINGLE self-escape arm on
        // the escape-lead axis end-to-end, this sweep exercises the
        // FULL closed-set table on the same axis.
        // Pre-lift the (NAMED_ESCAPE_TABLE.iter().map(|&(src, _)| src)
        // .chain(SELF_ESCAPE_TABLE.iter().copied())) runtime iterator
        // chain reassembled the FIVE non-passthrough source bytes at
        // this callsite; post-lift the SPAN binds at ONE forced-arity
        // `Atom::ESCAPE_SOURCES: [char; 5]` on the closed-set [`Atom`]
        // algebra so the sweep iterates the typed ALL array directly.
        // The trailing `'x'` is a representative PASSTHROUGH byte
        // (deliberately NOT in `ESCAPE_SOURCES`) — the sweep exercises
        // BOTH the non-passthrough closed set AND the passthrough
        // default-arm through the same reader pipeline in ONE loop.
        let escs: Vec<char> = Atom::ESCAPE_SOURCES
            .iter()
            .copied()
            .chain(std::iter::once('x'))
            .collect();
        for esc in escs {
            let source = format!(
                "{}{}{}{}",
                Atom::STR_DELIMITER,
                Atom::STR_ESCAPE_LEAD,
                esc,
                Atom::STR_DELIMITER,
            );
            let forms = crate::reader::read(&source).unwrap_or_else(|e| {
                panic!(
                    "reader rejected `{source}` composed from \
                     STR_DELIMITER + STR_ESCAPE_LEAD + `{esc}`: {e}"
                )
            });
            assert_eq!(
                forms.len(),
                1,
                "escape sweep for `{esc}` must read as exactly one form, \
                 got {forms:?}",
            );
            let decoded = Atom::decode_str_escape(esc);
            assert_eq!(
                forms[0],
                Sexp::Atom(Atom::string(decoded.to_string())),
                "escape sweep for `{esc}` drifted from \
                 Sexp::Atom(Atom::string(decode_str_escape({esc:?}) = \
                 {decoded:?}).to_string()) — the reader's escape-handler \
                 branch OR Atom::decode_str_escape drifted from the ONE \
                 shared closed-set escape-table projection",
            );
        }
    }

    // ── `Atom::ESCAPE_DECODED` — the closed-set forced-arity ALL array
    // over every DECODED byte `Atom::decode_str_escape` can emit from a
    // non-passthrough arm. Column-dual peer of `Atom::ESCAPE_SOURCES` at
    // the SAME `[char; 5]` shape on the SAME closed-set [`Atom`] algebra:
    // together the two arrays close the (SOURCE, DECODED) cross-product
    // of `decode_str_escape`'s non-passthrough arm-set at two byte-
    // identical `[char; 5]` shapes. Cross-sub-vocabulary SPAN peer of
    // `NAMED_ESCAPE_TABLE` (three pattern-DISTINCT-from-value rows'
    // DECODED column) + `SELF_ESCAPE_TABLE` (two pattern-EQUALS-value
    // rows whose DECODED column is definitionally the row byte itself)
    // at ONE typed `[char; 5]` on the SAME closed-set [`Atom`] algebra.
    // The pins below anchor (a) the SPAN composition against the two
    // peer sub-vocabulary arrays' DECODED columns in canonical
    // declaration order, (b) the forced-arity cardinality against a
    // refactor that loosens the array to `&[char]`, (c) pairwise
    // disjointness on the DECODED column, (d) the load-bearing
    // partition NAMED-decoded-column prefix / SELF-decoded-column suffix
    // that the declaration order encodes for consumers that walk the
    // array by index, and (e) the column-dual POINTWISE projection
    // identity that pins `ESCAPE_DECODED[i] ==
    // decode_str_escape(ESCAPE_SOURCES[i])` for every index — the
    // NEW load-bearing invariant this SPAN adds on top of `ESCAPE_SOURCES`.

    #[test]
    fn atom_escape_decoded_composes_from_named_and_self_escape_sub_vocabularies_in_declaration_order(
    ) {
        // COMPOSITION LAW: the ALL array's rows are (NAMED_ESCAPE_TABLE
        // DECODED column, then SELF_ESCAPE_TABLE rows) in canonical
        // declaration order matching `decode_str_escape`'s match-arm
        // order. Pins the SPAN composition at ONE site so a reorder
        // that broke the (named prefix, self suffix) partition (e.g.
        // interleaving the two sub-vocabularies' rows, sorting by C0
        // byte value) silently misaligns every consumer that sweeps the
        // array by index. Sibling-shape pin to
        // `atom_escape_sources_composes_from_named_and_self_escape_sub_vocabularies_in_declaration_order`
        // one column over on the peer SOURCE-column SPAN at
        // `Atom::ESCAPE_SOURCES`.
        assert_eq!(
            Atom::ESCAPE_DECODED,
            [
                Atom::NAMED_ESCAPE_TABLE[0].1,
                Atom::NAMED_ESCAPE_TABLE[1].1,
                Atom::NAMED_ESCAPE_TABLE[2].1,
                Atom::SELF_ESCAPE_TABLE[0],
                Atom::SELF_ESCAPE_TABLE[1],
            ],
            "ESCAPE_DECODED composition drifted from the canonical \
             (NAMED DECODED column, then SELF rows) SPAN in declaration \
             order — the SPAN lift must route through the two peer \
             sub-vocabulary arrays' rows in the exact order \
             decode_str_escape's match arms fire on them.",
        );
    }

    #[test]
    fn atom_escape_decoded_has_expected_cardinality() {
        // ARITY PIN: the forced-arity `[char; 5]` shape survives at
        // runtime AND matches the two peer sub-vocabularies' summed
        // cardinality AND matches the column-dual peer
        // `ESCAPE_SOURCES`'s arity. Pins the closed-set size against a
        // refactor that loosens the array's type to `&'static [char]`
        // or `Vec<char>` (which would drop the compile-time arity
        // forcing rustc bakes into `[T; N]` declarations) AND against a
        // refactor that drifted this array's arity without extending
        // one of the two peer sub-vocabularies (which would silently
        // desynchronize the SPAN identity from its two source arrays)
        // AND against a refactor that broke the column-dual shape
        // symmetry with `ESCAPE_SOURCES`. Sibling posture to
        // `atom_escape_sources_has_expected_cardinality` on the peer
        // SOURCE-column SPAN.
        assert_eq!(
            Atom::ESCAPE_DECODED.len(),
            5,
            "ESCAPE_DECODED cardinality drifted from the substrate-\
             canonical FIVE non-passthrough arms of \
             Atom::decode_str_escape.",
        );
        assert_eq!(
            Atom::ESCAPE_DECODED.len(),
            Atom::NAMED_ESCAPE_TABLE.len() + Atom::SELF_ESCAPE_TABLE.len(),
            "ESCAPE_DECODED cardinality drifted from the SUM of the two \
             peer sub-vocabulary arrays' cardinalities — the SPAN \
             identity is broken.",
        );
        assert_eq!(
            Atom::ESCAPE_DECODED.len(),
            Atom::ESCAPE_SOURCES.len(),
            "ESCAPE_DECODED cardinality drifted from the column-dual peer \
             ESCAPE_SOURCES's cardinality — the column-dual shape \
             symmetry `[char; 5]` × `[char; 5]` on decode_str_escape's \
             non-passthrough arm-set is broken.",
        );
    }

    #[test]
    fn atom_escape_decoded_pairwise_distinct() {
        // PAIRWISE DISJOINTNESS: every row is distinct from every
        // other row. On the DECODED column this is TIGHTER than on
        // the SOURCE column: the NAMED sub-vocabulary's DECODED rows
        // are C0 control bytes (`'\n'`, `'\t'`, `'\r'` — bytes 0x0A,
        // 0x09, 0x0D) and the SELF sub-vocabulary's rows are printable
        // ASCII bytes (`'"'`, `'\\'` — bytes 0x22, 0x5C), so no
        // NAMED-DECODED byte can alias a SELF byte by byte-class
        // disjointness. This test closes the disjointness contract at
        // the SPAN level so a future refactor that added a sixth arm
        // whose DECODED aliased an existing row (e.g. drifted
        // TAB_ESCAPE_DECODED from `'\t'` to `'\n'`, collapsing two
        // arms onto the same DECODED byte) surfaces HERE rather than
        // at a distant reader round-trip. Sibling posture to
        // `atom_escape_sources_pairwise_distinct` on the peer
        // SOURCE-column SPAN.
        for i in 0..Atom::ESCAPE_DECODED.len() {
            for j in (i + 1)..Atom::ESCAPE_DECODED.len() {
                assert_ne!(
                    Atom::ESCAPE_DECODED[i],
                    Atom::ESCAPE_DECODED[j],
                    "ESCAPE_DECODED bytes at indices {i} and {j} alias \
                     — every non-passthrough arm must emit a distinct \
                     DECODED byte.",
                );
            }
        }
    }

    #[test]
    fn atom_escape_decoded_partitions_into_named_decoded_prefix_and_self_decoded_suffix() {
        // PARTITION PIN: the SPAN's canonical declaration order
        // encodes a (named prefix, self suffix) partition —
        // `ESCAPE_DECODED[0..3]` IS `NAMED_ESCAPE_TABLE`'s DECODED
        // column, `ESCAPE_DECODED[3..5]` IS `SELF_ESCAPE_TABLE` (the
        // SELF sub-vocabulary's DECODED column IS its row column by
        // pattern-EQUALS-value identity). Pin the partition at the
        // index level so a reorder that broke the sub-vocabulary
        // boundary (e.g. moved a SELF row to index 2 to sort by C0
        // byte value, or interleaved a self row between two named
        // rows) fails HERE rather than as silent drift where consumers
        // that walk the array by index would route the wrong
        // sub-vocabulary's row through the wrong downstream handler.
        // Sibling-shape pin to
        // `atom_escape_sources_partitions_into_named_source_prefix_and_self_source_suffix`
        // one column over on the peer SOURCE-column SPAN.
        for (i, &(_, dec)) in Atom::NAMED_ESCAPE_TABLE.iter().enumerate() {
            assert_eq!(
                Atom::ESCAPE_DECODED[i],
                dec,
                "ESCAPE_DECODED[{i}] ({}) drifted from \
                 NAMED_ESCAPE_TABLE[{i}].1 ({dec}) — the named-decoded-\
                 prefix partition is broken.",
                Atom::ESCAPE_DECODED[i],
            );
        }
        for (i, &self_byte) in Atom::SELF_ESCAPE_TABLE.iter().enumerate() {
            let span_index = Atom::NAMED_ESCAPE_TABLE.len() + i;
            assert_eq!(
                Atom::ESCAPE_DECODED[span_index],
                self_byte,
                "ESCAPE_DECODED[{span_index}] ({}) drifted from \
                 SELF_ESCAPE_TABLE[{i}] ({self_byte}) — the self-decoded-\
                 suffix partition is broken (SELF rows are pattern-\
                 EQUALS-value so DECODED == SOURCE by definitional \
                 identity).",
                Atom::ESCAPE_DECODED[span_index],
            );
        }
    }

    #[test]
    fn atom_escape_decoded_projects_pointwise_from_escape_sources_through_decode_str_escape() {
        // COLUMN-DUAL POINTWISE PROJECTION LAW: the two forced-arity
        // `[char; 5]` peer arrays [`Atom::ESCAPE_SOURCES`] +
        // [`Atom::ESCAPE_DECODED`] are the SOURCE column and DECODED
        // column of `decode_str_escape`'s non-passthrough arm-set — for
        // every index `i` in `0..5`,
        // `ESCAPE_DECODED[i] == Atom::decode_str_escape(
        // ESCAPE_SOURCES[i])`. This is the NEW load-bearing invariant
        // this SPAN adds on top of `ESCAPE_SOURCES`: the column-dual
        // pointwise projection identity that pins the two `[char; 5]`
        // arrays as the two columns of the SAME arm-set at the SAME
        // row-order at rustc time. Pin the projection identity
        // structurally so a refactor that drifted either array's
        // declaration order OR drifted `decode_str_escape`'s match-arm
        // ordering surfaces HERE at the first drifted index rather
        // than at a distant sweep site. A regression that swapped
        // (e.g.) rows 3 and 4 in `ESCAPE_DECODED` without swapping
        // them in `ESCAPE_SOURCES` (or vice versa) would silently
        // collapse the column-dual identity; this pin catches the
        // divergence at the first drifted index.
        for (i, &src) in Atom::ESCAPE_SOURCES.iter().enumerate() {
            let expected = Atom::decode_str_escape(src);
            assert_eq!(
                Atom::ESCAPE_DECODED[i],
                expected,
                "ESCAPE_DECODED[{i}] ({}) drifted from \
                 decode_str_escape(ESCAPE_SOURCES[{i}] = {src:?}) = \
                 {expected:?} — the column-dual pointwise projection \
                 law from ESCAPE_SOURCES onto ESCAPE_DECODED through \
                 decode_str_escape is broken at index {i}.",
                Atom::ESCAPE_DECODED[i],
            );
        }
    }

    // ── `Atom::ESCAPE_TABLE` — the paired-column SPAN closing BOTH
    // columns of `decode_str_escape`'s FIVE non-passthrough arms at
    // ONE typed forced-arity `[(char, char); 5]` on the closed-set
    // [`Atom`] algebra. Peer-collapse of the two column-dual
    // `[char; 5]` peer arrays `Atom::ESCAPE_SOURCES` and
    // `Atom::ESCAPE_DECODED` at the paired-shape level. Tests pin
    // (a) the pointwise composition law `ESCAPE_TABLE[i] ==
    // (ESCAPE_SOURCES[i], ESCAPE_DECODED[i])`, (b) the forced-arity
    // `[(char, char); 5]` shape, (c) the sub-vocabulary partition into
    // NAMED-paired prefix + SELF-reshape suffix (the SELF sub-
    // vocabulary's rows re-shape from `char` to `(row, row)` via the
    // definitional-identity collapse), (d) the pattern-classification
    // partition where NAMED rows carry `row.0 != row.1` and SELF rows
    // carry `row.0 == row.1`, and (e) the pointwise projection law
    // `decode_str_escape(row.0) == row.1` for every row.

    #[test]
    fn atom_escape_table_composes_pointwise_from_escape_sources_and_escape_decoded_column_duals() {
        // POINTWISE COMPOSITION LAW: the paired-column SPAN's rows are
        // the two column-dual peer arrays zipped pointwise — for every
        // index `i` in `0..5`, `ESCAPE_TABLE[i] ==
        // (ESCAPE_SOURCES[i], ESCAPE_DECODED[i])`. This is the load-
        // bearing pointwise identity carrying the two-column
        // composition relation between the paired SPAN and its two
        // column-dual peer SPANs. A refactor that drifted any of the
        // three arrays' declaration orders OR drifted
        // `decode_str_escape`'s match-arm ordering surfaces HERE at
        // the first drifted index rather than at a distant sweep site.
        // Sibling-shape pin to
        // `atom_escape_decoded_projects_pointwise_from_escape_sources_through_decode_str_escape`
        // one composition layer up: where that pin binds the DECODED-
        // column SPAN to the SOURCE-column SPAN through
        // `decode_str_escape`, this pin binds the paired-column SPAN
        // to the two column-dual peer SPANs through pointwise
        // composition.
        assert_eq!(Atom::ESCAPE_TABLE.len(), Atom::ESCAPE_SOURCES.len());
        assert_eq!(Atom::ESCAPE_TABLE.len(), Atom::ESCAPE_DECODED.len());
        for (i, &(src, decoded)) in Atom::ESCAPE_TABLE.iter().enumerate() {
            assert_eq!(
                src,
                Atom::ESCAPE_SOURCES[i],
                "ESCAPE_TABLE[{i}].0 ({src:?}) drifted from \
                 ESCAPE_SOURCES[{i}] ({:?}) — the paired-column SPAN's \
                 SOURCE-column projection is broken at index {i}.",
                Atom::ESCAPE_SOURCES[i],
            );
            assert_eq!(
                decoded,
                Atom::ESCAPE_DECODED[i],
                "ESCAPE_TABLE[{i}].1 ({decoded:?}) drifted from \
                 ESCAPE_DECODED[{i}] ({:?}) — the paired-column SPAN's \
                 DECODED-column projection is broken at index {i}.",
                Atom::ESCAPE_DECODED[i],
            );
        }
    }

    #[test]
    fn atom_escape_table_has_expected_cardinality() {
        // ARITY PIN: the forced-arity `[(char, char); 5]` shape
        // survives at runtime AND matches the two column-dual peer
        // arrays' arities AND matches the summed cardinality of the
        // two sub-vocabulary arrays. Pins the closed-set size against
        // a refactor that loosens the array's type to
        // `&'static [(char, char)]` or `Vec<(char, char)>` (which
        // would drop the compile-time arity forcing rustc bakes into
        // `[T; N]` declarations) AND against a refactor that drifted
        // this array's arity without extending one of the two peer
        // column-dual arrays or one of the two peer sub-vocabulary
        // arrays. Sibling posture to
        // `atom_escape_sources_has_expected_cardinality` +
        // `atom_escape_decoded_has_expected_cardinality` on the two
        // column-dual peer SPANs.
        assert_eq!(
            Atom::ESCAPE_TABLE.len(),
            5,
            "ESCAPE_TABLE cardinality drifted from the substrate-\
             canonical FIVE non-passthrough arms of \
             Atom::decode_str_escape.",
        );
        assert_eq!(
            Atom::ESCAPE_TABLE.len(),
            Atom::ESCAPE_SOURCES.len(),
            "ESCAPE_TABLE cardinality drifted from the column-dual \
             peer ESCAPE_SOURCES's cardinality — the paired-column \
             shape symmetry `[(char, char); 5]` × `[char; 5]` on \
             decode_str_escape's non-passthrough arm-set is broken on \
             the SOURCE column.",
        );
        assert_eq!(
            Atom::ESCAPE_TABLE.len(),
            Atom::ESCAPE_DECODED.len(),
            "ESCAPE_TABLE cardinality drifted from the column-dual \
             peer ESCAPE_DECODED's cardinality — the paired-column \
             shape symmetry `[(char, char); 5]` × `[char; 5]` on \
             decode_str_escape's non-passthrough arm-set is broken on \
             the DECODED column.",
        );
        assert_eq!(
            Atom::ESCAPE_TABLE.len(),
            Atom::NAMED_ESCAPE_TABLE.len() + Atom::SELF_ESCAPE_TABLE.len(),
            "ESCAPE_TABLE cardinality drifted from the SUM of the two \
             peer sub-vocabulary arrays' cardinalities — the paired-\
             column SPAN identity is broken.",
        );
    }

    #[test]
    fn atom_escape_table_partitions_into_named_paired_prefix_and_self_reshape_suffix() {
        // SUB-VOCABULARY PARTITION LAW: `ESCAPE_TABLE[0..3]` IS the
        // NAMED_ESCAPE_TABLE (pattern-DISTINCT-from-value sub-
        // vocabulary at its native paired shape passes through
        // identically); `ESCAPE_TABLE[3..5]` re-shapes the SELF_ESCAPE_TABLE
        // rows from `char` to `(row, row)` via the definitional-
        // identity collapse (pattern-EQUALS-value sub-vocabulary). The
        // index-level partition pin binds every consumer walking the
        // paired-column SPAN by index to the (named-paired prefix,
        // self-reshape suffix) partition at rustc time. Sibling
        // posture to
        // `atom_escape_sources_partitions_into_named_source_prefix_and_self_source_suffix`
        // + `atom_escape_decoded_partitions_into_named_decoded_prefix_and_self_decoded_suffix`
        // on the two column-dual peer SPANs.
        assert_eq!(
            &Atom::ESCAPE_TABLE[0..3],
            &Atom::NAMED_ESCAPE_TABLE[..],
            "ESCAPE_TABLE named-paired prefix drifted from \
             NAMED_ESCAPE_TABLE — the sub-vocabulary partition is \
             broken.",
        );
        for (self_index, &row) in Atom::SELF_ESCAPE_TABLE.iter().enumerate() {
            let span_index = Atom::NAMED_ESCAPE_TABLE.len() + self_index;
            assert_eq!(
                Atom::ESCAPE_TABLE[span_index],
                (row, row),
                "ESCAPE_TABLE[{span_index}] ({:?}) drifted from the \
                 SELF-reshape suffix pair (SELF_ESCAPE_TABLE[{self_index}], \
                 SELF_ESCAPE_TABLE[{self_index}]) = ({row:?}, \
                 {row:?}) — the pattern-EQUALS-value definitional-\
                 identity reshape is broken.",
                Atom::ESCAPE_TABLE[span_index],
            );
        }
    }

    #[test]
    fn atom_escape_table_named_prefix_is_pattern_distinct_and_self_suffix_is_pattern_equals() {
        // PATTERN-CLASSIFICATION PARTITION LAW: the paired-column
        // SPAN's rows encode their sub-vocabulary identity in the
        // per-row per-column identity relation — NAMED rows (indices
        // 0..3) carry `row.0 != row.1` (pattern-DISTINCT-from-value),
        // SELF rows (indices 3..5) carry `row.0 == row.1` (pattern-
        // EQUALS-value). A consumer classifying an escape arm reads
        // the sub-vocabulary off `row.0 == row.1` rather than off an
        // index range or a separate tag — the classification IS the
        // pair's per-column identity relation. Pins the load-bearing
        // structural invariant that the paired-column SPAN encodes
        // both sub-vocabularies AT the paired shape.
        for i in 0..Atom::NAMED_ESCAPE_TABLE.len() {
            let (src, decoded) = Atom::ESCAPE_TABLE[i];
            assert_ne!(
                src, decoded,
                "ESCAPE_TABLE[{i}] ({src:?}, {decoded:?}) is in the \
                 NAMED prefix but its per-column identity relation \
                 collapsed to `src == decoded` — the pattern-DISTINCT-\
                 from-value classification is broken.",
            );
        }
        for self_index in 0..Atom::SELF_ESCAPE_TABLE.len() {
            let span_index = Atom::NAMED_ESCAPE_TABLE.len() + self_index;
            let (src, decoded) = Atom::ESCAPE_TABLE[span_index];
            assert_eq!(
                src, decoded,
                "ESCAPE_TABLE[{span_index}] ({src:?}, {decoded:?}) is \
                 in the SELF suffix but its per-column identity \
                 relation split to `src != decoded` — the pattern-\
                 EQUALS-value definitional-identity classification is \
                 broken.",
            );
        }
    }

    #[test]
    fn atom_escape_table_every_row_projects_through_decode_str_escape_pointwise() {
        // POINTWISE PROJECTION LAW: for every `(src, decoded)` row in
        // ESCAPE_TABLE, `Atom::decode_str_escape(src) == decoded`. The
        // paired-column SPAN closes the (input, output) cross-product
        // of `decode_str_escape`'s non-passthrough arm-set at ONE typed
        // array so a refactor that drifted the arm-set (swapped rows
        // in ESCAPE_TABLE without swapping them in `decode_str_escape`
        // or vice versa) surfaces HERE at the first drifted pair
        // rather than at a distant sweep site. Sibling-shape pin to
        // `atom_escape_decoded_projects_pointwise_from_escape_sources_through_decode_str_escape`
        // one composition layer over: where that pin binds the two
        // column-dual peer SPANs through `decode_str_escape`, this pin
        // binds the paired-column SPAN's per-row `(src, decoded)`
        // shape to `decode_str_escape`'s projection at the row level.
        for (i, &(src, decoded)) in Atom::ESCAPE_TABLE.iter().enumerate() {
            let projected = Atom::decode_str_escape(src);
            assert_eq!(
                projected, decoded,
                "ESCAPE_TABLE[{i}] = ({src:?}, {decoded:?}) drifted \
                 from Atom::decode_str_escape({src:?}) = {projected:?} \
                 — the paired-column SPAN's per-row projection law is \
                 broken at index {i}.",
            );
        }
    }

    #[test]
    fn atom_escape_table_sources_and_decoded_columns_pairwise_distinct() {
        // COLUMN-WISE PAIRWISE DISJOINTNESS: the paired-column SPAN's
        // SOURCE column AND DECODED column are each pairwise distinct.
        // Inherited disjointness from the two column-dual peer
        // `[char; 5]` SPANs already pinned at
        // `atom_escape_sources_pairwise_distinct` +
        // `atom_escape_decoded_pairwise_distinct`, but pinned HERE at
        // the paired-array level so a refactor that drifted the paired
        // SPAN's declaration order (collapsing two arms onto the same
        // SOURCE or DECODED byte) surfaces at this test rather than
        // at a distant sweep site. Sibling posture to the two column-
        // dual peer SPANs' pairwise-distinctness tests.
        for i in 0..Atom::ESCAPE_TABLE.len() {
            for j in (i + 1)..Atom::ESCAPE_TABLE.len() {
                assert_ne!(
                    Atom::ESCAPE_TABLE[i].0,
                    Atom::ESCAPE_TABLE[j].0,
                    "ESCAPE_TABLE SOURCE column collision: \
                     ESCAPE_TABLE[{i}].0 and ESCAPE_TABLE[{j}].0 are \
                     both {:?} — the paired-column SPAN's SOURCE \
                     column pairwise disjointness is broken.",
                    Atom::ESCAPE_TABLE[i].0,
                );
                assert_ne!(
                    Atom::ESCAPE_TABLE[i].1,
                    Atom::ESCAPE_TABLE[j].1,
                    "ESCAPE_TABLE DECODED column collision: \
                     ESCAPE_TABLE[{i}].1 and ESCAPE_TABLE[{j}].1 are \
                     both {:?} — the paired-column SPAN's DECODED \
                     column pairwise disjointness is broken.",
                    Atom::ESCAPE_TABLE[i].1,
                );
            }
        }
    }

    // ── `Sexp::LIST_OPEN` / `Sexp::LIST_CLOSE` — the paired canonical
    // `(` / `)` chars routed through the FOUR outer-structural round-
    // trip sites: two `crate::reader::tokenize` outer-dispatch arms
    // (`Token::LParen`, `Token::RParen`), two bare-atom terminator
    // disjuncts (`|| ch == LIST_OPEN` / `|| ch == LIST_CLOSE`), and
    // two `fmt::Display for Sexp` arms (`Self::List(_)` opener +
    // closer AND `Self::Nil` two-char `()`). Sibling-shape tests to
    // the `atom_str_delimiter_*` block above (Str-payload delimiter
    // axis), lifted onto the outer-structural [`Sexp`] algebra.

    #[test]
    fn sexp_list_open_projects_canonical_open_paren_char() {
        // Pins the constant's exact `char` value so a typo (`'['`,
        // `'{'`, `';'`) or an accidental redefinition surfaces
        // immediately. Sibling-shape pin to
        // `atom_str_delimiter_projects_canonical_double_quote_char`
        // (the Str-payload delimiter axis) — pins the SAME shape on
        // the outer list-opener axis of the closed-set outer [`Sexp`]
        // algebra.
        assert_eq!(
            Sexp::LIST_OPEN,
            '(',
            "LIST_OPEN char drifted from the substrate-canonical `(` \
             opener — the reader-round-trip contract at \
             crate::reader::tokenize (Token::LParen outer arm, bare-\
             atom terminator disjunct) AND fmt::Display for Sexp \
             (Self::List(_) opener, Self::Nil two-char left) all bind \
             to this ONE constant.",
        );
    }

    #[test]
    fn sexp_list_close_projects_canonical_close_paren_char() {
        // Pins the constant's exact `char` value so a typo (`']'`,
        // `'}'`, `';'`) or an accidental redefinition surfaces
        // immediately. Section-for-retraction sibling pin of the
        // opener above; the paired-delimiter round-trip contract
        // holds iff both constants pin their canonical bytes here.
        assert_eq!(
            Sexp::LIST_CLOSE,
            ')',
            "LIST_CLOSE char drifted from the substrate-canonical `)` \
             closer — the reader-round-trip contract at \
             crate::reader::tokenize (Token::RParen outer arm, bare-\
             atom terminator disjunct) AND fmt::Display for Sexp \
             (Self::List(_) closer, Self::Nil two-char right) all \
             bind to this ONE constant.",
        );
    }

    #[test]
    fn sexp_list_delimiters_distinct_from_every_other_algebra_marker() {
        // Cross-axis disjointness pin: neither `Sexp::LIST_OPEN` nor
        // `Sexp::LIST_CLOSE` may alias any sibling outer-marker
        // char on the substrate's other closed-set algebras — the
        // Str-payload delimiter (`Atom::STR_DELIMITER`), the
        // Keyword-marker prefix (`Atom::KEYWORD_MARKER`), the two
        // Bool-literal spellings (`Atom::bool_literal(true|false)`),
        // AND every quote-family lead char
        // (`QuoteForm::lead_char(qf)` for each `qf` in
        // `QuoteForm::ALL`). Otherwise a bare `(`/`)`-starting lexeme
        // would ambiguously route through TWO outer-dispatch arms in
        // `crate::reader::tokenize`. Guards the paired disjointness
        // across the substrate's outer-marker axes so a future
        // refactor that swaps a marker to collide with either list
        // delimiter surfaces at this pin rather than as a silent
        // reader misclassification.
        //
        // First: opener/closer disjoint from each other — pairs
        // MUST be structurally distinct.
        assert_ne!(
            Sexp::LIST_OPEN,
            Sexp::LIST_CLOSE,
            "LIST_OPEN and LIST_CLOSE share a byte — the paired-\
             delimiter contract would collapse.",
        );

        // Second: opener/closer disjoint from Str-delimiter.
        assert_ne!(
            Sexp::LIST_OPEN,
            Atom::STR_DELIMITER,
            "LIST_OPEN and STR_DELIMITER share a byte — a bare `{}foo` \
             lexeme would ambiguously begin a list AND open a string.",
            Atom::STR_DELIMITER,
        );
        assert_ne!(
            Sexp::LIST_CLOSE,
            Atom::STR_DELIMITER,
            "LIST_CLOSE and STR_DELIMITER share a byte — a bare `{}foo` \
             lexeme would ambiguously close a list AND open a string.",
            Atom::STR_DELIMITER,
        );

        // Third: opener/closer disjoint from KEYWORD_MARKER's LEAD
        // `char` (single-char `":"` on the outer axis) — the
        // `Atom::KEYWORD_MARKER` `&'static str`'s projected lead byte
        // lives at `Atom::KEYWORD_MARKER_LEAD` on the closed-set
        // outer [`Atom`] algebra.
        assert_ne!(
            Sexp::LIST_OPEN,
            Atom::KEYWORD_MARKER_LEAD,
            "LIST_OPEN and KEYWORD_MARKER_LEAD share a byte — a bare \
             `{}foo` lexeme would ambiguously begin a list AND begin \
             a keyword.",
            Atom::KEYWORD_MARKER_LEAD,
        );
        assert_ne!(
            Sexp::LIST_CLOSE,
            Atom::KEYWORD_MARKER_LEAD,
            "LIST_CLOSE and KEYWORD_MARKER_LEAD share a byte — a bare \
             `{}foo` lexeme would ambiguously close a list AND begin \
             a keyword.",
            Atom::KEYWORD_MARKER_LEAD,
        );

        // Fourth: opener/closer disjoint from every Bool-literal
        // spelling's first char (`'#'` for both `"#t"` / `"#f"`).
        for b in [true, false] {
            let lead = Atom::bool_literal(b)
                .chars()
                .next()
                .expect("bool_literal must be non-empty");
            assert_ne!(
                Sexp::LIST_OPEN,
                lead,
                "LIST_OPEN and bool_literal({b:?}) share a lead byte — a \
                 bare `{lead}...` lexeme would ambiguously begin a list \
                 AND classify as a Bool.",
            );
            assert_ne!(
                Sexp::LIST_CLOSE,
                lead,
                "LIST_CLOSE and bool_literal({b:?}) share a lead byte — a \
                 bare `{lead}...` lexeme would ambiguously close a list \
                 AND classify as a Bool.",
            );
        }

        // Fifth: opener/closer disjoint from every quote-family
        // lead char (`'\''`, `` '`' ``, `','` — three distinct lead
        // chars across the four `QuoteForm` variants). The reader's
        // outer-dispatch orders the quote-family arm BEFORE the
        // list-delimiter arms, so a collision here would silently
        // route `(`/`)` through the quote-family branch.
        for qf in QuoteForm::ALL {
            assert_ne!(
                Sexp::LIST_OPEN,
                qf.lead_char(),
                "LIST_OPEN and QuoteForm::{qf:?}::lead_char share a byte — \
                 a bare `(...)` list would silently route through the \
                 quote-family outer-dispatch arm.",
            );
            assert_ne!(
                Sexp::LIST_CLOSE,
                qf.lead_char(),
                "LIST_CLOSE and QuoteForm::{qf:?}::lead_char share a byte — \
                 a bare `(...)` list-closer would silently route through \
                 the quote-family outer-dispatch arm.",
            );
        }
    }

    #[test]
    fn sexp_display_nil_arm_binds_to_both_list_delimiter_constants() {
        // NIL DISPLAY CONTRACT: pin that `format!("{}", Sexp::Nil)`
        // produces the two-char rendering composed of BOTH typed
        // delimiters — `LIST_OPEN` followed by `LIST_CLOSE`. Pre-lift
        // this arm carried the two bytes inline as ONE `"()"` string
        // literal; post-lift each byte binds to its typed constant,
        // so a delimiter swap flips both the opener AND the closer in
        // lockstep at the typed algebra rather than at this arm's
        // inline literal. A regression that re-inlines the two bytes
        // OR drifts ONE of the two typed-constant bindings fails
        // loudly at this composition pin.
        let rendered = format!("{}", Sexp::Nil);
        let expected: String = Sexp::LIST_DELIMITERS.iter().collect();
        assert_eq!(
            rendered, expected,
            "Sexp::Nil Display drifted from the [LIST_OPEN, LIST_CLOSE] \
             composition — the two-char `()` rendering must be the \
             string composed of the two typed constants in order.",
        );
        // Cross-check against the bare byte-string to catch a
        // regression that silently swaps the two constants' values.
        assert_eq!(
            rendered, "()",
            "Sexp::Nil Display drifted from the canonical `()` two-char \
             rendering — a typed-constant swap would produce e.g. `)(` \
             which passes the `[LIST_OPEN, LIST_CLOSE]` compose test \
             but fails this hard-coded reference check.",
        );
    }

    #[test]
    fn sexp_display_list_arms_bind_to_sexp_list_delimiter_constants() {
        // LIST DISPLAY CONTRACT: pin that `format!("{}", Sexp::List(_))`
        // opens with `LIST_OPEN`, closes with `LIST_CLOSE`, and
        // interleaves the children through the arm's ` `-separator
        // loop. Sweeps a representative small list plus the singleton
        // list plus the empty list — the empty list is IMPORTANT
        // because `Sexp::List(vec![])` is a distinct `Sexp` shape from
        // `Sexp::Nil`, and both must render as `()` through the outer
        // algebra (the reader's `()` source produces `Sexp::List(vec![])`
        // — see the `read` pipeline in `crate::reader`). A regression
        // that drifts either arm's binding surfaces here.
        for list in [
            Sexp::List(vec![]),
            Sexp::List(vec![Sexp::symbol("x")]),
            Sexp::List(vec![Sexp::symbol("a"), Sexp::symbol("b")]),
            Sexp::List(vec![Sexp::int(1), Sexp::int(2), Sexp::int(3)]),
        ] {
            let rendered = format!("{list}");
            let first = rendered
                .chars()
                .next()
                .unwrap_or_else(|| panic!("empty rendering for {list:?}"));
            let last = rendered
                .chars()
                .last()
                .unwrap_or_else(|| panic!("empty rendering for {list:?}"));
            assert_eq!(
                first,
                Sexp::LIST_OPEN,
                "List Display opener drifted from LIST_OPEN for {list:?}: \
                 got {rendered:?}",
            );
            assert_eq!(
                last,
                Sexp::LIST_CLOSE,
                "List Display closer drifted from LIST_CLOSE for {list:?}: \
                 got {rendered:?}",
            );
        }
    }

    #[test]
    fn sexp_list_delimiters_close_reader_display_round_trip_for_lists_of_atoms() {
        // Load-bearing round-trip contract for the four outer-
        // structural sites — the reader's `Token::LParen` /
        // `Token::RParen` outer-dispatch arms both bind to
        // `Sexp::LIST_OPEN` / `Sexp::LIST_CLOSE`, AND the Display
        // impl's `Self::List(_)` arms bind to the SAME two constants,
        // so wrapping a sequence of atom lexemes in the constants on
        // both sides recovers a `Sexp::List(_)` shape that
        // round-trips through Display and the reader without drift.
        // A regression that swaps ONE of the four arms (e.g.
        // re-inlines `'('` at the reader opener while migrating the
        // Display opener to a different delimiter) breaks the
        // opener-must-match-closer contract across two files.
        for children in [
            vec![],
            vec![Sexp::symbol("foo")],
            vec![Sexp::symbol("a"), Sexp::symbol("b"), Sexp::int(42)],
        ] {
            let original = Sexp::List(children);
            let rendered = format!("{original}");
            let reread = crate::reader::read(&rendered).unwrap_or_else(|e| {
                panic!(
                    "reader rejected Display-rendered list `{rendered}` \
                     for `{original:?}`: {e}"
                )
            });
            assert_eq!(
                reread.len(),
                1,
                "Display-rendered list `{rendered}` must read as exactly \
                 one form, got {reread:?}",
            );
            assert_eq!(
                reread[0], original,
                "read(display(list)) drifted from list for {original:?} \
                 — rendered={rendered:?} reread={reread:?}",
            );
        }
    }

    #[test]
    fn sexp_list_delimiters_composes_from_algebra_constants_in_declaration_order() {
        // FAMILY COMPOSITION LAW: pin that the ALL array's rows are the
        // two paired-delimiter algebra constants (`Self::LIST_OPEN`,
        // `Self::LIST_CLOSE`) in canonical declaration order matching
        // the substrate-canonical (opener, closer) pair shape every
        // consumer expects. A reorder of ONE row without reordering
        // the underlying algebra constants silently misaligns every
        // index-sweep consumer (`Nil` Display's `.iter().collect()`
        // routing, a hypothetical `Sexp::LIST_DELIMITERS[0]` opener
        // lookup, the sub-vocabulary sweep at
        // `is_bare_atom_boundary`). Sibling-shape pin to
        // `atom_self_escape_table_composes_from_algebra_constants_in_declaration_order`
        // on the peer `[char; 2]` sub-vocabulary at
        // [`Atom::SELF_ESCAPE_TABLE`].
        assert_eq!(
            Sexp::LIST_DELIMITERS,
            [Sexp::LIST_OPEN, Sexp::LIST_CLOSE],
            "LIST_DELIMITERS composition drifted from the canonical \
             (LIST_OPEN, LIST_CLOSE) pair — the paired-delimiter \
             sub-vocabulary lift must route through the two typed \
             algebra constants in that order.",
        );
    }

    #[test]
    fn sexp_list_delimiters_has_expected_cardinality() {
        // CARDINALITY PIN: `[char; 2]` at rustc — this assert pins the
        // runtime observable so a refactor that loosens the array's
        // type to `&[char]` (dropping the compile-time arity forcing)
        // fails HERE at the runtime cardinality assertion rather than
        // silently allowing a third or absent row. Sibling-shape pin
        // to `atom_self_escape_table_has_expected_cardinality`.
        assert_eq!(
            Sexp::LIST_DELIMITERS.len(),
            2,
            "LIST_DELIMITERS cardinality drifted from 2 — the paired \
             (opener, closer) sub-vocabulary MUST be exactly two rows.",
        );
    }

    #[test]
    fn sexp_list_delimiters_pairwise_distinct() {
        // PAIRWISE DISJOINTNESS: the two paired-delimiter rows MUST NOT
        // alias (a hypothetical `[` opener + `[` closer degenerate
        // list-mode would silently collapse the paired-delimiter
        // contract and lose the ability to bracket a well-formed list
        // — the reader's `Token::LParen` and `Token::RParen` arms
        // would collide at the same byte). Sibling-shape pin to
        // `atom_self_escape_table_pairwise_distinct` on the peer
        // `[char; 2]` sub-vocabulary at [`Atom::SELF_ESCAPE_TABLE`].
        for (i, a) in Sexp::LIST_DELIMITERS.iter().enumerate() {
            for (j, b) in Sexp::LIST_DELIMITERS.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "LIST_DELIMITERS rows [{i}] and [{j}] share a byte \
                     ({a:?} == {b:?}) — the paired-delimiter contract \
                     would collapse.",
                );
            }
        }
    }

    #[test]
    fn sexp_list_delimiters_disjoint_from_str_delimiter() {
        // CROSS-AXIS DISJOINTNESS (Str-delimiter): no row of
        // `LIST_DELIMITERS` may alias `Atom::STR_DELIMITER` — otherwise
        // the reader's `Token::LParen` / `Token::RParen` outer-dispatch
        // arms would collide with `Token::Str`'s opener/closer arm at
        // the same byte. Sibling-shape pin to
        // `atom_named_escape_table_disjoint_from_self_escape_algebra_constants`:
        // both close the cross-sub-vocabulary disjointness contract at
        // the ALL-array level rather than as an inline disjunction per
        // consumer.
        for (i, ch) in Sexp::LIST_DELIMITERS.iter().enumerate() {
            assert_ne!(
                *ch,
                Atom::STR_DELIMITER,
                "LIST_DELIMITERS[{i}] ({ch:?}) aliases Atom::STR_DELIMITER \
                 ({:?}) — the reader's list-delimiter arm would collide \
                 with the Str-payload delimiter arm at the same byte.",
                Atom::STR_DELIMITER,
            );
        }
    }

    #[test]
    fn sexp_list_delimiters_disjoint_from_comment_lead() {
        // CROSS-AXIS DISJOINTNESS (comment lead): no row of
        // `LIST_DELIMITERS` may alias `Sexp::COMMENT_LEAD` — otherwise
        // the reader's list-delimiter arm would collide with the
        // line-comment discard arm at the same byte. Closes the
        // structural coherence contract between the outer-structural
        // list-delimiter sub-vocabulary and the reader-discard
        // sub-vocabulary on the SAME closed-set outer [`Sexp`]
        // algebra.
        for (i, ch) in Sexp::LIST_DELIMITERS.iter().enumerate() {
            assert_ne!(
                *ch,
                Sexp::COMMENT_LEAD,
                "LIST_DELIMITERS[{i}] ({ch:?}) aliases Sexp::COMMENT_LEAD \
                 ({:?}) — the reader's list-delimiter arm would collide \
                 with the line-comment lead arm at the same byte.",
                Sexp::COMMENT_LEAD,
            );
        }
    }

    #[test]
    fn sexp_is_bare_atom_boundary_routes_through_list_delimiters_for_every_row() {
        // PATH-UNIFORMITY PIN: every row of `LIST_DELIMITERS` MUST
        // classify as a bare-atom boundary via
        // `Sexp::is_bare_atom_boundary`. A regression that reverted the
        // projection's list-delimiter disjunct to two inline
        // `|| ch == Self::LIST_OPEN || ch == Self::LIST_CLOSE`
        // enumerations AND drifted one of the two constants (or vice
        // versa) fails HERE at the first mismatched row rather than at
        // a distant tokenize-round-trip. Sibling-shape pin to
        // `atom_decode_str_escape_routes_through_self_escape_table_for_every_row`
        // on the peer `[char; 2]` sub-vocabulary at
        // [`Atom::SELF_ESCAPE_TABLE`].
        for (i, ch) in Sexp::LIST_DELIMITERS.iter().enumerate() {
            assert!(
                Sexp::is_bare_atom_boundary(*ch),
                "LIST_DELIMITERS[{i}] ({ch:?}) does NOT classify as a \
                 bare-atom boundary via Sexp::is_bare_atom_boundary — \
                 the paired-delimiter sub-vocabulary sweep drifted from \
                 the reader's outer-dispatch arm-set.",
            );
        }
    }

    // ── `Sexp::COMMENT_LEAD` — the canonical `;` char routed through
    // the reader's TWO comment-boundary sites: the outer-dispatch arm
    // that begins a line-comment run AND the bare-atom terminator
    // disjunct that breaks a `Token::Atom` accumulator on this byte.
    // Sibling-shape tests to the `sexp_list_open_close` block above
    // (outer-structural paired-delimiter axis), lifted onto the reader-
    // discard axis of the closed-set outer [`Sexp`] algebra.

    #[test]
    fn sexp_comment_lead_projects_canonical_semicolon_char() {
        // Pins the constant's exact `char` value so a typo (`'#'`,
        // `'!'`, `':'`) or an accidental redefinition surfaces
        // immediately. Sibling-shape pin to
        // `sexp_list_open_projects_canonical_open_paren_char` on the
        // outer-structural axis — pins the SAME shape on the reader-
        // discard axis of the closed-set outer [`Sexp`] algebra.
        assert_eq!(
            Sexp::COMMENT_LEAD,
            ';',
            "COMMENT_LEAD char drifted from the substrate-canonical `;` \
             line-comment lead — the reader-discard contract at \
             crate::reader::tokenize (line-comment outer arm, bare-atom \
             terminator disjunct) binds to this ONE constant.",
        );
    }

    #[test]
    fn sexp_comment_lead_distinct_from_every_other_algebra_marker() {
        // Cross-axis disjointness pin: `Sexp::COMMENT_LEAD` may NOT
        // alias any sibling outer-marker char on the substrate's other
        // closed-set algebras — the paired list delimiters
        // (`Sexp::LIST_OPEN` / `Sexp::LIST_CLOSE`), the Str-payload
        // delimiter (`Atom::STR_DELIMITER`), the Keyword-marker prefix
        // (`Atom::KEYWORD_MARKER`'s lead byte), the two Bool-literal
        // spellings' lead byte (`Atom::bool_literal(true|false)`'s first
        // char), AND every quote-family lead char
        // (`QuoteForm::lead_char(qf)` for each `qf` in `QuoteForm::ALL`).
        // Otherwise a bare `;`-starting lexeme would ambiguously route
        // through the line-comment arm AND a sibling algebra's arm in
        // `crate::reader::tokenize`. Guards the paired disjointness
        // across the substrate's outer-marker axes so a future refactor
        // that swaps a marker to collide with the comment lead surfaces
        // at this pin rather than as a silent reader misclassification.
        assert_ne!(
            Sexp::COMMENT_LEAD,
            Sexp::LIST_OPEN,
            "COMMENT_LEAD and LIST_OPEN share a byte — a bare `{}foo` \
             lexeme would ambiguously begin a list AND begin a comment.",
            Sexp::LIST_OPEN,
        );
        assert_ne!(
            Sexp::COMMENT_LEAD,
            Sexp::LIST_CLOSE,
            "COMMENT_LEAD and LIST_CLOSE share a byte — a bare `{}foo` \
             lexeme would ambiguously close a list AND begin a comment.",
            Sexp::LIST_CLOSE,
        );
        assert_ne!(
            Sexp::COMMENT_LEAD,
            Atom::STR_DELIMITER,
            "COMMENT_LEAD and STR_DELIMITER share a byte — a bare `{}foo` \
             lexeme would ambiguously begin a comment AND open a string.",
            Atom::STR_DELIMITER,
        );
        assert_ne!(
            Sexp::COMMENT_LEAD,
            Atom::KEYWORD_MARKER_LEAD,
            "COMMENT_LEAD and KEYWORD_MARKER_LEAD share a byte — a bare \
             `{lead}foo` lexeme would ambiguously begin a comment AND \
             begin a keyword.",
            lead = Atom::KEYWORD_MARKER_LEAD,
        );
        for b in [true, false] {
            let lead = Atom::bool_literal(b)
                .chars()
                .next()
                .expect("bool_literal must be non-empty");
            assert_ne!(
                Sexp::COMMENT_LEAD,
                lead,
                "COMMENT_LEAD and bool_literal({b:?}) share a lead byte — a \
                 bare `{lead}...` lexeme would ambiguously begin a comment \
                 AND classify as a Bool.",
            );
        }
        for qf in QuoteForm::ALL {
            assert_ne!(
                Sexp::COMMENT_LEAD,
                qf.lead_char(),
                "COMMENT_LEAD and QuoteForm::{qf:?}::lead_char share a byte — \
                 a bare `;`-starting source would silently route through the \
                 quote-family outer-dispatch arm.",
            );
        }
    }

    // ── `Sexp::COMMENT_TERM` — the canonical `\n` char that terminates
    // a line-comment run in the reader's tokenizer. Section-for-retraction
    // sibling of `Sexp::COMMENT_LEAD` on the reader-discard axis; paired
    // opener/terminator peer of `Sexp::LIST_OPEN` / `Sexp::LIST_CLOSE`
    // on the outer-structural axis. The pins below anchor the constant's
    // exact byte AND its cross-axis disjointness against every
    // non-whitespace closed-set outer-marker char.

    #[test]
    fn sexp_comment_term_projects_canonical_line_feed_char() {
        // Pins the constant's exact `char` value so a typo (`'\r'`,
        // `'\0'`, a display-glyph substitution) or an accidental
        // redefinition surfaces immediately. Sibling-shape pin to
        // `sexp_comment_lead_projects_canonical_semicolon_char` on the
        // reader-discard axis — pins the SAME shape at the terminator
        // side of the (COMMENT_LEAD, COMMENT_TERM) paired-delimiter
        // algebra on the closed-set outer [`Sexp`] algebra.
        assert_eq!(
            Sexp::COMMENT_TERM,
            '\n',
            "COMMENT_TERM char drifted from the substrate-canonical `\\n` \
             line-feed byte — the reader-discard contract at \
             crate::reader::tokenize's line-comment discard loop binds \
             to this ONE constant.",
        );
    }

    #[test]
    fn sexp_comment_term_is_whitespace_family_char() {
        // WHITESPACE-FAMILY PIN: the line-comment terminator MUST be a
        // whitespace char. The reader's outer-match's `ws if
        // ws.is_whitespace()` arm absorbs any lingering COMMENT_TERM
        // byte after the discard loop terminates on it — a regression
        // that repointed COMMENT_TERM at a NON-whitespace byte would
        // BOTH break the discard loop's semantics AND leak the byte
        // into the token stream as an outer-dispatch dispatch (either a
        // specific arm firing on it, or the bare-atom accumulator
        // consuming it). Pin the property structurally so a byte swap
        // that lost whitespace-family membership surfaces here rather
        // than as a downstream tokenizer misclassification.
        assert!(
            Sexp::COMMENT_TERM.is_whitespace(),
            "COMMENT_TERM `{:?}` is NOT a whitespace char — the reader's \
             outer-match whitespace arm would fail to absorb it AND the \
             line-comment discard loop's terminator would leak the byte \
             into the token stream.",
            Sexp::COMMENT_TERM,
        );
    }

    #[test]
    fn sexp_comment_term_distinct_from_every_non_whitespace_algebra_marker() {
        // Cross-axis disjointness pin: `Sexp::COMMENT_TERM` may NOT
        // alias any NON-whitespace sibling outer-marker char on the
        // substrate's other closed-set algebras — the paired list
        // delimiters (`Sexp::LIST_OPEN` / `Sexp::LIST_CLOSE`), the
        // line-comment lead (`Sexp::COMMENT_LEAD`), the Str-payload
        // delimiter + escape-lead (`Atom::STR_DELIMITER` /
        // `Atom::STR_ESCAPE_LEAD`), the Keyword-marker prefix
        // (`Atom::KEYWORD_MARKER`'s lead byte), the two Bool-literal
        // spellings' lead byte (`Atom::bool_literal(true|false)`'s
        // first char), AND every quote-family lead char
        // (`QuoteForm::lead_char(qf)` for each `qf` in `QuoteForm::ALL`).
        // The disjointness contract EXCLUDES the whitespace-family
        // axis — the terminator's role IS to be whitespace-family, so
        // the outer-match's `ws if ws.is_whitespace()` arm absorbs it
        // by design (see `sexp_comment_term_is_whitespace_family_char`
        // above). Sibling-shape pin to
        // `sexp_comment_lead_distinct_from_every_other_algebra_marker`
        // on the lead side of the paired-delimiter algebra — pins the
        // SAME shape at the terminator side.
        assert_ne!(
            Sexp::COMMENT_TERM,
            Sexp::LIST_OPEN,
            "COMMENT_TERM and LIST_OPEN share a byte — the reader's \
             line-comment discard loop would terminate on the SAME byte \
             the outer-dispatch's list-opening arm binds to.",
        );
        assert_ne!(
            Sexp::COMMENT_TERM,
            Sexp::LIST_CLOSE,
            "COMMENT_TERM and LIST_CLOSE share a byte — the reader's \
             line-comment discard loop would terminate on the SAME byte \
             the outer-dispatch's list-closing arm binds to.",
        );
        assert_ne!(
            Sexp::COMMENT_TERM,
            Sexp::COMMENT_LEAD,
            "COMMENT_TERM and COMMENT_LEAD share a byte — a bare \
             `{lead}{lead}` two-char source would AMBIGUOUSLY begin AND \
             terminate the SAME comment run at the SAME byte, collapsing \
             the paired-delimiter algebra onto ONE char.",
            lead = Sexp::COMMENT_LEAD,
        );
        assert_ne!(
            Sexp::COMMENT_TERM,
            Atom::STR_DELIMITER,
            "COMMENT_TERM and STR_DELIMITER share a byte — the reader's \
             line-comment discard loop would terminate on the SAME byte \
             the outer-dispatch's string-opening arm binds to.",
        );
        assert_ne!(
            Sexp::COMMENT_TERM,
            Atom::STR_ESCAPE_LEAD,
            "COMMENT_TERM and STR_ESCAPE_LEAD share a byte — the reader's \
             line-comment discard loop would terminate on the SAME byte \
             the Str-payload's escape-handler outer arm binds to.",
        );
        assert_ne!(
            Sexp::COMMENT_TERM,
            Atom::KEYWORD_MARKER_LEAD,
            "COMMENT_TERM and KEYWORD_MARKER_LEAD share a byte — the \
             reader's line-comment discard loop would terminate on the \
             SAME byte the from_lexeme keyword-prefix arm binds to.",
        );
        for b in [true, false] {
            let lead = Atom::bool_literal(b)
                .chars()
                .next()
                .expect("bool_literal must be non-empty");
            assert_ne!(
                Sexp::COMMENT_TERM,
                lead,
                "COMMENT_TERM and bool_literal({b:?}) share a lead byte — \
                 the reader's line-comment discard loop would terminate \
                 on the SAME byte the from_lexeme bool-literal arm binds \
                 to.",
            );
        }
        for qf in QuoteForm::ALL {
            assert_ne!(
                Sexp::COMMENT_TERM,
                qf.lead_char(),
                "COMMENT_TERM and QuoteForm::{qf:?}::lead_char share a \
                 byte — the reader's line-comment discard loop would \
                 terminate on the SAME byte the quote-family outer- \
                 dispatch arm binds to.",
            );
        }
    }

    // ── `Sexp::COMMENT_DELIMITERS` — the paired (opener, terminator)
    // reader-discard sub-vocabulary on the closed-set outer [`Sexp`]
    // algebra. Sibling-shape tests to the `sexp_list_delimiters_*` block
    // above (outer-structural paired-delimiter axis), lifted onto the
    // reader-discard axis of the SAME algebra at the SAME `[char; 2]`
    // shape.

    #[test]
    fn sexp_comment_delimiters_composes_from_algebra_constants_in_declaration_order() {
        // FAMILY COMPOSITION LAW: pin that the ALL array's rows are the
        // two paired reader-discard algebra constants
        // (`Self::COMMENT_LEAD`, `Self::COMMENT_TERM`) in canonical
        // (opener, terminator) declaration order matching the
        // substrate-canonical paired-role shape every consumer expects.
        // A reorder of ONE row without reordering the underlying
        // algebra constants silently misaligns every index-sweep
        // consumer (a hypothetical `Sexp::COMMENT_DELIMITERS[0]` opener
        // lookup, an LSP span-highlighter that renders the (opener,
        // terminator) span as-is, the metric label-set generator that
        // walks the array). Sibling-shape pin to
        // `sexp_list_delimiters_composes_from_algebra_constants_in_declaration_order`
        // on the outer-structural axis; both close the (opener,
        // closer_or_terminator) pair contract at ONE typed ALL array.
        assert_eq!(
            Sexp::COMMENT_DELIMITERS,
            [Sexp::COMMENT_LEAD, Sexp::COMMENT_TERM],
            "COMMENT_DELIMITERS composition drifted from the canonical \
             (COMMENT_LEAD, COMMENT_TERM) pair — the paired-discard \
             sub-vocabulary lift must route through the two typed \
             algebra constants in that order.",
        );
    }

    #[test]
    fn sexp_comment_delimiters_has_expected_cardinality() {
        // CARDINALITY PIN: `[char; 2]` at rustc — this assert pins the
        // runtime observable so a refactor that loosens the array's
        // type to `&[char]` (dropping the compile-time arity forcing)
        // fails HERE at the runtime cardinality assertion rather than
        // silently allowing a third or absent row. Sibling-shape pin
        // to `sexp_list_delimiters_has_expected_cardinality` on the
        // outer-structural axis.
        assert_eq!(
            Sexp::COMMENT_DELIMITERS.len(),
            2,
            "COMMENT_DELIMITERS cardinality drifted from 2 — the paired \
             (opener, terminator) reader-discard sub-vocabulary MUST be \
             exactly two rows.",
        );
    }

    #[test]
    fn sexp_comment_delimiters_pairwise_distinct() {
        // PAIRWISE DISJOINTNESS: the two paired reader-discard rows
        // MUST NOT alias (a hypothetical degenerate `;` opener + `;`
        // terminator convention would collapse the paired-delimiter
        // contract — the discard loop's terminator check `ch ==
        // Sexp::COMMENT_TERM` inside a run led by `Sexp::COMMENT_LEAD`
        // would fire on the very byte that opened the run, breaking
        // the loop after zero characters and leaving the actual comment
        // body in the token stream). Sibling-shape pin to
        // `sexp_list_delimiters_pairwise_distinct` on the outer-
        // structural axis; both close the pairwise-distinctness
        // contract at the ALL-array level rather than at an inline
        // `assert_ne!(LEAD, TERM)` per consumer.
        for (i, a) in Sexp::COMMENT_DELIMITERS.iter().enumerate() {
            for (j, b) in Sexp::COMMENT_DELIMITERS.iter().enumerate() {
                if i == j {
                    continue;
                }
                assert_ne!(
                    a, b,
                    "COMMENT_DELIMITERS rows [{i}] and [{j}] share a byte \
                     ({a:?} == {b:?}) — the paired-discard contract \
                     would collapse.",
                );
            }
        }
    }

    #[test]
    fn sexp_comment_delimiters_lead_row_is_bare_atom_boundary() {
        // PATH-UNIFORMITY PIN (LEAD row, non-whitespace): the [0] row
        // (`Sexp::COMMENT_LEAD`, `;`) MUST classify as a bare-atom
        // boundary via `Sexp::is_bare_atom_boundary` — the reader's
        // outer-dispatch cascade has a DEDICATED line-comment arm
        // keyed on this byte, so the projection's disjunction
        // enumerates it. A regression that dropped the LEAD from
        // `is_bare_atom_boundary`'s disjunction OR that pointed
        // `COMMENT_DELIMITERS[0]` at a byte the projection doesn't
        // recognize as a boundary fails HERE rather than at a distant
        // tokenize-round-trip. Sibling-shape pin to
        // `sexp_is_bare_atom_boundary_routes_through_list_delimiters_for_every_row`
        // — the LIST_DELIMITERS peer sweeps BOTH rows through the
        // predicate; this pin sweeps ONLY the LEAD row (index 0),
        // because the TERM row (index 1) classifies through the
        // whitespace-family axis, NOT the bare-atom-boundary predicate
        // directly.
        assert!(
            Sexp::is_bare_atom_boundary(Sexp::COMMENT_DELIMITERS[0]),
            "COMMENT_DELIMITERS[0] ({:?}) does NOT classify as a \
             bare-atom boundary via Sexp::is_bare_atom_boundary — the \
             reader-discard opener row drifted from the reader's \
             outer-dispatch arm-set.",
            Sexp::COMMENT_DELIMITERS[0],
        );
    }

    #[test]
    fn sexp_comment_delimiters_term_row_is_whitespace_family_char() {
        // PATH-UNIFORMITY PIN (TERM row, whitespace): the [1] row
        // (`Sexp::COMMENT_TERM`, `'\n'`) MUST classify as a whitespace
        // char via `char::is_whitespace` — the reader's line-comment
        // discard loop consumes bytes up to and including the FIRST
        // COMMENT_TERM, then hands control back to the outer-dispatch's
        // `ws if ws.is_whitespace()` arm which absorbs any lingering
        // COMMENT_TERM byte cleanly. A regression that repointed
        // `COMMENT_DELIMITERS[1]` at a NON-whitespace byte (e.g. a `#`
        // reader-macro-lead) would break the post-discard hand-off:
        // the reader would either loop indefinitely on the byte or
        // silently tokenize it into the next Token::Atom. Pinning the
        // whitespace-family membership at the array's TERM row keeps
        // the outer-dispatch's cascading arm-set structurally coherent
        // through the ALL array. Sibling-shape pin to
        // `sexp_comment_term_is_whitespace_family_char` above; that
        // pin binds the whitespace-family membership to the
        // `Self::COMMENT_TERM` constant directly, this pin binds it to
        // the ALL array's [1] row so any override of the TERM row via
        // a refactored `pub const` misalignment surfaces HERE too.
        assert!(
            Sexp::COMMENT_DELIMITERS[1].is_whitespace(),
            "COMMENT_DELIMITERS[1] ({:?}) does NOT classify as a \
             whitespace char via char::is_whitespace — the reader's \
             line-comment discard loop's post-loop hand-off to the \
             outer-dispatch's whitespace arm would break at the \
             non-whitespace terminator.",
            Sexp::COMMENT_DELIMITERS[1],
        );
    }

    #[test]
    fn sexp_comment_delimiters_disjoint_from_list_delimiters() {
        // CROSS-AXIS DISJOINTNESS (same-algebra): no row of
        // `COMMENT_DELIMITERS` may alias any row of
        // `LIST_DELIMITERS` — the reader-discard axis and the
        // outer-structural list-delimiter axis partition their
        // respective bytes disjointly on the SAME closed-set outer
        // [`Sexp`] algebra. Otherwise the reader's dedicated line-
        // comment arm would collide with the `Token::LParen` /
        // `Token::RParen` arms at the same byte, silently reclassifying
        // a bare `(` or `)` as a comment lead or vice versa. Sibling-
        // shape pin to `sexp_list_delimiters_disjoint_from_comment_lead`
        // above (the outer-structural axis's mirror pin against the
        // LEAD row); this pin closes the FULL 2×2 cross-axis
        // disjointness contract rather than only the LEAD row against
        // both LIST rows.
        for (i, ch) in Sexp::COMMENT_DELIMITERS.iter().enumerate() {
            for (j, other) in Sexp::LIST_DELIMITERS.iter().enumerate() {
                assert_ne!(
                    *ch, *other,
                    "COMMENT_DELIMITERS[{i}] ({ch:?}) aliases \
                     LIST_DELIMITERS[{j}] ({other:?}) — the reader- \
                     discard axis and the outer-structural list- \
                     delimiter axis share a byte, silently reclassifying \
                     the shared byte at the reader's outer dispatch.",
                );
            }
        }
    }

    #[test]
    fn sexp_comment_delimiters_disjoint_from_str_delimiter() {
        // CROSS-ALGEBRA DISJOINTNESS (Str-delimiter): no row of
        // `COMMENT_DELIMITERS` may alias `Atom::STR_DELIMITER` —
        // otherwise the reader's line-comment discard arm would
        // collide with `Token::Str`'s opener/closer arm at the same
        // byte. The disjointness contract binds ACROSS the two closed-
        // set algebras (outer [`Sexp`] discard vocabulary vs. inner
        // [`Atom`] Str-payload vocabulary), matching the sibling-shape
        // pin `sexp_list_delimiters_disjoint_from_str_delimiter` on
        // the outer-structural axis of the SAME [`Sexp`] algebra.
        for (i, ch) in Sexp::COMMENT_DELIMITERS.iter().enumerate() {
            assert_ne!(
                *ch,
                Atom::STR_DELIMITER,
                "COMMENT_DELIMITERS[{i}] ({ch:?}) aliases \
                 Atom::STR_DELIMITER ({:?}) — the reader's line- \
                 comment discard arm would collide with the Str-payload \
                 delimiter arm at the same byte across the two closed- \
                 set algebras.",
                Atom::STR_DELIMITER,
            );
        }
    }

    // ── `Sexp::is_bare_atom_boundary` — the ONE typed projection on the
    // outer [`Sexp`] algebra that names the SIX-fold outer-dispatch
    // category-leading char disjunction. The exhaustive pin below
    // anchors each of the six categories AS a positive arm AND the
    // load-bearing substrate marker LEAD bytes (`:` / `#` / `@`) AS
    // negative arms — the three lead bytes are first-char classifiers
    // for bare-atom payload families (Keyword / Bool / splice second-
    // char), NOT outer-dispatch category-leading chars, and a
    // regression that promoted any to a boundary would break their
    // tokenization. The composition end-to-end pin (in reader tests)
    // sweeps every boundary char through the bare-atom accumulator and
    // asserts the atom terminates at exactly the boundary byte.

    #[test]
    fn sexp_is_bare_atom_boundary_matches_outer_dispatch_arm_set_exhaustively() {
        // OUTER-DISPATCH COHERENCE PIN: the SIX outer-dispatch category-
        // leading char families the reader's tokenizer specialises on
        // MUST ALL classify as boundaries; no other char (bare-atom
        // chars) may classify as one. This test enumerates the FULL
        // outer-dispatch arm-set as a typed table AND sweeps a
        // representative negative set, asserting the projection's
        // predicate matches the outer-dispatch's specific-arm firing
        // exactly. A refactor that added a SEVENTH outer-dispatch arm
        // (e.g. `#|…|#` block-comment) to the reader without extending
        // the projection's disjunction would fail HERE at the coherence
        // sweep: the new lead byte would EITHER be a boundary the
        // projection missed (test asserts positive, projection returns
        // false → panic) OR a bare-atom char the reader stole from the
        // default arm (silent tokenizer drift the projection doesn't
        // catch). Either way the coherence pin catches the drift and
        // forces the projection + outer-dispatch to stay in lockstep.
        let positive_arms: Vec<(char, String)> = {
            let mut arms: Vec<(char, String)> = vec![
                (' ', "whitespace".to_string()),
                ('\t', "whitespace-tab".to_string()),
                ('\n', "whitespace-newline".to_string()),
                (Sexp::LIST_OPEN, "LIST_OPEN".to_string()),
                (Sexp::LIST_CLOSE, "LIST_CLOSE".to_string()),
                (Atom::STR_DELIMITER, "STR_DELIMITER".to_string()),
                (Sexp::COMMENT_LEAD, "COMMENT_LEAD".to_string()),
            ];
            for qf in QuoteForm::ALL {
                arms.push((qf.lead_char(), format!("QuoteForm::{qf:?}")));
            }
            arms
        };
        for (ch, name) in &positive_arms {
            assert!(
                Sexp::is_bare_atom_boundary(*ch),
                "outer-dispatch arm `{name}` (`{ch:?}`) must classify as \
                 a boundary — the projection missed a category the \
                 reader's outer-dispatch specialises on",
            );
        }
        // Negative sweep: every char below MUST fall through to the
        // default bare-atom arm. Includes typical alpha, digit, and
        // sign chars AND the three load-bearing substrate marker LEAD
        // bytes (`:` / `#` / `@`) that are first-char classifiers for
        // bare-atom payload families rather than outer-dispatch
        // categories.
        let negative_arms: &[char] = &[
            'a',
            'z',
            'A',
            'Z',
            '0',
            '9',
            '-',
            '+',
            '_',
            '.',
            '=',
            '<',
            '>',
            '!',
            '?',
            '/',
            '*',
            '%',
            '&',
            '|',
            '^',
            '~',
            // The `KEYWORD_MARKER` prefix's lead byte lives at the
            // typed `Atom::KEYWORD_MARKER_LEAD` constant on the closed-
            // set outer [`Atom`] algebra. Pre-lift this slot held an
            // inline `Atom::KEYWORD_MARKER.chars().next().unwrap()`
            // chain extracting the byte from the `&'static str`
            // projection; post-lift the byte lives at ONE named
            // constant the `&'static str` projects to (pinned by
            // `atom_keyword_marker_lead_prefixes_keyword_marker`).
            Atom::KEYWORD_MARKER_LEAD,
            // The bool_literal spellings' shared lead byte lives at
            // the typed `Atom::BOOL_LITERAL_LEAD` constant on the
            // closed-set outer [`Atom`] algebra. Pre-lift this slot
            // held an inline `Atom::bool_literal(true).chars().next()
            // .unwrap()` chain extracting the byte from ONE spelling;
            // post-lift the byte lives at ONE named constant that
            // BOTH spellings project through (pinned by
            // `atom_bool_literal_lead_prefixes_every_bool_literal_spelling`).
            Atom::BOOL_LITERAL_LEAD,
            QuoteForm::SPLICE_DISCRIMINATOR,
        ];
        for ch in negative_arms {
            assert!(
                !Sexp::is_bare_atom_boundary(*ch),
                "bare-atom char {ch:?} must NOT classify as a boundary — \
                 the reader's outer-dispatch has NO specific arm on this \
                 byte; the default bare-atom arm must accept it",
            );
        }
    }

    #[test]
    fn sexp_non_whitespace_bare_atom_terminators_has_expected_cardinality() {
        // Cardinality contract: `Self::NON_WHITESPACE_BARE_ATOM_TERMINATORS.len()
        // == 7` — pinned at the declaration site by rustc's forced-arity
        // check on `[char; 7]`. This test surfaces the arity as a fail-
        // loud runtime pin so a future refactor that switches the array
        // type to `&[char]` (dropping the compile-time arity forcing)
        // doesn't silently loosen the closed-set discipline the family
        // relies on. The seven arms are the FULL non-whitespace category-
        // leading char set the reader's outer-dispatch specialises on
        // (two structural `Sexp::LIST_{OPEN,CLOSE}`, three
        // `QuoteForm::{QUOTE,QUASIQUOTE,UNQUOTE}_LEAD`, one
        // `Atom::STR_DELIMITER`, one `Sexp::COMMENT_LEAD`). Sibling
        // posture to `sexp_list_delimiters_has_expected_cardinality`
        // and `sexp_comment_delimiters_has_expected_cardinality` on the
        // paired-role sub-arrays of the SAME closed set.
        assert_eq!(
            Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS.len(),
            7,
            "Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS cardinality \
             drifted from 7 — the reader's outer-dispatch specialises \
             on exactly seven non-whitespace category-leading chars by \
             construction; an extension surfaces here"
        );
    }

    #[test]
    fn sexp_non_whitespace_bare_atom_terminators_route_through_typed_sub_algebra_constants() {
        // PATH-UNIFORMITY (family-wide ARRAY-side): the seven entries
        // of `Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS` MUST bind
        // byte-for-byte to the seven typed sub-algebra `pub const`
        // primitives — no inline `char` literals. Catches a regression
        // that inlines `['(', ')', '\'', '`', ',', '"', ';']`: both
        // the alignment property AND the numeric bytes would still
        // hold, but the algebra-provenance would disappear, so a
        // future rename (e.g. `Sexp::LIST_OPEN → Sexp::PAREN_OPEN`,
        // `Sexp::COMMENT_LEAD → Sexp::LINE_COMMENT_OPEN`) at any of
        // the three sibling algebras would silently drift the array's
        // provenance from the algebra's canonical spelling. Sibling
        // posture to the `LIST_DELIMITERS` / `COMMENT_DELIMITERS`
        // ARRAY-side provenance pins on the paired-role sub-arrays,
        // AND to the shape-level HASH_DISCRIMINATORS ARRAY-side
        // provenance pin
        // `sexp_shape_hash_discriminators_align_with_typed_per_role_constants_by_index`
        // on the outer-`Sexp` cache-key axis.
        assert_eq!(
            Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS[0],
            Sexp::LIST_OPEN
        );
        assert_eq!(
            Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS[1],
            Sexp::LIST_CLOSE
        );
        assert_eq!(
            Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS[2],
            QuoteForm::QUOTE_LEAD,
        );
        assert_eq!(
            Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS[3],
            QuoteForm::QUASIQUOTE_LEAD,
        );
        assert_eq!(
            Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS[4],
            QuoteForm::UNQUOTE_LEAD,
        );
        assert_eq!(
            Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS[5],
            Atom::STR_DELIMITER,
        );
        assert_eq!(
            Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS[6],
            Sexp::COMMENT_LEAD,
        );
    }

    #[test]
    fn sexp_non_whitespace_bare_atom_terminators_are_pairwise_distinct() {
        // INJECTIVITY CONTRACT: the seven entries of
        // `Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS` MUST be pairwise
        // distinct — no char appears twice across the (structural,
        // quote-family, atomic-delimiter, comment-lead) sub-vocabularies.
        // A silent collision (e.g. a hypothetical Racket-compat port
        // moving `QuoteForm::QUOTE_LEAD` from `'\''` to `';'` conflating
        // it with `Sexp::COMMENT_LEAD`, or a future block-comment
        // extension re-using `Atom::STR_DELIMITER`) would break the
        // reader's outer-dispatch's implicit "each specific arm fires
        // on a DISTINCT lead char" contract — the `match c { … }`
        // outer-dispatch in `crate::reader::tokenize` cannot admit
        // duplicate patterns without breaking exhaustiveness. This pin
        // surfaces the distinctness as a substrate-level structural
        // theorem so a cross-algebra rename that flips the injectivity
        // is a compile-time-verified regression at the sub-carving
        // level (rustc-forbidden duplicate `match` patterns) AND a
        // runtime fail-loud regression here.
        let mut seen: std::collections::HashSet<char> = std::collections::HashSet::new();
        for ch in Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS {
            assert!(
                seen.insert(ch),
                "Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS carries a \
                 duplicate char {ch:?} — the reader's outer-dispatch \
                 arms MUST be pairwise disjoint by construction",
            );
        }
        assert_eq!(seen.len(), Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS.len(),);
    }

    #[test]
    fn sexp_is_bare_atom_boundary_agrees_with_terminators_array_on_non_whitespace_partition() {
        // BOUNDARY-PREDICATE COMPOSITION LAW: for every char `ch`,
        // `Sexp::is_bare_atom_boundary(ch) == (ch.is_whitespace() ||
        // Self::NON_WHITESPACE_BARE_ATOM_TERMINATORS.contains(&ch))`.
        // Pins the ARRAY-driven refactor of the boundary predicate
        // against a regression that reverts the disjunction to the
        // pre-lift three-part sub-expression composition (or drifts
        // ONE sub-expression's arm silently). Sibling posture to
        // `sexp_is_bare_atom_boundary_matches_outer_dispatch_arm_set_exhaustively`
        // — that pin binds the boundary predicate's TRUTH-TABLE against
        // the reader's outer-dispatch categories; this pin binds the
        // boundary predicate's DEFINITION against the family-wide
        // terminators ARRAY as the sole non-whitespace clause. The
        // (positive, negative) sweep covers a whitespace char + the
        // seven terminator entries as positives, and a representative
        // negative set (alpha, digit, sign, and the three substrate
        // marker LEADs `:` / `#` / `@`) as negatives.
        for &ch in &Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS {
            assert!(
                Sexp::is_bare_atom_boundary(ch),
                "Sexp::is_bare_atom_boundary({ch:?}) must return true \
                 for every char in NON_WHITESPACE_BARE_ATOM_TERMINATORS",
            );
        }
        assert!(Sexp::is_bare_atom_boundary(' '));
        assert!(Sexp::is_bare_atom_boundary('\t'));
        assert!(Sexp::is_bare_atom_boundary('\n'));
        for ch in ['a', 'Z', '0', '9', '-', '_', ':', '#', '@'] {
            let expected =
                ch.is_whitespace() || Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS.contains(&ch);
            assert_eq!(
                Sexp::is_bare_atom_boundary(ch),
                expected,
                "Sexp::is_bare_atom_boundary({ch:?}) drifted from the \
                 ARRAY-driven composition law",
            );
        }
    }

    // ── `assert_char_array_pairwise_distinct` — the const-fn compile-
    // time pairwise-distinctness contract lifter. Sibling posture to
    // the runtime `_pairwise_distinct` tests: those pin the property
    // at test-run time on each individual array; these pins bind the
    // lift's OWN contract (accept-distinct, reject-collision, runtime-
    // callability, cross-array coverage) so a regression that silently
    // weakens the helper (e.g. flipping `!=` to `==`, dropping the
    // inner `j` loop, or returning early on collision) is caught by
    // the helper's OWN test surface rather than only surfacing as a
    // false-positive on some future array's distinctness pin.

    #[test]
    fn assert_char_array_pairwise_distinct_accepts_the_empty_array() {
        // Empty array — vacuously pairwise distinct (no pair to
        // collide). The compile-time `const _: () = assert_char_array_
        // pairwise_distinct(&EMPTY);` would land on this arm, so the
        // runtime call MUST return normally.
        assert_char_array_pairwise_distinct::<0>(&[]);
    }

    #[test]
    fn assert_char_array_pairwise_distinct_accepts_singleton_arrays() {
        // Singleton array — vacuously pairwise distinct (only one
        // element, no pair). Cross-arity coverage on the `[char; 1]`
        // corner of the const-N generic.
        assert_char_array_pairwise_distinct(&['a']);
        assert_char_array_pairwise_distinct(&[Sexp::LIST_OPEN]);
    }

    #[test]
    fn assert_char_array_pairwise_distinct_accepts_every_family_wide_substrate_array() {
        // Runtime cross-check that the SAME seven arrays the module-
        // level `const _: () = ...` witnesses cover at COMPILE time
        // are pairwise distinct. 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 collision at `cargo test`. The
        // pair enforces the theorem at TWO stages of the toolchain.
        assert_char_array_pairwise_distinct(&Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS);
        assert_char_array_pairwise_distinct(&Sexp::LIST_DELIMITERS);
        assert_char_array_pairwise_distinct(&Sexp::COMMENT_DELIMITERS);
        assert_char_array_pairwise_distinct(&QuoteForm::LEADS);
        assert_char_array_pairwise_distinct(&Atom::SELF_ESCAPE_TABLE);
        assert_char_array_pairwise_distinct(&Atom::ESCAPE_SOURCES);
        assert_char_array_pairwise_distinct(&Atom::ESCAPE_DECODED);
    }

    #[test]
    #[should_panic(expected = "assert_char_array_pairwise_distinct")]
    fn assert_char_array_pairwise_distinct_panics_at_runtime_on_binary_collision() {
        // NEGATIVE PIN — binary corner: a two-element array carrying
        // the same char twice MUST panic at runtime (the const-eval
        // panic surfaces normally when the function is invoked from
        // a runtime context, not just a `const _` context). Pins the
        // helper's OWN reject-collision arm — a regression that
        // silently returns without panicking on a duplicate would
        // slip through the compile-time witnesses' failure mode too.
        assert_char_array_pairwise_distinct(&['x', 'x']);
    }

    #[test]
    #[should_panic(expected = "assert_char_array_pairwise_distinct")]
    fn assert_char_array_pairwise_distinct_panics_at_runtime_on_non_adjacent_collision() {
        // NEGATIVE PIN — non-adjacent corner: the collision fires on
        // ANY (i, j) pair with i < j, not just the adjacent (0, 1)
        // corner. Pins the nested-loop shape of the helper — a
        // regression that walked ONLY the adjacent pairs (i.e., swept
        // `while i + 1 < N { if arr[i] == arr[i+1] { panic } … }`)
        // would silently accept `['a', 'b', 'a']` (non-adjacent
        // collision at positions 0 and 2), missing the contract.
        assert_char_array_pairwise_distinct(&['a', 'b', 'a']);
    }

    #[test]
    #[should_panic(expected = "assert_char_array_pairwise_distinct")]
    fn assert_char_array_pairwise_distinct_panics_at_runtime_on_terminal_collision() {
        // NEGATIVE PIN — terminal corner: the collision at the LAST
        // pair (positions N-2 and N-1) MUST also fire. Pins the outer
        // `while i < N` bound — a regression that walked `while i <
        // N - 1` (dropping the last row) would silently accept a
        // collision at the tail.
        assert_char_array_pairwise_distinct(&['a', 'b', 'c', 'd', 'd']);
    }

    #[test]
    fn assert_char_array_pairwise_distinct_panic_message_names_the_helper() {
        // PANIC-MESSAGE PROVENANCE PIN: the panic message MUST begin
        // with the helper's own name so downstream diagnostics
        // (`cargo check` const-eval error output, test-suite failure
        // reports) route the drift back to the helper by string
        // search — the family-wide contract's failure mode surfaces
        // as an identifiable panic-message prefix rather than as an
        // opaque const-eval error. Sibling posture to the runtime
        // pairwise-distinctness tests that name the ARRAY in their
        // failure message; this pin names the HELPER.
        let outcome = std::panic::catch_unwind(|| {
            assert_char_array_pairwise_distinct(&['x', 'x']);
        });
        let payload = outcome.expect_err(
            "assert_char_array_pairwise_distinct must panic on a \
             duplicate — the reject-collision arm is the point of the \
             helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_array_pairwise_distinct panic payload \
                 must be a static &str or String",
            );
        assert!(
            msg.contains("assert_char_array_pairwise_distinct"),
            "assert_char_array_pairwise_distinct panic message \
             {msg:?} must name the helper for provenance-preserving \
             failure diagnostics",
        );
    }

    // ── assert_char_array_all_ascii — the per-entry ASCII-SCALAR-RANGE
    // gate row-dual peer of `assert_str_array_all_ascii` on the
    // (element-type ∈ {char, `&'static str`}) axis of the (per-entry ×
    // contract-shape) matrix at the (per-entry, ASCII) column. Contract-
    // orthogonal sibling of `assert_char_array_pairwise_distinct` on
    // the (INJECTIVITY, ASCII) axis of the SAME (`char`) row. ──

    #[test]
    fn assert_char_array_all_ascii_accepts_the_empty_array() {
        // Empty array — vacuously all-ASCII (no entry to fail the
        // scalar-range gate). The compile-time `const _: () =
        // assert_char_array_all_ascii(&EMPTY);` would land on this
        // arm, so the runtime call MUST return normally. Sibling
        // posture to `assert_str_array_all_ascii_accepts_the_empty_
        // array` on the (`&'static str`) row-dual ASCII helper — the
        // two share the trivial-arity arm across the element-type
        // column.
        assert_char_array_all_ascii::<0>(&[]);
    }

    #[test]
    fn assert_char_array_all_ascii_accepts_ascii_singleton_arrays() {
        // Singleton array carrying an all-ASCII entry — the sole
        // entry clears the scalar-range gate. Cross-arity coverage
        // on the `[char; 1]` corner of the const-N generic. Includes
        // a substrate-scalar entry (`Sexp::LIST_OPEN`) to cover the
        // named-constant projection alongside the char literal
        // projection.
        assert_char_array_all_ascii(&['a']);
        assert_char_array_all_ascii(&[Sexp::LIST_OPEN]);
    }

    #[test]
    fn assert_char_array_all_ascii_accepts_every_family_wide_substrate_array() {
        // Runtime cross-check that the SAME seven arrays the module-
        // level `const _: () = ...` witnesses cover at COMPILE time
        // are all-ASCII. Sibling posture to the runtime
        // `_pairwise_distinct_accepts_every_family_wide_substrate_
        // array` cross-check — the two together pin BOTH the SET-
        // LEVEL INJECTIVITY axis AND the PER-ENTRY ASCII-SCALAR-RANGE
        // axis on the SAME seven arrays, at TWO stages of the
        // toolchain (compile-time `const _` line + this runtime
        // safety-net). Row-dual posture to
        // `assert_str_array_all_ascii_accepts_every_family_wide_
        // substrate_array` on the (`&'static str`) row — the two
        // together sweep the ASCII contract across every reader-
        // boundary AND every outer-algebra vocabulary the substrate
        // ships.
        assert_char_array_all_ascii(&Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS);
        assert_char_array_all_ascii(&Sexp::LIST_DELIMITERS);
        assert_char_array_all_ascii(&Sexp::COMMENT_DELIMITERS);
        assert_char_array_all_ascii(&QuoteForm::LEADS);
        assert_char_array_all_ascii(&Atom::SELF_ESCAPE_TABLE);
        assert_char_array_all_ascii(&Atom::ESCAPE_SOURCES);
        assert_char_array_all_ascii(&Atom::ESCAPE_DECODED);
    }

    #[test]
    fn assert_char_array_all_ascii_accepts_the_ascii_boundary_scalar() {
        // Boundary-inclusive pin on the ASCII scalar range's upper
        // edge — U+007F (DEL, the last ASCII scalar) MUST be
        // accepted. Guards against an off-by-one regression that
        // walked `arr[i] as u32 >= 0x7F` and spuriously rejected the
        // sole `'\u{7F}'` character. Together with the negative pins
        // below (which fire on U+0080 — the first non-ASCII scalar),
        // the two pin the scalar-range boundary at both edges.
        assert_char_array_all_ascii(&['\u{7F}']);
    }

    #[test]
    #[should_panic(expected = "assert_char_array_all_ascii")]
    fn assert_char_array_all_ascii_panics_at_runtime_on_singleton_non_ascii() {
        // NEGATIVE PIN — singleton corner: a one-element array
        // carrying a non-ASCII scalar MUST panic. Pins the helper's
        // own reject-non-ascii arm on the smallest possible array
        // shape. The scalar `'é'` (U+00E9) has `as u32 == 0xE9 >
        // 0x7F` and fires the range gate.
        assert_char_array_all_ascii(&['é']);
    }

    #[test]
    #[should_panic(expected = "assert_char_array_all_ascii")]
    fn assert_char_array_all_ascii_panics_at_runtime_on_head_non_ascii() {
        // NEGATIVE PIN — head corner: the non-ASCII scalar at
        // position 0 MUST fire even when subsequent entries are
        // ASCII. Pins the sweep's inclusive-start behavior — a
        // regression that walked `while i < N { … i += 1 }` from
        // an off-by-one start (`i = 1`) would silently accept a
        // leading non-ASCII entry.
        assert_char_array_all_ascii(&['é', 'a', 'b']);
    }

    #[test]
    #[should_panic(expected = "assert_char_array_all_ascii")]
    fn assert_char_array_all_ascii_panics_at_runtime_on_interior_non_ascii() {
        // NEGATIVE PIN — interior corner: the non-ASCII scalar at a
        // strictly-interior position MUST fire. Pins the sweep's
        // non-early-exit behavior at the head-arm — a regression
        // that returned `Ok` on the first ASCII entry (bailing out
        // of the sweep prematurely) would silently accept an
        // interior non-ASCII entry.
        assert_char_array_all_ascii(&['a', 'é', 'b']);
    }

    #[test]
    #[should_panic(expected = "assert_char_array_all_ascii")]
    fn assert_char_array_all_ascii_panics_at_runtime_on_tail_non_ascii() {
        // NEGATIVE PIN — tail corner: the non-ASCII scalar at
        // position `N - 1` MUST fire. Pins the outer `while i < N`
        // upper bound — a regression that walked `while i < N - 1`
        // (dropping the last slot) would silently accept a trailing
        // non-ASCII entry.
        assert_char_array_all_ascii(&['a', 'b', 'c', 'é']);
    }

    #[test]
    #[should_panic(expected = "assert_char_array_all_ascii")]
    fn assert_char_array_all_ascii_panics_on_the_first_non_ascii_scalar() {
        // NEGATIVE PIN — first-non-ASCII-scalar boundary: U+0080
        // (the smallest non-ASCII scalar) MUST fire. Guards against
        // an off-by-one regression that walked `arr[i] as u32 >
        // 0x80` (dropping U+0080 from the reject set). Together
        // with `_accepts_the_ascii_boundary_scalar` (which pins
        // U+007F acceptance), the two pin the scalar-range boundary
        // at both edges. Row-dual posture to `assert_str_array_all_
        // ascii_panics_on_the_first_non_ascii_byte` — the two
        // together pin the boundary at both element-type projections.
        assert_char_array_all_ascii(&['\u{80}']);
    }

    #[test]
    fn assert_char_array_all_ascii_rejects_the_all_non_ascii_array() {
        // POSITIVE-ORTHOGONAL PIN — the ALL-non-ASCII corner: an
        // array whose every entry is a non-ASCII scalar fires the
        // helper on the FIRST entry (the head-arm). Confirms the
        // helper does not silently accept an array whose every
        // entry ships non-ASCII scalars. Row-dual posture to
        // `assert_str_array_all_ascii_rejects_the_all_non_ascii_
        // array` on the (`&'static str`) row — the two together pin
        // the all-reject corner across the element-type column.
        let outcome = std::panic::catch_unwind(|| {
            assert_char_array_all_ascii(&['é', 'ü']);
        });
        outcome.expect_err(
            "assert_char_array_all_ascii must panic on an array \
             whose every entry is a non-ASCII scalar — the head-arm \
             fires on the first non-ASCII scalar at position 0",
        );
    }

    #[test]
    fn assert_char_array_all_ascii_panic_message_names_the_helper_and_axis() {
        // PANIC-MESSAGE PROVENANCE PIN: the panic message MUST
        // begin with the helper's own name AND name the failed axis
        // as `"CHAR-NON-ASCII-SCALAR"` (chosen DISTINCT from every
        // sibling helper's axis vocabulary: `"duplicate"` on the
        // pairwise-distinct sibling; `"CHAR-SUBSET-VIOLATION"` on
        // the within-finite-set sibling; `"CHAR-DISJOINTNESS-
        // VIOLATION"` on the arrays-disjoint sibling; `"STR-NON-
        // ASCII-ENTRY"` on the (`&'static str`) row-dual ASCII
        // sibling) so a diagnostic that names the failed axis routes
        // UNAMBIGUOUSLY to THIS specific (`char`)-row ASCII helper.
        // The `"CHAR-"` prefix disambiguates from the (`&'static
        // str`) row-dual ASCII sibling; the shared `"-NON-ASCII-"`
        // infix lets callers grep any row's ASCII sibling by `"NON-
        // ASCII"` alone.
        let outcome = std::panic::catch_unwind(|| {
            assert_char_array_all_ascii(&['é']);
        });
        let payload = outcome.expect_err(
            "assert_char_array_all_ascii must panic on a non-ASCII \
             scalar — the reject-non-ascii arm is the point of the \
             helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_array_all_ascii panic payload must be \
                 a static &str or String",
            );
        assert!(
            msg.contains("assert_char_array_all_ascii"),
            "assert_char_array_all_ascii panic message {msg:?} must \
             name the helper for provenance-preserving failure \
             diagnostics",
        );
        assert!(
            msg.contains("CHAR-NON-ASCII-SCALAR"),
            "assert_char_array_all_ascii panic message {msg:?} must \
             name the failed axis as `CHAR-NON-ASCII-SCALAR` \
             DISTINCT from every sibling helper's axis vocabulary",
        );
        assert!(
            !msg.contains("STR-NON-ASCII-ENTRY"),
            "assert_char_array_all_ascii panic message {msg:?} must \
             NOT name the (`&'static str`) row-dual sibling's axis \
             — the two row-dual ASCII helpers must keep their axis-\
             provenance strings lexically distinct on the element-\
             type column",
        );
        assert!(
            !msg.contains("CHAR-SUBSET-VIOLATION"),
            "assert_char_array_all_ascii panic message {msg:?} must \
             NOT name the SUBSET-embedding sibling's axis — the \
             per-entry ASCII helper and the SUBSET-embedding helper \
             must keep their axis-provenance strings lexically \
             distinct on the contract-shape column",
        );
    }

    // ── `assert_char_array_within_char_finite_set` — the char-element
    // SUBSET-EMBEDDING verifier that binds `arr ⊆ set` at compile time
    // on the reader-boundary `char` vocabulary, peer to the (u8) row's
    // `assert_u8_array_within_u8_finite_set` on the (element-type ×
    // contract-shape) matrix. The runtime test surface pins each of
    // the helper's arms (accept-empty, accept-singleton-in-set,
    // accept-arr-equals-set, accept-each-family-wide-substrate-subset,
    // accept-array-duplicates-in-set, reject-single-out-of-set-entry,
    // reject-terminal-out-of-set-entry, panic-message-provenance on
    // the CHAR-SUBSET-VIOLATION axis, negative pin on the DELEGATED
    // SET-side well-formedness arm) so a regression that silently
    // weakened the helper on ANY arm is caught by the helper's OWN
    // test surface rather than only surfacing as a false-positive on
    // some future subset-embedded `[char; N]` array's compound pin.

    #[test]
    fn assert_char_array_within_char_finite_set_accepts_the_empty_array_within_any_set() {
        // Empty array `arr = []` at the `[char; 0]` corner — vacuously
        // a subset of every set (no `i` position exists to test).
        // Cross-arity coverage on the trivial ARRAY corner of the
        // const-N generic across three witness-set widths (empty,
        // singleton, multi-element) to pin the helper's OUTER-sweep
        // arm across the whole (`N == 0` × `M`) axis. Turbofish
        // binding required because there's no other cue for the const
        // parameters on the empty array literal. Sibling posture to
        // `assert_u8_array_within_u8_finite_set_accepts_the_empty_array_within_any_set`
        // on the (u8) row's SUBSET-EMBEDDING helper — the two share
        // the trivial-arity arm across the element-type column.
        assert_char_array_within_char_finite_set::<0, 0>(&[], &[]);
        assert_char_array_within_char_finite_set::<0, 1>(&[], &['x']);
        assert_char_array_within_char_finite_set::<0, 3>(&[], &['a', 'b', 'c']);
    }

    #[test]
    fn assert_char_array_within_char_finite_set_accepts_singleton_array_when_char_in_set() {
        // Singleton array `arr = [K]` at the `[char; 1]` corner MUST
        // pass when `K ∈ set`. Cross-position coverage: the char can
        // sit at the FIRST, MIDDLE, or LAST position of the `set` —
        // pins the INNER `while j < M` sweep terminates at the first-
        // match position rather than always at position `0` OR always
        // at position `M - 1`. A regression that narrowed the inner
        // sweep to `j == 0` would silently reject singleton arrays
        // hitting non-first set positions.
        assert_char_array_within_char_finite_set::<1, 3>(&['a'], &['a', 'b', 'c']);
        assert_char_array_within_char_finite_set::<1, 3>(&['b'], &['a', 'b', 'c']);
        assert_char_array_within_char_finite_set::<1, 3>(&['c'], &['a', 'b', 'c']);
    }

    #[test]
    fn assert_char_array_within_char_finite_set_accepts_arr_equals_set() {
        // Boundary corner where `arr` and `set` cover byte-for-byte
        // identical distinct-value sets — the SUBSET relation
        // degenerates to EQUALITY. Pins that the helper does NOT
        // gratuitously require the SUBSET to be PROPER (strict):
        // equal-multisets pass the SUBSET check. Sibling posture to
        // `assert_u8_array_within_u8_finite_set_accepts_arr_equals_set`
        // on the (u8) row's SUBSET-EMBEDDING helper — the two share
        // the EQUAL-SETS corner across the element-type column.
        assert_char_array_within_char_finite_set(&['a', 'b'], &['a', 'b']);
        assert_char_array_within_char_finite_set(&[Sexp::LIST_OPEN], &[Sexp::LIST_OPEN]);
    }

    #[test]
    fn assert_char_array_within_char_finite_set_accepts_each_family_wide_substrate_subset() {
        // Runtime cross-check that the THREE (subset, superset) pairs
        // the substrate's module-level `const _` witnesses pin at
        // COMPILE time are PROPER SUBSET embeddings at runtime too.
        // The pairs enforce the theorem at TWO stages of the
        // toolchain: the const witnesses fire FIRST at `cargo check`
        // (through the three module-level `const _: () =
        // assert_char_array_within_char_finite_set::<N, M>(...)`
        // lines), this runtime pin catches the drift at `cargo test`
        // as a safety net. Sibling posture to
        // `assert_char_array_pairwise_distinct_accepts_every_family_wide_substrate_array`
        // which sweeps the seven family-wide `[char; N]` arrays at
        // the INJECTIVITY axis; this pin sweeps the three (subset,
        // superset) PAIRS at the SUBSET-EMBEDDING axis.
        assert_char_array_within_char_finite_set::<2, 7>(
            &Sexp::LIST_DELIMITERS,
            &Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS,
        );
        assert_char_array_within_char_finite_set::<3, 7>(
            &QuoteForm::LEADS,
            &Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS,
        );
        assert_char_array_within_char_finite_set::<2, 5>(
            &Atom::SELF_ESCAPE_TABLE,
            &Atom::ESCAPE_SOURCES,
        );
    }

    #[test]
    fn assert_char_array_within_char_finite_set_accepts_repeated_array_entries_in_set() {
        // Peer corner to a (future-lift) `_covers_char_finite_set`:
        // this helper permits duplicates in `arr` because SUBSET-
        // membership is a DISTINCT-value predicate — `['a', 'a', 'b']`
        // is a subset of `{'a', 'b', 'c'}` even though the array is
        // not pairwise-distinct. Pins that the helper does NOT
        // gratuitously require INJECTIVITY on `arr` (the injectivity
        // axis is a DIFFERENT compile-time contract bound by
        // `assert_char_array_pairwise_distinct`; combining both binds
        // BOTH axes). Sibling posture to
        // `assert_u8_array_within_u8_finite_set_accepts_repeated_array_entries_in_set`
        // on the (u8) row's SUBSET-EMBEDDING peer.
        assert_char_array_within_char_finite_set(&['a', 'a', 'b'], &['a', 'b', 'c']);
    }

    #[test]
    #[should_panic(expected = "CHAR-SUBSET-VIOLATION")]
    fn assert_char_array_within_char_finite_set_panics_at_runtime_on_out_of_set_entry() {
        // NEGATIVE PIN — CHAR-SUBSET-VIOLATION corner: an array
        // carrying a single entry NOT in the target set MUST panic at
        // runtime with the CHAR-SUBSET-VIOLATION-named message. Pins
        // the helper's OWN reject arm — a regression that silently
        // returned without panicking on an out-of-set entry would
        // slip through the compile-time witnesses' failure mode too.
        // The offending char `'z'` is intentionally chosen OUTSIDE
        // the target set to pin the OUT-OF-SET drift mode.
        assert_char_array_within_char_finite_set(&['a', 'z'], &['a', 'b', 'c']);
    }

    #[test]
    #[should_panic(expected = "CHAR-SUBSET-VIOLATION")]
    fn assert_char_array_within_char_finite_set_panics_at_runtime_on_terminal_out_of_set_entry() {
        // NEGATIVE PIN — terminal-position drift: an out-of-set entry
        // at the LAST array position MUST panic — pins that the outer
        // `while i < N` loop reaches `i = N - 1` (else the terminal
        // drift would slip through). A regression that narrowed the
        // outer sweep to `while i < N - 1` (off-by-one on the OUTER
        // bound) would silently accept this array. Sibling posture to
        // `assert_u8_array_within_u8_finite_set_panics_at_runtime_on_terminal_out_of_set_entry`
        // on the (u8) row's terminal-position pin — both bind the
        // outer-sweep terminal bound at the ONE array-side outer loop
        // the helper carries.
        assert_char_array_within_char_finite_set(&['a', 'b', 'c', 'z'], &['a', 'b', 'c']);
    }

    #[test]
    fn assert_char_array_within_char_finite_set_panic_message_names_the_helper_and_char_subset_violation_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — CHAR-SUBSET-VIOLATION arm:
        // the panic message MUST begin with the helper's own name AND
        // identify the failed AXIS as "CHAR-SUBSET-VIOLATION" so
        // downstream diagnostics route the drift back to (a) the
        // helper by string search on
        // `"assert_char_array_within_char_finite_set"` and (b) the
        // axis by string search on `"CHAR-SUBSET-VIOLATION"`. Sibling
        // posture to
        // `assert_u8_array_within_u8_finite_set_panic_message_names_the_helper_and_subset_violation_axis`
        // on the (u8) row's provenance pin — the two pins together
        // bind the (helper, failed-axis) provenance pair at ONE test
        // per SUBSET helper on the (element-type) 2×1 face. The axis-
        // provenance string `"CHAR-SUBSET-VIOLATION"` is chosen
        // DISTINCT from EVERY sibling helper's axis vocabulary
        // (`"duplicate"` on the ARRAY-side pairwise-distinct sibling;
        // `"SUBSET-VIOLATION"` on the (u8) finite-set SUBSET-only
        // sibling; `"RANGE-SUBSET-VIOLATION"` on the (u8) range
        // SUBSET-only sibling; `"OUT-OF-SET"` / `"SET-BYTE-MISSING"`
        // on the (u8) covers-finite-set sibling; `"OUT-OF-RANGE"` /
        // `"MISSING"` on the (u8) covers-inclusive-range sibling;
        // `"ARITY-MISMATCH"` on both (u8) `_permutes_*` compound
        // helpers; `"SET-NOT-PAIRWISE-DISTINCT"` on the (u8) SET-side
        // well-formedness sibling) so a diagnostic that names the
        // failed axis routes UNAMBIGUOUSLY to (a) this specific char
        // SUBSET-embedding helper, (b) the `arr` argument as the
        // drift site rather than the `set` argument specifying the
        // target superset.
        let outcome = std::panic::catch_unwind(|| {
            assert_char_array_within_char_finite_set(&['a', 'z'], &['a', 'b', 'c']);
        });
        let payload = outcome.expect_err(
            "assert_char_array_within_char_finite_set must panic on \
             an out-of-set entry — the reject-out-of-set arm is the \
             sole CHAR-SUBSET-VIOLATION failure mode of the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_array_within_char_finite_set panic \
                 payload must be a static &str or String",
            );
        assert!(
            msg.contains("assert_char_array_within_char_finite_set"),
            "assert_char_array_within_char_finite_set panic message \
             {msg:?} must name the helper for provenance-preserving \
             failure diagnostics",
        );
        assert!(
            msg.contains("CHAR-SUBSET-VIOLATION"),
            "assert_char_array_within_char_finite_set panic message \
             {msg:?} must name the failed AXIS (\"CHAR-SUBSET-\
             VIOLATION\") for axis-provenance-preserving failure \
             diagnostics",
        );
    }

    #[test]
    #[should_panic(expected = "assert_char_array_pairwise_distinct")]
    fn assert_char_array_within_char_finite_set_panics_on_malformed_target_set_spec() {
        // NEGATIVE PIN — DELEGATED SET-side well-formedness: a
        // malformed target-set spec `['a', 'a', 'b']` fed into the
        // ARRAY-side within helper MUST panic on the DELEGATED
        // pairwise-distinct arm BEFORE the CHAR-SUBSET-VIOLATION arm
        // fires. Pins the delegation chain: a regression that dropped
        // the `assert_char_array_pairwise_distinct(set)` call at the
        // top of `assert_char_array_within_char_finite_set` would
        // silently accept a malformed set and produce a false-positive
        // verdict on any `arr` embedded in the DISTINCT-value subset.
        // The panic message here surfaces from the SIBLING helper
        // (containing the ARRAY-side helper's `"assert_char_array_
        // pairwise_distinct"` panic-name prefix rather than a bespoke
        // `"SET-NOT-PAIRWISE-DISTINCT"` axis string) because the char
        // row does NOT yet carry a separate `assert_char_finite_set_
        // pairwise_distinct` alias — the delegation reuses the
        // ARRAY-side helper directly per the design choice documented
        // on the SET-side-well-formedness section of the helper's
        // docstring. Sibling posture to
        // `assert_u8_array_within_u8_finite_set_panics_on_malformed_target_set_spec`
        // on the (u8) row's delegated-SET-well-formedness pin — the
        // two pins together bind the delegation chain at ONE test per
        // element-type row.
        assert_char_array_within_char_finite_set::<2, 3>(&['a', 'b'], &['a', 'b', 'b']);
    }

    // ── `assert_char_arrays_disjoint` — the CHAR-DISJOINTNESS-VIOLATION
    // verifier that binds `a ∩ b = ∅` at compile time on the reader-
    // boundary `char` vocabulary, peer to
    // `assert_char_array_within_char_finite_set` on the (char) row of
    // the (subset, disjointness) 2-corner face of the (contract-shape)
    // axis. The runtime test surface pins each of the helper's arms
    // (accept-both-empty, accept-either-empty, accept-disjoint-
    // singletons, accept-each-family-wide-substrate-pair, accept-arg-
    // order-symmetry, reject-single-collision, reject-terminal-a-
    // collision, reject-terminal-b-collision, panic-message-provenance
    // on the CHAR-DISJOINTNESS-VIOLATION axis) so a regression that
    // silently weakened the helper on ANY arm is caught by the
    // helper's OWN test surface rather than only surfacing as a false-
    // positive on some future disjoint `[char; N] × [char; M]` pair's
    // compound pin.

    #[test]
    fn assert_char_arrays_disjoint_accepts_both_empty_arrays() {
        // Both arrays empty at the `[char; 0] × [char; 0]` corner —
        // vacuously disjoint (no `(i, j)` pair exists to test). The
        // compile-time `const _: () = assert_char_arrays_disjoint(&[],
        // &[]);` would land on this arm, so the runtime call MUST
        // return normally. Turbofish binding required because there's
        // no other cue for the const parameters on the empty array
        // literals. Sibling posture to
        // `assert_char_array_within_char_finite_set_accepts_the_empty_array_within_any_set`
        // on the peer SUBSET-embedding helper — the two share the
        // trivial-arity arm across the (subset, disjointness) 2-corner
        // face on the (char) row.
        assert_char_arrays_disjoint::<0, 0>(&[], &[]);
    }

    #[test]
    fn assert_char_arrays_disjoint_accepts_either_side_empty() {
        // Either side empty at the `[char; 0] × [char; M]` OR
        // `[char; N] × [char; 0]` corners — vacuously disjoint (the
        // OUTER `while i < N` OR the INNER `while j < M` sweep is a
        // no-op). Pins BOTH SIDES of the (a-empty, b-empty) 2-corner
        // sub-face on the trivial-arity axis so a regression that
        // narrowed the sweep to only-a-non-empty OR only-b-non-empty
        // fails HERE at the empty-side corner rather than at a distant
        // false-positive.
        assert_char_arrays_disjoint::<0, 3>(&[], &['a', 'b', 'c']);
        assert_char_arrays_disjoint::<3, 0>(&['a', 'b', 'c'], &[]);
    }

    #[test]
    fn assert_char_arrays_disjoint_accepts_disjoint_singletons() {
        // Singleton `a = [K]` and singleton `b = [L]` with `K != L` at
        // the `[char; 1] × [char; 1]` corner — the minimal non-empty
        // disjointness relation. Pins the INNER `if a[i] != b[j]` gate
        // returns without panicking on a single distinct-pair check.
        // A regression that flipped the equality direction (`==` vs
        // `!=`) would silently reject every disjoint singleton pair.
        assert_char_arrays_disjoint(&['a'], &['b']);
    }

    #[test]
    fn assert_char_arrays_disjoint_accepts_each_family_wide_substrate_pair() {
        // Runtime cross-check that the FIVE (a, b) `[char; N] ×
        // [char; M]` pairs the substrate's module-level `const _`
        // witnesses pin at COMPILE time are proper DISJOINTNESS
        // embeddings at runtime too. The pairs enforce the theorem at
        // TWO stages of the toolchain: the const witnesses fire FIRST
        // at `cargo check` (through the five module-level `const _:
        // () = assert_char_arrays_disjoint::<N, M>(...)` lines), this
        // runtime pin catches the drift at `cargo test` as a safety
        // net. Sibling posture to
        // `assert_char_array_within_char_finite_set_accepts_each_family_wide_substrate_subset`
        // which sweeps the three (subset, superset) PAIRS at the
        // SUBSET-EMBEDDING axis; this pin sweeps the five (a, b)
        // PAIRS at the DISJOINTNESS axis on the SAME (char) row.
        assert_char_arrays_disjoint::<2, 2>(&Sexp::LIST_DELIMITERS, &Sexp::COMMENT_DELIMITERS);
        assert_char_arrays_disjoint::<2, 3>(&Sexp::LIST_DELIMITERS, &QuoteForm::LEADS);
        assert_char_arrays_disjoint::<2, 3>(&Sexp::COMMENT_DELIMITERS, &QuoteForm::LEADS);
        assert_char_arrays_disjoint::<2, 2>(&Sexp::LIST_DELIMITERS, &Atom::SELF_ESCAPE_TABLE);
        assert_char_arrays_disjoint::<3, 2>(&QuoteForm::LEADS, &Atom::SELF_ESCAPE_TABLE);
    }

    #[test]
    fn assert_char_arrays_disjoint_is_symmetric_in_argument_order() {
        // SYMMETRY PIN: swapping the two arguments produces the SAME
        // verdict. Pins that the disjointness relation is truly
        // symmetric across the two array arguments (the helper's
        // nested-sweep implementation does NOT gratuitously depend on
        // argument order). A regression that narrowed the sweep to
        // `for i in a { if !b.contains(a[i]) }` (subset-shape, not
        // disjointness-shape) would fail the swap on one direction
        // only. Runs each substrate pair BOTH ways.
        assert_char_arrays_disjoint(&Sexp::COMMENT_DELIMITERS, &Sexp::LIST_DELIMITERS);
        assert_char_arrays_disjoint(&QuoteForm::LEADS, &Sexp::LIST_DELIMITERS);
        assert_char_arrays_disjoint(&Atom::SELF_ESCAPE_TABLE, &QuoteForm::LEADS);
    }

    #[test]
    #[should_panic(expected = "CHAR-DISJOINTNESS-VIOLATION")]
    fn assert_char_arrays_disjoint_panics_at_runtime_on_collision() {
        // NEGATIVE PIN — CHAR-DISJOINTNESS-VIOLATION corner: two arrays
        // sharing a single entry MUST panic at runtime with the
        // CHAR-DISJOINTNESS-VIOLATION-named message. Pins the helper's
        // OWN reject arm — a regression that silently returned
        // without panicking on a cross-array collision would slip
        // through the compile-time witnesses' failure mode too. The
        // shared entry `'a'` is intentionally placed at the FIRST
        // position of BOTH arrays to pin the initial-position drift
        // mode.
        assert_char_arrays_disjoint(&['a', 'b'], &['a', 'c']);
    }

    #[test]
    #[should_panic(expected = "CHAR-DISJOINTNESS-VIOLATION")]
    fn assert_char_arrays_disjoint_panics_at_runtime_on_terminal_a_collision() {
        // NEGATIVE PIN — terminal-position drift on the OUTER `a` side:
        // a shared entry at the LAST position of `a` MUST panic — pins
        // that the outer `while i < N` loop reaches `i = N - 1` (else
        // the terminal drift on `a` would slip through). A regression
        // that narrowed the outer sweep to `while i < N - 1` (off-by-
        // one on the OUTER bound) would silently accept this pair.
        assert_char_arrays_disjoint(&['x', 'y', 'z'], &['z']);
    }

    #[test]
    #[should_panic(expected = "CHAR-DISJOINTNESS-VIOLATION")]
    fn assert_char_arrays_disjoint_panics_at_runtime_on_terminal_b_collision() {
        // NEGATIVE PIN — terminal-position drift on the INNER `b` side:
        // a shared entry at the LAST position of `b` MUST panic — pins
        // that the inner `while j < M` loop reaches `j = M - 1` (else
        // the terminal drift on `b` would slip through). A regression
        // that narrowed the inner sweep to `while j < M - 1` (off-by-
        // one on the INNER bound) would silently accept this pair.
        // Sibling posture to the outer-terminal pin above — the two
        // pins together bind the terminal bounds on BOTH loops.
        assert_char_arrays_disjoint(&['x'], &['a', 'b', 'x']);
    }

    #[test]
    fn assert_char_arrays_disjoint_panic_message_names_the_helper_and_char_disjointness_violation_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — CHAR-DISJOINTNESS-VIOLATION
        // arm: the panic message MUST begin with the helper's own name
        // AND identify the failed AXIS as "CHAR-DISJOINTNESS-VIOLATION"
        // so downstream diagnostics route the drift back to (a) the
        // helper by string search on `"assert_char_arrays_disjoint"`
        // and (b) the axis by string search on `"CHAR-DISJOINTNESS-
        // VIOLATION"`. Sibling posture to
        // `assert_char_array_within_char_finite_set_panic_message_names_the_helper_and_char_subset_violation_axis`
        // on the peer SUBSET-embedding helper's provenance pin — the
        // two pins together bind the (helper, failed-axis) provenance
        // pair at ONE test per corner of the (subset, disjointness)
        // 2-corner face on the (char) row. The axis-provenance string
        // `"CHAR-DISJOINTNESS-VIOLATION"` is chosen DISTINCT from EVERY
        // sibling helper's axis vocabulary (`"duplicate"` on the
        // ARRAY-side pairwise-distinct sibling; `"CHAR-SUBSET-
        // VIOLATION"` on the (char) SUBSET-embedding sibling;
        // `"SUBSET-VIOLATION"` on the (u8) finite-set SUBSET-only
        // sibling; `"RANGE-SUBSET-VIOLATION"` on the (u8) range
        // SUBSET-only sibling; `"OUT-OF-SET"` / `"SET-BYTE-MISSING"`
        // on the (u8) covers-finite-set sibling; `"OUT-OF-RANGE"` /
        // `"MISSING"` on the (u8) covers-inclusive-range sibling;
        // `"ARITY-MISMATCH"` on both (u8) `_permutes_*` compound
        // helpers; `"SET-NOT-PAIRWISE-DISTINCT"` on the (u8) SET-side
        // well-formedness sibling) so a diagnostic that names the
        // failed axis routes UNAMBIGUOUSLY to (a) this specific char
        // DISJOINTNESS helper.
        let outcome = std::panic::catch_unwind(|| {
            assert_char_arrays_disjoint(&['a', 'b'], &['a', 'c']);
        });
        let payload = outcome.expect_err(
            "assert_char_arrays_disjoint must panic on a cross-array \
             collision — the reject-collision arm is the sole CHAR-\
             DISJOINTNESS-VIOLATION failure mode of the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_arrays_disjoint panic payload must be a \
                 static &str or String",
            );
        assert!(
            msg.contains("assert_char_arrays_disjoint"),
            "assert_char_arrays_disjoint panic message {msg:?} must \
             name the helper for provenance-preserving failure \
             diagnostics",
        );
        assert!(
            msg.contains("CHAR-DISJOINTNESS-VIOLATION"),
            "assert_char_arrays_disjoint panic message {msg:?} must \
             name the failed AXIS (\"CHAR-DISJOINTNESS-VIOLATION\") \
             for axis-provenance-preserving failure diagnostics",
        );
    }

    // ── `assert_char_array_slice_equals_char_array` — the CHAR-SLICE-
    // EQUALS-ARRAY-VIOLATION verifier that binds the sub-slice
    // `full[START..START + M) == sub[..]` positionwise-composition
    // contract at compile time on the substrate's reader-boundary
    // `[char; N]` scalar-composed vocabulary, row-dual peer to
    // `assert_u8_array_slice_equals_u8_array` on the (u8) row of the
    // (element-type) axis of the SAME (SUB-SLICE ARRAY-image) column
    // of the (element-type × contract-shape) matrix. The runtime test
    // surface pins each of the helper's arms (accept-canonical-
    // middle-slice, accept-empty-sub-array-at-three-start-positions,
    // accept-full-array-degenerate-at-three-arities, accept-each-of-
    // the-eight-family-wide-substrate-arrays, reject-positionwise-
    // drift, reject-start-out-of-bounds, reject-slice-length-out-of-
    // bounds, panic-message-provenance on the CHAR-SLICE-EQUALS-
    // ARRAY-VIOLATION axis) so a regression that silently weakened
    // the helper on ANY arm (e.g. flipping `!=` to `==` on the char
    // comparison, dropping the `START` offset from the `full[START +
    // i]` read, returning early past ANY bounds gate, or dropping the
    // `as u32` char-to-scalar bridge that lets the const-eval sweep
    // proceed byte-for-byte) is caught by the helper's OWN test
    // surface rather than only surfacing as a false-positive on some
    // future `[char; N]`-typed reader-boundary array's per-position
    // ORDER pin.

    #[test]
    fn assert_char_array_slice_equals_char_array_accepts_a_canonical_middle_slice() {
        // Canonical sub-slice `full[START..START + M) == sub[..]`
        // inside a longer array `full` whose ENDPOINTS carry
        // DIFFERENT chars than the peer sub-array. Pins the outer
        // `while i < M` sweep reads `full[START + i]` at the OFFSET
        // position (not `full[i]`) — a regression that dropped the
        // `START` offset would compare `full[0..M)` against `sub[..]`
        // and pass on `full[0]='z' != sub[0]='b'` silently or panic
        // on the wrong axis. `START = 1` pins the sweep skips
        // position `[0..START)` and reads only `[1..1+3) = [1..4)`.
        assert_char_array_slice_equals_char_array::<7, 3, 1>(
            &['z', 'b', 'c', 'd', 'z', 'z', 'z'],
            &['b', 'c', 'd'],
        );
    }

    #[test]
    fn assert_char_array_slice_equals_char_array_accepts_the_empty_sub_array() {
        // LEGAL degenerate: `M == 0` collapses the sub-array into an
        // empty listing `[]`. The sweep never enters the loop body
        // and the helper accepts. Cross-position coverage pins the
        // empty-sub-array acceptance at THREE distinct `START`
        // positions (`START == 0` at the left endpoint, `START == 3`
        // in the interior, `START == N` at the right endpoint — the
        // latter is the corner `START == N` combined with `M == 0`
        // that the START-OUT-OF-BOUNDS gate's inclusive upper bound
        // must accept). A regression that hard-coded `START < N` OR
        // panicked on the `M == 0` corner is caught on ALL THREE
        // arms.
        assert_char_array_slice_equals_char_array::<5, 0, 0>(&['x', 'x', 'x', 'x', 'x'], &[]);
        assert_char_array_slice_equals_char_array::<5, 0, 3>(&['x', 'x', 'x', 'x', 'x'], &[]);
        assert_char_array_slice_equals_char_array::<5, 0, 5>(&['x', 'x', 'x', 'x', 'x'], &[]);
    }

    #[test]
    fn assert_char_array_slice_equals_char_array_accepts_the_full_array_degenerate() {
        // Full-array-covering slice `M == N, START == 0` collapses
        // to the ALL-positions-equal-peer-array shape `full == sub`
        // pointwise. Pins that the sweep proceeds through EVERY
        // position of the outer array when `START = 0` and `M = N`.
        // Cross-arity coverage on `N ∈ {1, 3, 7}` pins the sweep's
        // terminal-position visit across the range of char arities
        // the substrate's reader-boundary arrays span (`N = 1` for
        // `UnquoteForm::LEADS`, `N = 2` for the delimiter/escape
        // pairs, `N = 3` for `QuoteForm::LEADS`, `N = 5` for
        // `ESCAPE_SOURCES` / `ESCAPE_DECODED`, `N = 7` for
        // `NON_WHITESPACE_BARE_ATOM_TERMINATORS`).
        assert_char_array_slice_equals_char_array::<1, 1, 0>(&[','], &[',']);
        assert_char_array_slice_equals_char_array::<3, 3, 0>(&['\'', '`', ','], &['\'', '`', ',']);
        assert_char_array_slice_equals_char_array::<7, 7, 0>(
            &['(', ')', '\'', '`', ',', '"', ';'],
            &['(', ')', '\'', '`', ',', '"', ';'],
        );
    }

    #[test]
    fn assert_char_array_slice_equals_char_array_accepts_each_family_wide_substrate_array() {
        // Runtime cross-check that the EIGHT reader-boundary
        // `[char; N]` scalar-composed substrate arrays each byte-
        // equal their canonical literal-char listing pointwise at the
        // FULL-ARRAY corner (`M == N`, `START == 0`). Runs the SAME
        // helper the eight `const _` witnesses at line ~616 in this
        // file run at rustc time — a runtime safety net enforcing
        // the theorem at BOTH stages of the toolchain (const at
        // `cargo check`, runtime at `cargo test`). A regression that
        // renamed one of the per-role `*_LEAD` / `*_DELIMITER` /
        // `*_ESCAPE_LEAD` / `*_ESCAPE_SOURCE` / `*_ESCAPE_DECODED`
        // aliases (or drifted its literal char value at the
        // declaration site, or reordered a slot in the outer array's
        // initializer) fails HERE at the substrate callsite AND at
        // the const witness above. Peer of
        // `assert_u8_array_slice_equals_u8_array_accepts_sub_carving_hash_discriminators_per_position_order`
        // on the (u8) row — that witness carries the FULL-ARRAY per-
        // position ORDER theorem for the FOUR sub-carving
        // `HASH_DISCRIMINATORS` arrays; this witness carries the same
        // theorem for the EIGHT reader-boundary `char` arrays.
        //
        // The eight reader-boundary scalar-composed arrays appear
        // here in canonical (owning-algebra, per-role-alias-count-
        // ascending) order:
        // * `Sexp::LIST_DELIMITERS == ['(', ')']` — the outer-`Sexp`
        //   list-delimiter pair.
        // * `Sexp::COMMENT_DELIMITERS == [';', '\n']` — the outer-
        //   `Sexp` comment-boundary pair.
        // * `Atom::SELF_ESCAPE_TABLE == ['"', '\\']` — the `Atom`
        //   escape-self pair.
        // * `Atom::ESCAPE_SOURCES == ['n', 't', 'r', '"', '\\']` —
        //   the `Atom` escape-source column.
        // * `Atom::ESCAPE_DECODED == ['\n', '\t', '\r', '"', '\\']`
        //   — the `Atom` escape-decoded column.
        // * `Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS == ['(',
        //   ')', '\'', '`', ',', '"', ';']` — the outer-`Sexp`
        //   reader-boundary category-leading seven-char SPAN.
        // * `QuoteForm::LEADS == ['\'', '`', ',']` — the quote-
        //   family reader-lead-char triple.
        // * `UnquoteForm::LEADS == [',']` — the substitution-subset
        //   shared-lead singleton.
        assert_char_array_slice_equals_char_array::<2, 2, 0>(&Sexp::LIST_DELIMITERS, &['(', ')']);
        assert_char_array_slice_equals_char_array::<2, 2, 0>(
            &Sexp::COMMENT_DELIMITERS,
            &[';', '\n'],
        );
        assert_char_array_slice_equals_char_array::<2, 2, 0>(
            &Atom::SELF_ESCAPE_TABLE,
            &['"', '\\'],
        );
        assert_char_array_slice_equals_char_array::<5, 5, 0>(
            &Atom::ESCAPE_SOURCES,
            &['n', 't', 'r', '"', '\\'],
        );
        assert_char_array_slice_equals_char_array::<5, 5, 0>(
            &Atom::ESCAPE_DECODED,
            &['\n', '\t', '\r', '"', '\\'],
        );
        assert_char_array_slice_equals_char_array::<7, 7, 0>(
            &Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS,
            &['(', ')', '\'', '`', ',', '"', ';'],
        );
        assert_char_array_slice_equals_char_array::<3, 3, 0>(&QuoteForm::LEADS, &['\'', '`', ',']);
        assert_char_array_slice_equals_char_array::<1, 1, 0>(
            &crate::error::UnquoteForm::LEADS,
            &[','],
        );
    }

    #[test]
    fn assert_char_array_slice_equals_char_array_accepts_terminator_span_sub_carving_positional_composition(
    ) {
        // Runtime cross-check that the outer-`Sexp` reader-boundary
        // terminator SPAN `Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS`
        // (`[char; 7]`) positionally composes as the segmented
        // concatenation of its FOUR sub-carvings:
        //
        //     NON_WHITESPACE_BARE_ATOM_TERMINATORS
        //         == Sexp::LIST_DELIMITERS       // slots [0..2)
        //         ++ QuoteForm::LEADS            // slots [2..5)
        //         ++ [Atom::STR_DELIMITER]       // slot   [5..6)
        //         ++ [Sexp::COMMENT_LEAD]        // slot   [6..7)
        //
        // Runs the SAME helper the FOUR `const _` witnesses at line
        // ~915 in this file run at rustc time — a runtime safety net
        // enforcing the ARRAY-LEVEL POSITIONAL-COMPOSITION theorem at
        // BOTH stages of the toolchain (const at `cargo check`,
        // runtime at `cargo test`). Strictly STRONGER on the
        // (contract-strength) axis than the sibling
        // `sexp_list_delimiters_positionally_align_with_terminator_head`
        // /
        // `quote_form_leads_positionally_align_with_terminator_mid`
        // -shape pre-lift runtime pins that lived only in prose in the
        // sub-carvings' composition-rule docstrings: those pin the
        // SUBSET containment `LIST_DELIMITERS ⊆ NON_WHITESPACE_BARE_
        // ATOM_TERMINATORS` (and `QuoteForm::LEADS ⊆
        // NON_WHITESPACE_BARE_ATOM_TERMINATORS`) as a SET-level
        // theorem, order-invariant on the sub-carving side; this pin
        // binds the ARRAY-LEVEL POSITIONAL identity at the CANONICAL
        // slot segments. A regression that reorders any sub-carving's
        // declaration (e.g. `Sexp::LIST_DELIMITERS = [LIST_CLOSE,
        // LIST_OPEN]` swapping the pair, or `QuoteForm::LEADS =
        // [QUASIQUOTE_LEAD, QUOTE_LEAD, UNQUOTE_LEAD]` permuting the
        // triple) preserves the SET-level SUBSET theorem AND the FULL-
        // ARRAY LITERAL witness on `NON_WHITESPACE_BARE_ATOM_
        // TERMINATORS` (which peer-compares against a HARDCODED
        // `[char; 7]` literal via its inline listing rather than
        // against the SUB-CARVING arrays) but silently misaligns every
        // consumer that treats the composite's slot segment as
        // positionally-interchangeable with its sub-carving. Peer
        // posture to `assert_u8_array_slice_equals_u8_array_accepts_
        // sexp_shape_hash_discriminators_per_position_order`-shape
        // sibling on the (u8) row — that pin carries the SUB-CARVING
        // per-position POSITIONAL-COMPOSITION theorem for the twelve-
        // slot outer `SexpShape::HASH_DISCRIMINATORS` container; this
        // pin carries the same theorem for the seven-slot outer
        // `NON_WHITESPACE_BARE_ATOM_TERMINATORS` SPAN.
        assert_char_array_slice_equals_char_array::<7, 2, 0>(
            &Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS,
            &Sexp::LIST_DELIMITERS,
        );
        assert_char_array_slice_equals_char_array::<7, 3, 2>(
            &Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS,
            &QuoteForm::LEADS,
        );
        assert_char_array_slice_equals_char_array::<7, 1, 5>(
            &Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS,
            &[Atom::STR_DELIMITER],
        );
        assert_char_array_slice_equals_char_array::<7, 1, 6>(
            &Sexp::NON_WHITESPACE_BARE_ATOM_TERMINATORS,
            &[Sexp::COMMENT_LEAD],
        );
    }

    #[test]
    #[should_panic(expected = "CHAR-SLICE-EQUALS-ARRAY-VIOLATION")]
    fn assert_char_array_slice_equals_char_array_panics_at_runtime_on_positionwise_drift() {
        // NEGATIVE PIN — CHAR-SLICE-EQUALS-ARRAY-VIOLATION corner: a
        // char at some position in `full[START..START + M)` that
        // does NOT byte-equal the peer sub-array `sub` at the
        // offset-matched position MUST panic at runtime with the
        // axis-named message. Pins the helper's positionwise-drift
        // reject arm — a regression that silently short-circuited on
        // the first slice position without checking the middle or
        // terminal slice positions would slip through the compile-
        // time witness's failure mode too. The offending char `'!'`
        // at outer position `3` (interior of the sub-slice `[1..4)`,
        // offset `2` inside `sub`) pins the middle-of-slice drift
        // mode.
        assert_char_array_slice_equals_char_array::<5, 3, 1>(
            &['z', 'b', 'c', '!', 'z'],
            &['b', 'c', 'd'],
        );
    }

    #[test]
    #[should_panic(expected = "START-OUT-OF-BOUNDS")]
    fn assert_char_array_slice_equals_char_array_panics_at_runtime_on_start_out_of_bounds() {
        // NEGATIVE PIN — START-OUT-OF-BOUNDS gate: a caller-side
        // turbofish arity slip on the `START` const-generic where
        // `START > N` MUST panic at runtime with the START-OUT-OF-
        // BOUNDS-named message BEFORE the peer SLICE-LENGTH-OUT-OF-
        // BOUNDS gate reads `N - START` (which would `usize`-
        // underflow had this gate not caught the slip first). Pins
        // the gate's placement at the TOP of the helper — a
        // regression that dropped the gate would either underflow
        // subtraction at the peer gate OR panic deeper in
        // `full[START + i]` bounds-checking with a helper-name-less
        // panic message. The offending `START = 7` against `N = 5`
        // pins the strict `START > N` reject arm; the LEGAL
        // `START == N` empty-slice-at-right-endpoint corner is
        // covered by the peer acceptance test above.
        assert_char_array_slice_equals_char_array::<5, 0, 7>(&['x', 'x', 'x', 'x', 'x'], &[]);
    }

    #[test]
    #[should_panic(expected = "SLICE-LENGTH-OUT-OF-BOUNDS")]
    fn assert_char_array_slice_equals_char_array_panics_at_runtime_on_slice_length_out_of_bounds() {
        // NEGATIVE PIN — SLICE-LENGTH-OUT-OF-BOUNDS gate: a peer
        // sub-array arity `M` that exceeds the outer array's tail
        // cardinality `N - START` MUST panic at runtime with the
        // slice-length-out-of-bounds-named message. Peer gate to the
        // START-OUT-OF-BOUNDS arm above — the two gates jointly
        // enforce `START ≤ N` and `M ≤ N - START` before any content
        // sweep. The offending `M = 5` against `N - START = 5 - 3 =
        // 2` pins the strict `M > N - START` reject arm; the LEGAL
        // exact-fit corner `M == N - START` is covered by the
        // middle-slice acceptance test above.
        assert_char_array_slice_equals_char_array::<5, 5, 3>(
            &['x', 'x', 'x', 'x', 'x'],
            &['x', 'x', 'x', 'x', 'x'],
        );
    }

    #[test]
    fn assert_char_array_slice_equals_char_array_panic_message_names_the_helper_and_char_slice_equals_array_violation_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — CHAR-SLICE-EQUALS-ARRAY-
        // VIOLATION arm: the panic message MUST begin with the
        // helper's own name AND identify the failed AXIS as "CHAR-
        // SLICE-EQUALS-ARRAY-VIOLATION" so downstream diagnostics
        // route the drift back to (a) the helper by string search on
        // `"assert_char_array_slice_equals_char_array"` and (b) the
        // failed axis by string search on `"CHAR-SLICE-EQUALS-ARRAY-
        // VIOLATION"`. Sibling posture to the u8-row peer's
        // provenance pin
        // `assert_u8_array_slice_equals_u8_array_panic_message_names_the_helper_and_slice_equals_array_violation_axis`
        // — the two pins together bind the (helper, failed-axis)
        // provenance pair at ONE test per corner of the (SUB-SLICE
        // ARRAY-image) column on both the (u8) row AND the (char)
        // row of the (element-type × contract-shape) matrix. The
        // `CHAR-` prefix on this axis disambiguates it from the u8-
        // row sibling's plain `SLICE-EQUALS-ARRAY-VIOLATION` axis
        // vocabulary; the shared `-SLICE-EQUALS-ARRAY-VIOLATION`
        // infix lets callers grep either element-type variant by
        // the shared axis substring.
        let outcome = std::panic::catch_unwind(|| {
            assert_char_array_slice_equals_char_array::<5, 3, 1>(
                &['z', 'b', 'c', '!', 'z'],
                &['b', 'c', 'd'],
            );
        });
        let payload = outcome.expect_err(
            "assert_char_array_slice_equals_char_array must panic on \
             a positionwise drift — the reject-positionwise-drift arm \
             is the CONTENT failure mode of the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_array_slice_equals_char_array panic \
                 payload must be a static &str or String",
            );
        assert!(
            msg.contains("assert_char_array_slice_equals_char_array"),
            "assert_char_array_slice_equals_char_array panic message \
             {msg:?} must name the helper for provenance-preserving \
             failure diagnostics",
        );
        assert!(
            msg.contains("CHAR-SLICE-EQUALS-ARRAY-VIOLATION"),
            "assert_char_array_slice_equals_char_array panic message \
             {msg:?} must name the failed AXIS (\"CHAR-SLICE-EQUALS-\
             ARRAY-VIOLATION\") for axis-provenance-preserving \
             failure diagnostics",
        );
    }

    // ── `assert_str_array_slice_equals_str_array` — the (str)-row
    // peer to `assert_u8_array_slice_equals_u8_array` +
    // `assert_char_array_slice_equals_char_array` on the (element-
    // type) axis of the SUB-SLICE ARRAY-image column of the
    // (element-type × contract-shape) matrix. The runtime test
    // surface pins each of the helper's arms (accept-middle-slice,
    // accept-empty-sub-array, accept-full-array-degenerate, accept-
    // sexp-shape-labels-positional-decomposition, reject-positionwise-
    // drift, reject-start-out-of-bounds, reject-slice-length-out-of-
    // bounds, panic-message-provenance on the STR-SLICE-EQUALS-ARRAY-
    // VIOLATION axis) so a regression that silently weakened the
    // helper on ANY arm is caught by the helper's OWN test surface
    // rather than only surfacing as a false-positive on some future
    // sub-slice `[&'static str; N]` pair's compound pin.

    #[test]
    fn assert_str_array_slice_equals_str_array_accepts_a_canonical_middle_slice() {
        // Canonical sub-slice `full[START..START + M) == sub[..]`
        // inside a longer array `full` whose ENDPOINTS carry DIFFERENT
        // strings than the peer sub-array. Pins the outer `while i <
        // M` sweep reads `full[START + i]` at the OFFSET position
        // (not `full[i]`) — a regression that dropped the `START`
        // offset would compare `full[0..M)` against `sub[..]` and
        // pass on `full[0]="z" != sub[0]="b"` silently or panic on
        // the wrong axis. `START = 1` pins the sweep skips position
        // `[0..START)` and reads only `[1..1+3) = [1..4)`. Sibling
        // posture to
        // `assert_char_array_slice_equals_char_array_accepts_a_canonical_middle_slice`
        // and
        // `assert_u8_array_slice_equals_u8_array_accepts_a_canonical_middle_slice`
        // — the three share the middle-slice acceptance arm across
        // the (element-type × contract-shape) 3-row × 1-column face
        // at the (SUB-SLICE ARRAY-image) column.
        assert_str_array_slice_equals_str_array::<7, 3, 1>(
            &["z", "b", "c", "d", "z", "z", "z"],
            &["b", "c", "d"],
        );
    }

    #[test]
    fn assert_str_array_slice_equals_str_array_accepts_the_empty_sub_array() {
        // LEGAL degenerate: `M == 0` collapses the sub-array into an
        // empty listing `[]`. The sweep never enters the loop body
        // and the helper accepts. Cross-position coverage pins the
        // empty-sub-array acceptance at THREE distinct `START`
        // positions (`START == 0` at the left endpoint, `START == 3`
        // in the interior, `START == N` at the right endpoint — the
        // latter is the corner `START == N` combined with `M == 0`
        // that the START-OUT-OF-BOUNDS gate's inclusive upper bound
        // must accept). A regression that hard-coded `START < N` OR
        // panicked on the `M == 0` corner is caught on ALL THREE
        // arms.
        assert_str_array_slice_equals_str_array::<5, 0, 0>(&["x", "x", "x", "x", "x"], &[]);
        assert_str_array_slice_equals_str_array::<5, 0, 3>(&["x", "x", "x", "x", "x"], &[]);
        assert_str_array_slice_equals_str_array::<5, 0, 5>(&["x", "x", "x", "x", "x"], &[]);
    }

    #[test]
    fn assert_str_array_slice_equals_str_array_accepts_the_full_array_degenerate() {
        // Full-array-covering slice `M == N, START == 0` collapses
        // to the ALL-positions-equal-peer-array shape `full == sub`
        // pointwise. Pins that the sweep proceeds through EVERY
        // position of the outer array when `START = 0` and `M = N`.
        // Cross-arity coverage on `N ∈ {1, 3, 6}` pins the sweep's
        // terminal-position visit across the range of str arities
        // the substrate's LABELS arrays span (`N = 1` for the
        // singleton sub-carvings, `N = 4` for `QuoteForm::LABELS`,
        // `N = 6` for `AtomKind::LABELS`).
        assert_str_array_slice_equals_str_array::<1, 1, 0>(&["nil"], &["nil"]);
        assert_str_array_slice_equals_str_array::<3, 3, 0>(
            &["quote", "quasiquote", "unquote"],
            &["quote", "quasiquote", "unquote"],
        );
        assert_str_array_slice_equals_str_array::<6, 6, 0>(
            &["symbol", "keyword", "string", "int", "float", "bool"],
            &["symbol", "keyword", "string", "int", "float", "bool"],
        );
    }

    #[test]
    fn assert_str_array_slice_equals_str_array_accepts_sexp_shape_labels_positional_decomposition()
    {
        // Runtime cross-check that the FOUR canonical sub-slices of
        // `crate::error::SexpShape::LABELS` (`[&'static str; 12]`)
        // each byte-equal their sub-carving's canonical
        // `[&'static str; M]` listing pointwise. Runs the SAME
        // helper the FOUR `const _` witnesses in `error.rs` (in the
        // block titled "Compile-time SLICE-EQUALS-ARRAY witnesses
        // closing the twelve-arm `SexpShape::LABELS` POSITIONAL
        // decomposition") run at rustc time — a runtime safety net
        // enforcing the theorem at BOTH stages of the toolchain
        // (const at `cargo check`, runtime at `cargo test`). A
        // regression that reordered any of the twelve slots in the
        // outer array's initializer, or drifted any sub-carving's
        // per-role LABEL alias, fails HERE at the substrate callsite
        // AND at the const witness in `error.rs`. Sibling posture to
        // `assert_u8_array_slice_equals_u8_array_accepts_sub_carving_hash_discriminators_per_position_order`
        // on the (u8) row — that witness carries the positional
        // decomposition theorem for the FOUR sub-carving
        // `HASH_DISCRIMINATORS` arrays; this witness carries the
        // SAME theorem for the FOUR sub-carving LABELS arrays
        // (strictly STRONGER at the `[1..7)` slice: the (u8) row's
        // sibling collapses to a SCALAR replica witness on the six-
        // slot atomic-payload middle slice, but the (str) row's
        // per-slot label listing distinguishes ALL SIX slots
        // individually).
        //
        // The four canonical sub-slices are (all under the shared
        // `&'static str` element-type and shared parent
        // `[&'static str; 12]` outer container `SexpShape::LABELS`):
        //   1. `SexpShape::LABELS[0..1)  ==
        //      [StructuralKind::NIL_LABEL]`
        //   2. `SexpShape::LABELS[1..7)  == AtomKind::LABELS`
        //   3. `SexpShape::LABELS[7..8)  ==
        //      [StructuralKind::LIST_LABEL]`
        //   4. `SexpShape::LABELS[8..12) == QuoteForm::LABELS`
        assert_str_array_slice_equals_str_array::<12, 1, 0>(
            &crate::error::SexpShape::LABELS,
            &[crate::error::StructuralKind::NIL_LABEL],
        );
        assert_str_array_slice_equals_str_array::<12, 6, 1>(
            &crate::error::SexpShape::LABELS,
            &AtomKind::LABELS,
        );
        assert_str_array_slice_equals_str_array::<12, 1, 7>(
            &crate::error::SexpShape::LABELS,
            &[crate::error::StructuralKind::LIST_LABEL],
        );
        assert_str_array_slice_equals_str_array::<12, 4, 8>(
            &crate::error::SexpShape::LABELS,
            &QuoteForm::LABELS,
        );
    }

    #[test]
    fn assert_str_array_slice_equals_str_array_accepts_every_family_wide_substrate_array_full_array_literal_listing(
    ) {
        // Runtime cross-check that the SAME five (str)-row FULL-ARRAY
        // LITERAL witnesses covered at COMPILE time by the module-
        // level `const _: () = ...` cluster immediately below the
        // (str)-row `assert_str_array_pairwise_distinct` witnesses
        // (`Atom::BOOL_LITERALS` / `AtomKind::LABELS` /
        // `QuoteForm::PREFIXES` / `QuoteForm::LABELS` /
        // `QuoteForm::IAC_FORGE_TAGS`) 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 (const at `cargo check`, runtime at `cargo
        // test`). Sibling posture to
        // `assert_char_array_slice_equals_char_array_accepts_every_family_wide_substrate_array_full_array_literal_listing`
        // (if / when that (char)-row runtime-safety-net peer is
        // added) — the two would jointly enforce the FULL-ARRAY per-
        // position ORDER column at runtime across the (char, str)
        // 2-row face of the (element-type × contract-shape) matrix.
        //
        // 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` / `*_PREFIX`
        // / `*_TAG` / `TRUE_LITERAL` / `FALSE_LITERAL` aliases the
        // outer array's slots re-export, fails HERE with the
        // `STR-SLICE-EQUALS-ARRAY-VIOLATION` axis panic naming the
        // drifted position.
        assert_str_array_slice_equals_str_array::<2, 2, 0>(&Atom::BOOL_LITERALS, &["#t", "#f"]);
        assert_str_array_slice_equals_str_array::<6, 6, 0>(
            &AtomKind::LABELS,
            &["symbol", "keyword", "string", "int", "float", "bool"],
        );
        assert_str_array_slice_equals_str_array::<4, 4, 0>(
            &QuoteForm::PREFIXES,
            &["'", "`", ",", ",@"],
        );
        assert_str_array_slice_equals_str_array::<4, 4, 0>(
            &QuoteForm::LABELS,
            &["quote", "quasiquote", "unquote", "unquote-splice"],
        );
        assert_str_array_slice_equals_str_array::<4, 4, 0>(
            &QuoteForm::IAC_FORGE_TAGS,
            &["quote", "quasiquote", "unquote", "unquote-splicing"],
        );
    }

    #[test]
    #[should_panic(expected = "STR-SLICE-EQUALS-ARRAY-VIOLATION")]
    fn assert_str_array_slice_equals_str_array_panics_at_runtime_on_positionwise_drift() {
        // NEGATIVE PIN — STR-SLICE-EQUALS-ARRAY-VIOLATION corner: a
        // str at some position in `full[START..START + M)` that does
        // NOT byte-equal the peer sub-array `sub` at the offset-
        // matched position MUST panic at runtime with the axis-named
        // message. Pins the helper's positionwise-drift reject arm —
        // a regression that silently short-circuited on the first
        // slice position without checking the middle or terminal
        // slice positions would slip through the compile-time
        // witness's failure mode too. The offending str `"!"` at
        // outer position `3` (interior of the sub-slice `[1..4)`,
        // offset `2` inside `sub`) pins the middle-of-slice drift
        // mode.
        assert_str_array_slice_equals_str_array::<5, 3, 1>(
            &["z", "b", "c", "!", "z"],
            &["b", "c", "d"],
        );
    }

    #[test]
    #[should_panic(expected = "START-OUT-OF-BOUNDS")]
    fn assert_str_array_slice_equals_str_array_panics_at_runtime_on_start_out_of_bounds() {
        // NEGATIVE PIN — START-OUT-OF-BOUNDS gate: a caller-side
        // turbofish arity slip on the `START` const-generic where
        // `START > N` MUST panic at runtime with the START-OUT-OF-
        // BOUNDS-named message BEFORE the peer SLICE-LENGTH-OUT-OF-
        // BOUNDS gate reads `N - START` (which would `usize`-
        // underflow had this gate not caught the slip first). Pins
        // the gate's placement at the TOP of the helper — a
        // regression that dropped the gate would either underflow
        // subtraction at the peer gate OR panic deeper in
        // `full[START + i]` bounds-checking with a helper-name-less
        // panic message. The offending `START = 7` against `N = 5`
        // pins the strict `START > N` reject arm; the LEGAL
        // `START == N` empty-slice-at-right-endpoint corner is
        // covered by the peer acceptance test above.
        assert_str_array_slice_equals_str_array::<5, 0, 7>(&["x", "x", "x", "x", "x"], &[]);
    }

    #[test]
    #[should_panic(expected = "SLICE-LENGTH-OUT-OF-BOUNDS")]
    fn assert_str_array_slice_equals_str_array_panics_at_runtime_on_slice_length_out_of_bounds() {
        // NEGATIVE PIN — SLICE-LENGTH-OUT-OF-BOUNDS gate: a peer
        // sub-array arity `M` that exceeds the outer array's tail
        // cardinality `N - START` MUST panic at runtime with the
        // slice-length-out-of-bounds-named message. Peer gate to the
        // START-OUT-OF-BOUNDS arm above — the two gates jointly
        // enforce `START ≤ N` and `M ≤ N - START` before any content
        // sweep. The offending `M = 5` against `N - START = 5 - 3 =
        // 2` pins the strict `M > N - START` reject arm; the LEGAL
        // exact-fit corner `M == N - START` is covered by the middle-
        // slice acceptance test above.
        assert_str_array_slice_equals_str_array::<5, 5, 3>(
            &["x", "x", "x", "x", "x"],
            &["x", "x", "x", "x", "x"],
        );
    }

    #[test]
    fn assert_str_array_slice_equals_str_array_panic_message_names_the_helper_and_str_slice_equals_array_violation_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — STR-SLICE-EQUALS-ARRAY-
        // VIOLATION arm: the panic message MUST begin with the
        // helper's own name AND identify the failed AXIS as "STR-
        // SLICE-EQUALS-ARRAY-VIOLATION" so downstream diagnostics
        // route the drift back to (a) the helper by string search on
        // `"assert_str_array_slice_equals_str_array"` and (b) the
        // failed axis by string search on `"STR-SLICE-EQUALS-ARRAY-
        // VIOLATION"`. Sibling posture to the u8-row peer's
        // provenance pin
        // `assert_u8_array_slice_equals_u8_array_panic_message_names_the_helper_and_slice_equals_array_violation_axis`
        // AND the char-row peer's provenance pin
        // `assert_char_array_slice_equals_char_array_panic_message_names_the_helper_and_char_slice_equals_array_violation_axis`
        // — the three pins together bind the (helper, failed-axis)
        // provenance triple at ONE test per corner of the (SUB-SLICE
        // ARRAY-image) column on the (u8) + (char) + (str) rows of
        // the (element-type × contract-shape) matrix. The `STR-`
        // prefix on this axis disambiguates it from the u8-row
        // sibling's plain `SLICE-EQUALS-ARRAY-VIOLATION` axis
        // vocabulary AND the char-row sibling's `CHAR-SLICE-EQUALS-
        // ARRAY-VIOLATION` axis vocabulary; the shared `-SLICE-
        // EQUALS-ARRAY-VIOLATION` infix lets callers grep any of
        // the three element-type variants by the shared axis
        // substring.
        let outcome = std::panic::catch_unwind(|| {
            assert_str_array_slice_equals_str_array::<5, 3, 1>(
                &["z", "b", "c", "!", "z"],
                &["b", "c", "d"],
            );
        });
        let payload = outcome.expect_err(
            "assert_str_array_slice_equals_str_array must panic on a \
             positionwise drift — the reject-positionwise-drift arm \
             is the CONTENT failure mode of the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_str_array_slice_equals_str_array panic \
                 payload must be a static &str or String",
            );
        assert!(
            msg.contains("assert_str_array_slice_equals_str_array"),
            "assert_str_array_slice_equals_str_array panic message \
             {msg:?} must name the helper for provenance-preserving \
             failure diagnostics",
        );
        assert!(
            msg.contains("STR-SLICE-EQUALS-ARRAY-VIOLATION"),
            "assert_str_array_slice_equals_str_array panic message \
             {msg:?} must name the failed AXIS (\"STR-SLICE-EQUALS-\
             ARRAY-VIOLATION\") for axis-provenance-preserving \
             failure diagnostics",
        );
    }

    // ── `assert_u8_arrays_disjoint` — the U8-DISJOINTNESS-VIOLATION
    // verifier that binds `a ∩ b = ∅` at compile time on the outer-
    // `Sexp` cache-key `u8` vocabulary, peer to
    // `assert_u8_array_within_u8_finite_set` on the (u8) row of the
    // (subset, disjointness) 2-corner face of the (contract-shape)
    // axis AND row-dual peer to `assert_char_arrays_disjoint` on the
    // (element-type) axis of the SAME (contract-shape) column. The
    // runtime test surface pins each of the helper's arms (accept-
    // both-empty, accept-either-empty, accept-disjoint-singletons,
    // accept-each-family-wide-substrate-pair, accept-arg-order-
    // symmetry, reject-single-collision, reject-terminal-a-collision,
    // reject-terminal-b-collision, panic-message-provenance on the
    // U8-DISJOINTNESS-VIOLATION axis) so a regression that silently
    // weakened the helper on ANY arm is caught by the helper's OWN
    // test surface rather than only surfacing as a false-positive on
    // some future disjoint `[u8; N] × [u8; M]` pair's compound pin.

    #[test]
    fn assert_u8_arrays_disjoint_accepts_both_empty_arrays() {
        // Both arrays empty at the `[u8; 0] × [u8; 0]` corner —
        // vacuously disjoint (no `(i, j)` pair exists to test). The
        // compile-time `const _: () = assert_u8_arrays_disjoint(&[],
        // &[]);` would land on this arm, so the runtime call MUST
        // return normally. Turbofish binding required because there's
        // no other cue for the const parameters on the empty array
        // literals. Sibling posture to
        // `assert_char_arrays_disjoint_accepts_both_empty_arrays` on
        // the (char) row-dual peer — the two share the trivial-arity
        // arm across the (element-type × contract-shape) 4-corner
        // face at the (disjointness) column.
        assert_u8_arrays_disjoint::<0, 0>(&[], &[]);
    }

    #[test]
    fn assert_u8_arrays_disjoint_accepts_either_side_empty() {
        // Either side empty at the `[u8; 0] × [u8; M]` OR
        // `[u8; N] × [u8; 0]` corners — vacuously disjoint (the
        // OUTER `while i < N` OR the INNER `while j < M` sweep is a
        // no-op). Pins BOTH SIDES of the (a-empty, b-empty) 2-corner
        // sub-face on the trivial-arity axis so a regression that
        // narrowed the sweep to only-a-non-empty OR only-b-non-empty
        // fails HERE at the empty-side corner rather than at a
        // distant false-positive.
        assert_u8_arrays_disjoint::<0, 3>(&[], &[0, 1, 2]);
        assert_u8_arrays_disjoint::<3, 0>(&[0, 1, 2], &[]);
    }

    #[test]
    fn assert_u8_arrays_disjoint_accepts_disjoint_singletons() {
        // Singleton `a = [K]` and singleton `b = [L]` with `K != L`
        // at the `[u8; 1] × [u8; 1]` corner — the minimal non-empty
        // disjointness relation. Pins the INNER `if a[i] != b[j]`
        // gate returns without panicking on a single distinct-pair
        // check. A regression that flipped the equality direction
        // (`==` vs `!=`) would silently reject every disjoint
        // singleton pair.
        assert_u8_arrays_disjoint(&[0u8], &[1u8]);
    }

    #[test]
    fn assert_u8_arrays_disjoint_accepts_each_family_wide_substrate_pair() {
        // Runtime cross-check that the TWO (a, b) `[u8; N] × [u8; M]`
        // pairs the substrate's module-level `const _` witnesses pin
        // at COMPILE time are proper DISJOINTNESS embeddings at
        // runtime too. The pairs enforce the theorem at TWO stages
        // of the toolchain: the const witnesses fire FIRST at `cargo
        // check` (through the two module-level `const _: () =
        // assert_u8_arrays_disjoint::<N, M>(...)` lines), this
        // runtime pin catches the drift at `cargo test` as a safety
        // net. Sibling posture to
        // `assert_char_arrays_disjoint_accepts_each_family_wide_substrate_pair`
        // which sweeps the FIVE (a, b) PAIRS at the (char) row's
        // DISJOINTNESS axis; this pin sweeps the two (a, b) PAIRS
        // at the (u8) row's DISJOINTNESS axis on the SAME contract-
        // shape column.
        assert_u8_arrays_disjoint::<2, 4>(
            &crate::error::StructuralKind::HASH_DISCRIMINATORS,
            &QuoteForm::HASH_DISCRIMINATORS,
        );
        assert_u8_arrays_disjoint::<2, 2>(
            &crate::error::UnquoteForm::HASH_DISCRIMINATORS,
            &crate::error::StructuralKind::HASH_DISCRIMINATORS,
        );
    }

    #[test]
    fn assert_u8_arrays_disjoint_is_symmetric_in_argument_order() {
        // SYMMETRY PIN: swapping the two arguments produces the SAME
        // verdict. Pins that the disjointness relation is truly
        // symmetric across the two array arguments (the helper's
        // nested-sweep implementation does NOT gratuitously depend on
        // argument order). A regression that narrowed the sweep to
        // `for i in a { if !b.contains(a[i]) }` (subset-shape, not
        // disjointness-shape) would fail the swap on one direction
        // only. Runs each substrate pair BOTH ways. Sibling posture
        // to `assert_char_arrays_disjoint_is_symmetric_in_argument_order`
        // on the (char) row-dual peer.
        assert_u8_arrays_disjoint(
            &QuoteForm::HASH_DISCRIMINATORS,
            &crate::error::StructuralKind::HASH_DISCRIMINATORS,
        );
        assert_u8_arrays_disjoint(
            &crate::error::StructuralKind::HASH_DISCRIMINATORS,
            &crate::error::UnquoteForm::HASH_DISCRIMINATORS,
        );
    }

    #[test]
    #[should_panic(expected = "U8-DISJOINTNESS-VIOLATION")]
    fn assert_u8_arrays_disjoint_panics_at_runtime_on_collision() {
        // NEGATIVE PIN — U8-DISJOINTNESS-VIOLATION corner: two arrays
        // sharing a single byte MUST panic at runtime with the
        // U8-DISJOINTNESS-VIOLATION-named message. Pins the helper's
        // OWN reject arm — a regression that silently returned
        // without panicking on a cross-array collision would slip
        // through the compile-time witnesses' failure mode too. The
        // shared byte `0u8` is intentionally placed at the FIRST
        // position of BOTH arrays to pin the initial-position drift
        // mode.
        assert_u8_arrays_disjoint(&[0u8, 1u8], &[0u8, 2u8]);
    }

    #[test]
    #[should_panic(expected = "U8-DISJOINTNESS-VIOLATION")]
    fn assert_u8_arrays_disjoint_panics_at_runtime_on_terminal_a_collision() {
        // NEGATIVE PIN — terminal-position drift on the OUTER `a`
        // side: a shared byte at the LAST position of `a` MUST panic
        // — pins that the outer `while i < N` loop reaches `i = N -
        // 1` (else the terminal drift on `a` would slip through). A
        // regression that narrowed the outer sweep to `while i < N
        // - 1` (off-by-one on the OUTER bound) would silently accept
        // this pair.
        assert_u8_arrays_disjoint(&[10u8, 20u8, 30u8], &[30u8]);
    }

    #[test]
    #[should_panic(expected = "U8-DISJOINTNESS-VIOLATION")]
    fn assert_u8_arrays_disjoint_panics_at_runtime_on_terminal_b_collision() {
        // NEGATIVE PIN — terminal-position drift on the INNER `b`
        // side: a shared byte at the LAST position of `b` MUST panic
        // — pins that the inner `while j < M` loop reaches `j = M -
        // 1` (else the terminal drift on `b` would slip through). A
        // regression that narrowed the inner sweep to `while j < M
        // - 1` (off-by-one on the INNER bound) would silently accept
        // this pair. Sibling posture to the outer-terminal pin above
        // — the two pins together bind the terminal bounds on BOTH
        // loops.
        assert_u8_arrays_disjoint(&[30u8], &[10u8, 20u8, 30u8]);
    }

    #[test]
    fn assert_u8_arrays_disjoint_panic_message_names_the_helper_and_u8_disjointness_violation_axis()
    {
        // PANIC-MESSAGE PROVENANCE PIN — U8-DISJOINTNESS-VIOLATION
        // arm: the panic message MUST begin with the helper's own
        // name AND identify the failed AXIS as "U8-DISJOINTNESS-
        // VIOLATION" so downstream diagnostics route the drift back
        // to (a) the helper by string search on
        // `"assert_u8_arrays_disjoint"` and (b) the axis by string
        // search on `"U8-DISJOINTNESS-VIOLATION"`. Sibling posture to
        // `assert_char_arrays_disjoint_panic_message_names_the_helper_and_char_disjointness_violation_axis`
        // on the (char) row-dual peer's provenance pin AND to
        // `assert_u8_array_within_u8_finite_set_panic_message_names_the_helper_and_subset_violation_axis`
        // on the (u8, subset) contract-orthogonal peer's provenance
        // pin — the three pins together bind the (helper, failed-
        // axis) provenance triple across the (element-type × contract-
        // shape) 2×2 = 4-corner face's three currently-populated
        // corners with matching provenance-preservation discipline.
        // The axis-provenance string `"U8-DISJOINTNESS-VIOLATION"` is
        // chosen DISTINCT from EVERY sibling helper's axis vocabulary
        // (`"duplicate"` on the ARRAY-side pairwise-distinct sibling;
        // `"CHAR-DISJOINTNESS-VIOLATION"` on the (char) row-dual
        // DISJOINTNESS sibling; `"CHAR-SUBSET-VIOLATION"` on the
        // (char) SUBSET-embedding sibling; `"SUBSET-VIOLATION"` on
        // the (u8) finite-set SUBSET-only sibling; `"RANGE-SUBSET-
        // VIOLATION"` on the (u8) range SUBSET-only sibling;
        // `"OUT-OF-SET"` / `"SET-BYTE-MISSING"` on the (u8) covers-
        // finite-set sibling; `"OUT-OF-RANGE"` / `"MISSING"` on the
        // (u8) covers-inclusive-range sibling; `"ARITY-MISMATCH"` on
        // both (u8) `_permutes_*` compound helpers; `"SET-NOT-
        // PAIRWISE-DISTINCT"` on the (u8) SET-side well-formedness
        // sibling) so a diagnostic that names the failed axis routes
        // UNAMBIGUOUSLY to (a) this specific u8 DISJOINTNESS helper.
        let outcome = std::panic::catch_unwind(|| {
            assert_u8_arrays_disjoint(&[0u8, 1u8], &[0u8, 2u8]);
        });
        let payload = outcome.expect_err(
            "assert_u8_arrays_disjoint must panic on a cross-array \
             collision — the reject-collision arm is the sole U8-\
             DISJOINTNESS-VIOLATION failure mode of the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_u8_arrays_disjoint panic payload must be a \
                 static &str or String",
            );
        assert!(
            msg.contains("assert_u8_arrays_disjoint"),
            "assert_u8_arrays_disjoint panic message {msg:?} must \
             name the helper for provenance-preserving failure \
             diagnostics",
        );
        assert!(
            msg.contains("U8-DISJOINTNESS-VIOLATION"),
            "assert_u8_arrays_disjoint panic message {msg:?} must \
             name the failed AXIS (\"U8-DISJOINTNESS-VIOLATION\") \
             for axis-provenance-preserving failure diagnostics",
        );
    }

    // ── `assert_str_array_pairwise_distinct` — the `&'static str`
    // element-type sibling of `assert_char_array_pairwise_distinct`.
    // Sibling posture: same runtime-test surface (accept-empty,
    // accept-singleton, accept-every-family-wide-substrate-array,
    // reject-binary, reject-non-adjacent, reject-terminal, panic-
    // message-provenance) restricted to the `&'static str` element
    // type. A regression that silently weakens the helper (e.g.
    // dropping the byte-length gate, flipping `!=` to `==`, or
    // returning early on collision) is caught by the helper's OWN
    // test surface rather than only surfacing as a false-positive
    // on some future string-typed array's distinctness pin.

    #[test]
    fn assert_str_array_pairwise_distinct_accepts_the_empty_array() {
        // Empty array — vacuously pairwise distinct (no pair to
        // collide). The compile-time `const _: () =
        // assert_str_array_pairwise_distinct(&EMPTY);` would land on
        // this arm, so the runtime call MUST return normally.
        assert_str_array_pairwise_distinct::<0>(&[]);
    }

    #[test]
    fn assert_str_array_pairwise_distinct_accepts_singleton_arrays() {
        // Singleton array — vacuously pairwise distinct (only one
        // element, no pair). Cross-arity coverage on the
        // `[&'static str; 1]` corner of the const-N generic.
        assert_str_array_pairwise_distinct(&["a"]);
        assert_str_array_pairwise_distinct(&[Atom::TRUE_LITERAL]);
    }

    #[test]
    fn assert_str_array_pairwise_distinct_accepts_every_family_wide_substrate_array() {
        // Runtime cross-check that the SAME five arrays the module-
        // level `const _: () = ...` witnesses cover at COMPILE time
        // are pairwise distinct. 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 collision at `cargo
        // test`. The pair enforces the theorem at TWO stages of the
        // toolchain.
        assert_str_array_pairwise_distinct(&Atom::BOOL_LITERALS);
        assert_str_array_pairwise_distinct(&AtomKind::LABELS);
        assert_str_array_pairwise_distinct(&QuoteForm::PREFIXES);
        assert_str_array_pairwise_distinct(&QuoteForm::IAC_FORGE_TAGS);
        assert_str_array_pairwise_distinct(&QuoteForm::LABELS);
    }

    #[test]
    #[should_panic(expected = "assert_str_array_pairwise_distinct")]
    fn assert_str_array_pairwise_distinct_panics_at_runtime_on_binary_collision() {
        // NEGATIVE PIN — binary corner: a two-element array carrying
        // the same string twice MUST panic at runtime (the const-eval
        // panic surfaces normally when the function is invoked from a
        // runtime context, not just a `const _` context). Pins the
        // helper's OWN reject-collision arm — a regression that
        // silently returned without panicking on a duplicate would
        // slip through the compile-time witnesses' failure mode too.
        assert_str_array_pairwise_distinct(&["dup", "dup"]);
    }

    #[test]
    #[should_panic(expected = "assert_str_array_pairwise_distinct")]
    fn assert_str_array_pairwise_distinct_panics_at_runtime_on_non_adjacent_collision() {
        // NEGATIVE PIN — non-adjacent corner: the collision fires on
        // ANY (i, j) pair with i < j, not just the adjacent (0, 1)
        // corner. Pins the nested-loop shape of the helper — a
        // regression that walked ONLY the adjacent pairs (i.e., swept
        // `while i + 1 < N { if arr[i] == arr[i+1] { panic } … }`)
        // would silently accept `["a", "b", "a"]` (non-adjacent
        // collision at positions 0 and 2), missing the contract.
        assert_str_array_pairwise_distinct(&["a", "b", "a"]);
    }

    #[test]
    #[should_panic(expected = "assert_str_array_pairwise_distinct")]
    fn assert_str_array_pairwise_distinct_panics_at_runtime_on_terminal_collision() {
        // NEGATIVE PIN — terminal corner: the collision at the LAST
        // pair (positions N-2 and N-1) MUST also fire. Pins the outer
        // `while i < N` bound — a regression that walked `while i <
        // N - 1` (dropping the last row) would silently accept a
        // collision at the tail.
        assert_str_array_pairwise_distinct(&["a", "b", "c", "d", "d"]);
    }

    #[test]
    fn assert_str_array_pairwise_distinct_rejects_length_zero_collision() {
        // POSITIVE-ORTHOGONAL PIN — the byte-length gate at
        // `str_bytes_equal`: two empty strings must be flagged as
        // EQUAL (both are the zero-length byte sequence). A
        // regression that mishandled `a.len() == 0 && b.len() == 0`
        // (e.g. by returning `false` when both lengths are 0, or by
        // panicking on the zero-length index) would silently accept
        // a `["", ""]` duplicate. Pins the vacuous-length corner of
        // the byte-equality helper via the outer helper's runtime
        // panic surface.
        let outcome = std::panic::catch_unwind(|| {
            assert_str_array_pairwise_distinct(&["", ""]);
        });
        outcome.expect_err(
            "assert_str_array_pairwise_distinct must panic on a \
             duplicate at the zero-length string corner — the \
             `str_bytes_equal` helper's `a.len() == b.len()` gate \
             holds vacuously at length 0, so the byte-walk falls \
             through to a positive equality verdict",
        );
    }

    #[test]
    fn assert_str_array_pairwise_distinct_accepts_prefix_pair_without_collision() {
        // POSITIVE-ORTHOGONAL PIN — the byte-length gate at
        // `str_bytes_equal`: two strings where one is a strict
        // prefix of the other must be flagged as DISTINCT. A
        // regression that dropped the `a.len() != b.len()` gate
        // (e.g. by comparing bytes only up to the shorter length)
        // would silently accept `["ab", "abc"]` as equal. This pin
        // fires the outer helper on a prefix pair; the runtime call
        // MUST return normally.
        assert_str_array_pairwise_distinct(&["ab", "abc"]);
        assert_str_array_pairwise_distinct(&["", "a"]);
    }

    #[test]
    fn assert_str_array_pairwise_distinct_panic_message_names_the_helper() {
        // PANIC-MESSAGE PROVENANCE PIN: the panic message MUST begin
        // with the helper's own name so downstream diagnostics
        // (`cargo check` const-eval error output, test-suite failure
        // reports) route the drift back to the helper by string
        // search — the family-wide contract's failure mode surfaces
        // as an identifiable panic-message prefix rather than as an
        // opaque const-eval error. Sibling posture to the runtime
        // pairwise-distinctness tests that name the ARRAY in their
        // failure message; this pin names the HELPER.
        let outcome = std::panic::catch_unwind(|| {
            assert_str_array_pairwise_distinct(&["x", "x"]);
        });
        let payload = outcome.expect_err(
            "assert_str_array_pairwise_distinct must panic on a \
             duplicate — the reject-collision arm is the point of \
             the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_str_array_pairwise_distinct panic payload \
                 must be a static &str or String",
            );
        assert!(
            msg.contains("assert_str_array_pairwise_distinct"),
            "assert_str_array_pairwise_distinct panic message \
             {msg:?} must name the helper for provenance-preserving \
             failure diagnostics",
        );
    }

    #[test]
    fn assert_str_array_all_nonempty_accepts_the_empty_array() {
        // Empty array — vacuously all-nonempty (no entry to be empty).
        // The compile-time `const _: () = assert_str_array_all_nonempty
        // (&EMPTY);` would land on this arm, so the runtime call MUST
        // return normally.
        assert_str_array_all_nonempty::<0>(&[]);
    }

    #[test]
    fn assert_str_array_all_nonempty_accepts_nonempty_singleton_arrays() {
        // Singleton array carrying a nonempty entry — the sole entry
        // clears the length-gate. Cross-arity coverage on the
        // `[&'static str; 1]` corner of the const-N generic.
        assert_str_array_all_nonempty(&["a"]);
        assert_str_array_all_nonempty(&[Atom::TRUE_LITERAL]);
    }

    #[test]
    fn assert_str_array_all_nonempty_accepts_every_family_wide_substrate_array() {
        // Runtime cross-check that the SAME five arrays the module-
        // level `const _: () = ...` witnesses cover at COMPILE time
        // are all-nonempty. Sibling posture to the runtime
        // `_pairwise_distinct` cross-check above — the two together
        // pin BOTH the INJECTIVITY axis AND the NONEMPTY-CARDINALITY-
        // LOWER-BOUND axis on the SAME five arrays, at TWO stages of
        // the toolchain (compile-time `const _` line + this runtime
        // safety-net).
        assert_str_array_all_nonempty(&Atom::BOOL_LITERALS);
        assert_str_array_all_nonempty(&AtomKind::LABELS);
        assert_str_array_all_nonempty(&QuoteForm::PREFIXES);
        assert_str_array_all_nonempty(&QuoteForm::IAC_FORGE_TAGS);
        assert_str_array_all_nonempty(&QuoteForm::LABELS);
    }

    #[test]
    #[should_panic(expected = "assert_str_array_all_nonempty")]
    fn assert_str_array_all_nonempty_panics_at_runtime_on_singleton_empty() {
        // NEGATIVE PIN — singleton corner: a one-element array
        // carrying the empty string MUST panic. Pins the helper's own
        // reject-empty arm on the smallest possible array shape.
        assert_str_array_all_nonempty(&[""]);
    }

    #[test]
    #[should_panic(expected = "assert_str_array_all_nonempty")]
    fn assert_str_array_all_nonempty_panics_at_runtime_on_head_empty() {
        // NEGATIVE PIN — head corner: the empty entry at position 0
        // MUST fire even when subsequent entries are nonempty. Pins
        // the outer sweep's inclusive-start behavior — a regression
        // that walked `while i < N { … i += 1 }` from an off-by-one
        // start (`i = 1`) would silently accept a leading `""` entry.
        assert_str_array_all_nonempty(&["", "a", "b"]);
    }

    #[test]
    #[should_panic(expected = "assert_str_array_all_nonempty")]
    fn assert_str_array_all_nonempty_panics_at_runtime_on_interior_empty() {
        // NEGATIVE PIN — interior corner: the empty entry at a
        // strictly-interior position MUST fire. Pins the outer
        // sweep's non-early-exit behavior at the head-arm — a
        // regression that returned `Ok` on the first nonempty entry
        // (bailing out of the sweep prematurely) would silently
        // accept an interior `""` entry.
        assert_str_array_all_nonempty(&["a", "", "b"]);
    }

    #[test]
    #[should_panic(expected = "assert_str_array_all_nonempty")]
    fn assert_str_array_all_nonempty_panics_at_runtime_on_tail_empty() {
        // NEGATIVE PIN — tail corner: the empty entry at position
        // `N - 1` MUST fire. Pins the outer `while i < N` upper bound
        // — a regression that walked `while i < N - 1` (dropping the
        // last slot) would silently accept a trailing `""` entry.
        assert_str_array_all_nonempty(&["a", "b", "c", ""]);
    }

    #[test]
    fn assert_str_array_all_nonempty_rejects_the_all_empty_array() {
        // POSITIVE-ORTHOGONAL PIN — the ALL-empty corner: an array
        // whose every entry is `""` fires the helper on the FIRST
        // entry (the head-arm). Confirms the helper does not silently
        // accept an array whose every entry alias-collapses onto the
        // zero-length byte sequence — a corner that composes with
        // `assert_str_array_pairwise_distinct_rejects_length_zero_
        // collision` (that pin rejects `["", ""]` on the pairwise-
        // distinctness axis; this pin rejects `["", ""]` on the
        // NONEMPTY axis — the two contracts pin the `""`-repeat
        // failure mode at BOTH the INJECTIVITY axis AND the
        // NONEMPTY axis).
        let outcome = std::panic::catch_unwind(|| {
            assert_str_array_all_nonempty(&["", ""]);
        });
        outcome.expect_err(
            "assert_str_array_all_nonempty must panic on an array \
             whose every entry is `\"\"` — the head-arm fires on the \
             zero-length entry at position 0",
        );
    }

    #[test]
    fn assert_str_array_all_nonempty_panic_message_names_the_helper_and_axis() {
        // PANIC-MESSAGE PROVENANCE PIN: the panic message MUST begin
        // with the helper's own name AND name the failed axis as
        // `"STR-EMPTY-ENTRY"` (chosen DISTINCT from every sibling
        // helper's axis vocabulary: `"duplicate"` on the pairwise-
        // distinct sibling; `"STR-DISJOINTNESS-VIOLATION"` on the
        // arrays-disjoint sibling; `"STR-SUBSET-VIOLATION"` on the
        // within-finite-set sibling) so a diagnostic that names the
        // failed axis routes UNAMBIGUOUSLY to THIS specific helper.
        let outcome = std::panic::catch_unwind(|| {
            assert_str_array_all_nonempty(&[""]);
        });
        let payload = outcome.expect_err(
            "assert_str_array_all_nonempty must panic on an empty \
             entry — the reject-empty arm is the point of the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_str_array_all_nonempty panic payload must be \
                 a static &str or String",
            );
        assert!(
            msg.contains("assert_str_array_all_nonempty"),
            "assert_str_array_all_nonempty panic message {msg:?} must \
             name the helper for provenance-preserving failure \
             diagnostics",
        );
        assert!(
            msg.contains("STR-EMPTY-ENTRY"),
            "assert_str_array_all_nonempty panic message {msg:?} must \
             name the failed axis as `STR-EMPTY-ENTRY` DISTINCT from \
             every sibling helper's axis vocabulary",
        );
        // Trailing gate — the sibling `_all_ascii` axis vocabulary
        // (`STR-NON-ASCII-ENTRY`) must NOT appear in the NONEMPTY
        // helper's panic message. Guards against a copy-paste
        // regression that drifted the two helpers' axis-provenance
        // strings onto the same slot.
        assert!(
            !msg.contains("STR-NON-ASCII-ENTRY"),
            "assert_str_array_all_nonempty panic message {msg:?} \
             must NOT name the ASCII-sibling axis — the two per-\
             entry helpers must keep their axis-provenance strings \
             lexically distinct",
        );
    }

    // ── assert_str_array_all_ascii — the per-entry ASCII-BYTE-RANGE
    // gate sibling of `assert_str_array_all_nonempty` on the
    // (`&'static str`) row's (per-entry × contract-shape) axis. ──

    #[test]
    fn assert_str_array_all_ascii_accepts_the_empty_array() {
        // Empty array — vacuously all-ASCII (no entry to fail the
        // byte-range gate). The compile-time `const _: () =
        // assert_str_array_all_ascii(&EMPTY);` would land on this
        // arm, so the runtime call MUST return normally.
        assert_str_array_all_ascii::<0>(&[]);
    }

    #[test]
    fn assert_str_array_all_ascii_accepts_ascii_singleton_arrays() {
        // Singleton array carrying an all-ASCII entry — the sole
        // entry clears the byte-range gate. Cross-arity coverage on
        // the `[&'static str; 1]` corner of the const-N generic.
        assert_str_array_all_ascii(&["a"]);
        assert_str_array_all_ascii(&[Atom::TRUE_LITERAL]);
    }

    #[test]
    fn assert_str_array_all_ascii_accepts_the_empty_entry() {
        // Vacuous-inner-loop corner — a zero-length entry has no
        // byte to fail the range gate, so the helper MUST accept.
        // Positive-orthogonal pin against the NONEMPTY sibling — a
        // regression that fused the two contracts into one (rejecting
        // `""` on the ASCII sweep) would fail this pin. The two
        // per-entry contracts stay independent axes on the SAME row.
        assert_str_array_all_ascii(&[""]);
        assert_str_array_all_ascii(&["", "a", ""]);
    }

    #[test]
    fn assert_str_array_all_ascii_accepts_every_family_wide_substrate_array() {
        // Runtime cross-check that the SAME five arrays the module-
        // level `const _: () = ...` witnesses cover at COMPILE time
        // are all-ASCII. Sibling posture to the runtime
        // `_pairwise_distinct` + `_all_nonempty` cross-checks — the
        // three together pin BOTH the INJECTIVITY axis AND the
        // NONEMPTY-CARDINALITY-LOWER-BOUND axis AND the ASCII-BYTE-
        // RANGE axis on the SAME five arrays, at TWO stages of the
        // toolchain (compile-time `const _` line + this runtime
        // safety-net).
        assert_str_array_all_ascii(&Atom::BOOL_LITERALS);
        assert_str_array_all_ascii(&AtomKind::LABELS);
        assert_str_array_all_ascii(&QuoteForm::PREFIXES);
        assert_str_array_all_ascii(&QuoteForm::IAC_FORGE_TAGS);
        assert_str_array_all_ascii(&QuoteForm::LABELS);
    }

    #[test]
    fn assert_str_array_all_ascii_accepts_the_ascii_boundary_byte() {
        // Boundary-inclusive pin on the ASCII byte range's upper
        // edge — byte `0x7F` (DEL, the last ASCII byte) MUST be
        // accepted. Guards against an off-by-one regression that
        // walked `bytes[j] >= 0x7F` and spuriously rejected the
        // sole `0x7F` character. Together with the negative pins
        // below (which fire on `0x80` — the first non-ASCII byte),
        // the two pin the byte-range boundary at both edges.
        assert_str_array_all_ascii(&["\u{7F}"]);
    }

    #[test]
    #[should_panic(expected = "assert_str_array_all_ascii")]
    fn assert_str_array_all_ascii_panics_at_runtime_on_singleton_non_ascii() {
        // NEGATIVE PIN — singleton corner: a one-element array
        // carrying a non-ASCII entry MUST panic. Pins the helper's
        // own reject-non-ascii arm on the smallest possible array
        // shape. The two-byte UTF-8 sequence `"é"` (0xC3 0xA9) fires
        // on the leading high-byte `0xC3`.
        assert_str_array_all_ascii(&["é"]);
    }

    #[test]
    #[should_panic(expected = "assert_str_array_all_ascii")]
    fn assert_str_array_all_ascii_panics_at_runtime_on_head_non_ascii() {
        // NEGATIVE PIN — head corner: the non-ASCII entry at
        // position 0 MUST fire even when subsequent entries are
        // ASCII. Pins the outer sweep's inclusive-start behavior
        // — a regression that walked `while i < N { … i += 1 }`
        // from an off-by-one start (`i = 1`) would silently accept
        // a leading non-ASCII entry.
        assert_str_array_all_ascii(&["café", "a", "b"]);
    }

    #[test]
    #[should_panic(expected = "assert_str_array_all_ascii")]
    fn assert_str_array_all_ascii_panics_at_runtime_on_interior_non_ascii() {
        // NEGATIVE PIN — interior corner: the non-ASCII entry at a
        // strictly-interior position MUST fire. Pins the outer
        // sweep's non-early-exit behavior at the head-arm — a
        // regression that returned `Ok` on the first ASCII entry
        // (bailing out of the sweep prematurely) would silently
        // accept an interior non-ASCII entry.
        assert_str_array_all_ascii(&["a", "café", "b"]);
    }

    #[test]
    #[should_panic(expected = "assert_str_array_all_ascii")]
    fn assert_str_array_all_ascii_panics_at_runtime_on_tail_non_ascii() {
        // NEGATIVE PIN — tail corner: the non-ASCII entry at
        // position `N - 1` MUST fire. Pins the outer `while i < N`
        // upper bound — a regression that walked `while i < N - 1`
        // (dropping the last slot) would silently accept a trailing
        // non-ASCII entry.
        assert_str_array_all_ascii(&["a", "b", "c", "café"]);
    }

    #[test]
    #[should_panic(expected = "assert_str_array_all_ascii")]
    fn assert_str_array_all_ascii_panics_at_runtime_on_interior_byte_non_ascii() {
        // NEGATIVE PIN — interior-byte corner: the non-ASCII byte at
        // a strictly-interior position WITHIN a single entry MUST
        // fire. Pins the inner `while j < bytes.len()` sweep's
        // non-early-exit behavior — a regression that returned on
        // the first ASCII byte within an entry (bailing out of the
        // inner sweep prematurely at `bytes[0] <= 0x7F`) would
        // silently accept a non-ASCII byte in a strictly-interior
        // slot of the entry.
        assert_str_array_all_ascii(&["asdéf"]);
    }

    #[test]
    #[should_panic(expected = "assert_str_array_all_ascii")]
    fn assert_str_array_all_ascii_panics_on_the_first_non_ascii_byte() {
        // NEGATIVE PIN — first-non-ASCII-byte boundary: byte `0x80`
        // (the smallest non-ASCII byte) MUST fire. Guards against
        // an off-by-one regression that walked `bytes[j] > 0x80`
        // (dropping `0x80` from the reject set). Together with
        // `_accepts_the_ascii_boundary_byte` (which pins `0x7F`
        // acceptance), the two pin the byte-range boundary at both
        // edges. UTF-8 lowest continuation byte in isolation is not
        // well-formed, so we use `"\u{80}"` — which is the two-byte
        // sequence `0xC2 0x80` — either byte is `> 0x7F` so the
        // sweep fires on the leading byte `0xC2` regardless.
        assert_str_array_all_ascii(&["\u{80}"]);
    }

    #[test]
    fn assert_str_array_all_ascii_rejects_the_all_non_ascii_array() {
        // POSITIVE-ORTHOGONAL PIN — the ALL-non-ASCII corner: an
        // array whose every entry contains a non-ASCII byte fires
        // the helper on the FIRST entry (the head-arm). Confirms
        // the helper does not silently accept an array whose every
        // entry ships non-ASCII bytes.
        let outcome = std::panic::catch_unwind(|| {
            assert_str_array_all_ascii(&["café", "über"]);
        });
        outcome.expect_err(
            "assert_str_array_all_ascii must panic on an array whose \
             every entry carries a non-ASCII byte — the head-arm \
             fires on the first non-ASCII byte at position 0",
        );
    }

    #[test]
    fn assert_str_array_all_ascii_panic_message_names_the_helper_and_axis() {
        // PANIC-MESSAGE PROVENANCE PIN: the panic message MUST
        // begin with the helper's own name AND name the failed axis
        // as `"STR-NON-ASCII-ENTRY"` (chosen DISTINCT from every
        // sibling helper's axis vocabulary: `"duplicate"` on the
        // pairwise-distinct sibling; `"STR-EMPTY-ENTRY"` on the
        // per-entry NONEMPTY sibling; `"STR-DISJOINTNESS-VIOLATION"`
        // on the arrays-disjoint sibling; `"STR-SUBSET-VIOLATION"`
        // on the within-finite-set sibling) so a diagnostic that
        // names the failed axis routes UNAMBIGUOUSLY to THIS
        // specific ASCII helper.
        let outcome = std::panic::catch_unwind(|| {
            assert_str_array_all_ascii(&["é"]);
        });
        let payload = outcome.expect_err(
            "assert_str_array_all_ascii must panic on a non-ASCII \
             entry — the reject-non-ascii arm is the point of the \
             helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_str_array_all_ascii panic payload must be a \
                 static &str or String",
            );
        assert!(
            msg.contains("assert_str_array_all_ascii"),
            "assert_str_array_all_ascii panic message {msg:?} must \
             name the helper for provenance-preserving failure \
             diagnostics",
        );
        assert!(
            msg.contains("STR-NON-ASCII-ENTRY"),
            "assert_str_array_all_ascii panic message {msg:?} must \
             name the failed axis as `STR-NON-ASCII-ENTRY` DISTINCT \
             from every sibling helper's axis vocabulary",
        );
        assert!(
            !msg.contains("STR-EMPTY-ENTRY"),
            "assert_str_array_all_ascii panic message {msg:?} must \
             NOT name the NONEMPTY-sibling axis — the two per-entry \
             helpers must keep their axis-provenance strings \
             lexically distinct",
        );
    }

    #[test]
    fn str_bytes_equal_accepts_the_empty_pair() {
        // Direct pin on `str_bytes_equal`'s zero-length corner —
        // both inputs are the empty byte sequence, so the helper
        // MUST return `true`. Verifies the `a.len() == b.len()`
        // gate does not spuriously reject at `len == 0`.
        assert!(str_bytes_equal("", ""));
    }

    #[test]
    fn str_bytes_equal_rejects_the_prefix_pair() {
        // Direct pin on `str_bytes_equal`'s length-gate: a strict
        // prefix pair MUST be rejected. Guards against a regression
        // that dropped the length gate and compared bytes only up
        // to the shorter length.
        assert!(!str_bytes_equal("ab", "abc"));
        assert!(!str_bytes_equal("abc", "ab"));
    }

    #[test]
    fn str_bytes_equal_accepts_the_identical_pair() {
        // Direct pin on `str_bytes_equal`'s positive-match arm —
        // two identical strings MUST be flagged as equal at every
        // canonical shape the substrate carries (bool literal,
        // atomic-kind label, quote-family prefix). Sibling posture
        // to the `_accepts_every_family_wide_substrate_array` pin
        // on the outer helper: this pin fires the inner helper on
        // the SAME string values that back the outer witnesses'
        // per-array entries.
        assert!(str_bytes_equal(Atom::TRUE_LITERAL, Atom::TRUE_LITERAL));
        assert!(str_bytes_equal(
            AtomKind::SYMBOL_LABEL,
            AtomKind::SYMBOL_LABEL,
        ));
        assert!(str_bytes_equal(
            QuoteForm::QUOTE_PREFIX,
            QuoteForm::QUOTE_PREFIX,
        ));
    }

    #[test]
    fn str_bytes_equal_rejects_the_distinct_pair() {
        // Direct pin on `str_bytes_equal`'s reject-arm — two
        // distinct family-wide substrate strings MUST be flagged
        // as unequal. Guards against a regression that returned
        // `true` unconditionally (which would silently pass every
        // caller through the collision arm).
        assert!(!str_bytes_equal(Atom::TRUE_LITERAL, Atom::FALSE_LITERAL,));
        assert!(!str_bytes_equal(
            AtomKind::SYMBOL_LABEL,
            AtomKind::KEYWORD_LABEL,
        ));
        assert!(!str_bytes_equal(
            QuoteForm::QUOTE_PREFIX,
            QuoteForm::QUASIQUOTE_PREFIX,
        ));
    }

    // ── `assert_str_arrays_disjoint` — the `&'static str` element-
    // type sibling of `assert_char_arrays_disjoint` and
    // `assert_u8_arrays_disjoint`. Sibling posture: same runtime-test
    // surface (accept-both-empty, accept-either-side-empty, accept-
    // disjoint-singletons, accept-every-family-wide-substrate-pair,
    // symmetric-in-argument-order, reject-cross-collision, reject-
    // terminal-a-collision, reject-terminal-b-collision, panic-message-
    // provenance) restricted to the `&'static str` element type. A
    // regression that silently weakens the helper (e.g. flipping
    // `str_bytes_equal` polarity, dropping the outer OR inner sweep,
    // or returning early on collision) is caught by the helper's OWN
    // test surface rather than only surfacing as a false-positive on
    // some future disjoint `[&'static str; N] × [&'static str; M]`
    // pair's compound pin.

    #[test]
    fn assert_str_arrays_disjoint_accepts_both_empty_arrays() {
        // Both arrays empty at the `[&'static str; 0] × [&'static str; 0]`
        // corner — vacuously disjoint (no `(i, j)` pair exists to
        // test). The compile-time `const _: () =
        // assert_str_arrays_disjoint(&[], &[]);` would land on this
        // arm, so the runtime call MUST return normally. Turbofish
        // binding required because there's no other cue for the const
        // parameters on the empty array literals. Sibling posture to
        // `assert_char_arrays_disjoint_accepts_both_empty_arrays` and
        // `assert_u8_arrays_disjoint_accepts_both_empty_arrays` on
        // the (char) and (u8) row-dual peers — the three share the
        // trivial-arity arm across the (element-type × contract-shape)
        // 3-row × (disjointness)-column face.
        assert_str_arrays_disjoint::<0, 0>(&[], &[]);
    }

    #[test]
    fn assert_str_arrays_disjoint_accepts_either_side_empty() {
        // Either side empty at the `[&'static str; 0] × [&'static str; M]`
        // OR `[&'static str; N] × [&'static str; 0]` corners —
        // vacuously disjoint (the OUTER `while i < N` OR the INNER
        // `while j < M` sweep is a no-op). Pins BOTH SIDES of the
        // (a-empty, b-empty) 2-corner sub-face on the trivial-arity
        // axis so a regression that narrowed the sweep to only-a-non-
        // empty OR only-b-non-empty fails HERE at the empty-side
        // corner rather than at a distant false-positive.
        assert_str_arrays_disjoint::<0, 3>(&[], &["a", "b", "c"]);
        assert_str_arrays_disjoint::<3, 0>(&["a", "b", "c"], &[]);
    }

    #[test]
    fn assert_str_arrays_disjoint_accepts_disjoint_singletons() {
        // Singleton `a = [K]` and singleton `b = [L]` with `K != L`
        // at the `[&'static str; 1] × [&'static str; 1]` corner — the
        // minimal non-empty disjointness relation. Pins the INNER
        // `if str_bytes_equal(a[i], b[j])` gate returns without
        // panicking on a single distinct-pair check. A regression
        // that flipped the equality direction (`!=` vs `==` on the
        // byte-equality delegate) would silently reject every
        // disjoint singleton pair.
        assert_str_arrays_disjoint(&["a"], &["b"]);
    }

    #[test]
    fn assert_str_arrays_disjoint_accepts_each_family_wide_substrate_pair() {
        // Runtime cross-check that the FOUR (a, b) `[&'static str; N]
        // × [&'static str; M]` pairs the substrate's module-level
        // `const _` witnesses pin at COMPILE time are proper
        // DISJOINTNESS embeddings at runtime too. The pairs enforce
        // the theorem at TWO stages of the toolchain: the const
        // witnesses fire FIRST at `cargo check` (through the four
        // module-level `const _: () = assert_str_arrays_disjoint::
        // <N, M>(...)` lines), this runtime pin catches the drift at
        // `cargo test` as a safety net. Sibling posture to
        // `assert_char_arrays_disjoint_accepts_each_family_wide_substrate_pair`
        // which sweeps the FIVE (a, b) PAIRS at the (char) row and
        // `assert_u8_arrays_disjoint_accepts_each_family_wide_substrate_pair`
        // which sweeps the TWO (a, b) PAIRS at the (u8) row; this
        // pin sweeps the four (a, b) PAIRS at the (`&'static str`)
        // row on the SAME contract-shape column.
        assert_str_arrays_disjoint::<4, 4>(&QuoteForm::PREFIXES, &QuoteForm::LABELS);
        assert_str_arrays_disjoint::<4, 4>(&QuoteForm::PREFIXES, &QuoteForm::IAC_FORGE_TAGS);
        assert_str_arrays_disjoint::<4, 6>(&QuoteForm::PREFIXES, &AtomKind::LABELS);
        assert_str_arrays_disjoint::<6, 4>(&AtomKind::LABELS, &QuoteForm::LABELS);
    }

    #[test]
    fn assert_str_arrays_disjoint_is_symmetric_in_argument_order() {
        // SYMMETRY PIN: swapping the two arguments produces the SAME
        // verdict. Pins that the disjointness relation is truly
        // symmetric across the two array arguments (the helper's
        // nested-sweep implementation does NOT gratuitously depend on
        // argument order). A regression that narrowed the sweep to
        // `for i in a { if !b.contains(a[i]) }` (subset-shape, not
        // disjointness-shape) would fail the swap on one direction
        // only. Runs each substrate pair BOTH ways. Sibling posture
        // to `assert_char_arrays_disjoint_is_symmetric_in_argument_order`
        // on the (char) row-dual peer and
        // `assert_u8_arrays_disjoint_is_symmetric_in_argument_order`
        // on the (u8) row-dual peer.
        assert_str_arrays_disjoint(&QuoteForm::LABELS, &QuoteForm::PREFIXES);
        assert_str_arrays_disjoint(&QuoteForm::IAC_FORGE_TAGS, &QuoteForm::PREFIXES);
        assert_str_arrays_disjoint(&AtomKind::LABELS, &QuoteForm::PREFIXES);
        assert_str_arrays_disjoint(&QuoteForm::LABELS, &AtomKind::LABELS);
    }

    #[test]
    #[should_panic(expected = "STR-DISJOINTNESS-VIOLATION")]
    fn assert_str_arrays_disjoint_panics_at_runtime_on_collision() {
        // NEGATIVE PIN — STR-DISJOINTNESS-VIOLATION corner: two arrays
        // sharing a single string MUST panic at runtime with the
        // STR-DISJOINTNESS-VIOLATION-named message. Pins the helper's
        // OWN reject arm — a regression that silently returned
        // without panicking on a cross-array collision would slip
        // through the compile-time witnesses' failure mode too. The
        // shared string `"dup"` is intentionally placed at the FIRST
        // position of BOTH arrays to pin the initial-position drift
        // mode.
        assert_str_arrays_disjoint(&["dup", "x"], &["dup", "y"]);
    }

    #[test]
    #[should_panic(expected = "STR-DISJOINTNESS-VIOLATION")]
    fn assert_str_arrays_disjoint_panics_at_runtime_on_terminal_a_collision() {
        // NEGATIVE PIN — terminal-position drift on the OUTER `a`
        // side: a shared string at the LAST position of `a` MUST
        // panic — pins that the outer `while i < N` loop reaches
        // `i = N - 1` (else the terminal drift on `a` would slip
        // through). A regression that narrowed the outer sweep to
        // `while i < N - 1` (off-by-one on the OUTER bound) would
        // silently accept this pair.
        assert_str_arrays_disjoint(&["a", "b", "shared"], &["shared"]);
    }

    #[test]
    #[should_panic(expected = "STR-DISJOINTNESS-VIOLATION")]
    fn assert_str_arrays_disjoint_panics_at_runtime_on_terminal_b_collision() {
        // NEGATIVE PIN — terminal-position drift on the INNER `b`
        // side: a shared string at the LAST position of `b` MUST
        // panic — pins that the inner `while j < M` loop reaches
        // `j = M - 1` (else the terminal drift on `b` would slip
        // through). A regression that narrowed the inner sweep to
        // `while j < M - 1` (off-by-one on the INNER bound) would
        // silently accept this pair. Sibling posture to the outer-
        // terminal pin above — the two pins together bind the
        // terminal bounds on BOTH loops.
        assert_str_arrays_disjoint(&["shared"], &["a", "b", "shared"]);
    }

    #[test]
    #[should_panic(expected = "STR-DISJOINTNESS-VIOLATION")]
    fn assert_str_arrays_disjoint_panics_at_runtime_on_length_zero_collision() {
        // NEGATIVE PIN — the byte-length gate at `str_bytes_equal`
        // must classify TWO empty strings across the (a, b) boundary
        // as equal too (both are the zero-length byte sequence). A
        // regression that treated `""` as never-colliding across the
        // arrays would silently accept the empty-string collision.
        // Delegated to the SAME `str_bytes_equal` helper the
        // pairwise-distinct sibling uses — this pin exercises the
        // cross-array direction of the same zero-length arm.
        assert_str_arrays_disjoint(&[""], &[""]);
    }

    #[test]
    fn assert_str_arrays_disjoint_accepts_prefix_pair_without_collision() {
        // POSITIVE-ORTHOGONAL PIN — the byte-length gate at
        // `str_bytes_equal` across the (a, b) boundary: two arrays
        // where entries of one are strict prefixes of entries of the
        // other but no full-length equal pair exists must be flagged
        // as DISJOINT. A regression that dropped the
        // `a.len() != b.len()` gate (e.g. by comparing bytes only up
        // to the shorter length) would silently reject
        // `(["ab"], ["abc"])` as a collision. Sibling to the (str,
        // pairwise-distinct) sibling's `_accepts_prefix_pair_without_
        // collision` pin — the two share the byte-length-gate
        // theorem across (intra-array, inter-array) row-dual peers.
        assert_str_arrays_disjoint(&["ab"], &["abc"]);
        assert_str_arrays_disjoint(&["abc"], &["ab"]);
        assert_str_arrays_disjoint(&[""], &["a"]);
    }

    #[test]
    fn assert_str_arrays_disjoint_panic_message_names_the_helper_and_str_disjointness_violation_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — STR-DISJOINTNESS-VIOLATION
        // arm: the panic message MUST begin with the helper's own
        // name AND identify the failed AXIS as "STR-DISJOINTNESS-
        // VIOLATION" so downstream diagnostics route the drift back
        // to (a) the helper by string search on
        // `"assert_str_arrays_disjoint"` and (b) the axis by string
        // search on `"STR-DISJOINTNESS-VIOLATION"`. Sibling posture
        // to `assert_char_arrays_disjoint_panic_message_names_the_helper_and_char_disjointness_violation_axis`
        // on the (char) row-dual peer's provenance pin AND to
        // `assert_u8_arrays_disjoint_panic_message_names_the_helper_and_u8_disjointness_violation_axis`
        // on the (u8) row-dual peer's provenance pin — the three
        // pins together bind the (helper, failed-axis) provenance
        // triple across the (element-type ∈ {char, u8, `&'static
        // str`}) × (disjointness)-column 3-row face with matching
        // provenance-preservation discipline. The axis-provenance
        // string `"STR-DISJOINTNESS-VIOLATION"` is chosen DISTINCT
        // from EVERY sibling helper's axis vocabulary (`"duplicate"`
        // on the (str) ARRAY-side pairwise-distinct sibling;
        // `"CHAR-DISJOINTNESS-VIOLATION"` on the (char) row-dual
        // DISJOINTNESS sibling; `"U8-DISJOINTNESS-VIOLATION"` on
        // the (u8) row-dual DISJOINTNESS sibling; `"CHAR-SUBSET-
        // VIOLATION"` on the (char) SUBSET-embedding sibling;
        // `"SUBSET-VIOLATION"` on the (u8) finite-set SUBSET-only
        // sibling; `"RANGE-SUBSET-VIOLATION"` on the (u8) range
        // SUBSET-only sibling; `"OUT-OF-SET"` / `"SET-BYTE-MISSING"`
        // on the (u8) covers-finite-set sibling; `"OUT-OF-RANGE"` /
        // `"MISSING"` on the (u8) covers-inclusive-range sibling;
        // `"ARITY-MISMATCH"` on both (u8) `_permutes_*` compound
        // helpers; `"SET-NOT-PAIRWISE-DISTINCT"` on the (u8) SET-side
        // well-formedness sibling) so a diagnostic that names the
        // failed axis routes UNAMBIGUOUSLY to (a) this specific
        // `&'static str` DISJOINTNESS helper.
        let outcome = std::panic::catch_unwind(|| {
            assert_str_arrays_disjoint(&["dup", "x"], &["dup", "y"]);
        });
        let payload = outcome.expect_err(
            "assert_str_arrays_disjoint must panic on a cross-array \
             collision — the reject-collision arm is the sole STR-\
             DISJOINTNESS-VIOLATION failure mode of the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_str_arrays_disjoint panic payload must be a \
                 static &str or String",
            );
        assert!(
            msg.contains("assert_str_arrays_disjoint"),
            "assert_str_arrays_disjoint panic message {msg:?} must \
             name the helper for provenance-preserving failure \
             diagnostics",
        );
        assert!(
            msg.contains("STR-DISJOINTNESS-VIOLATION"),
            "assert_str_arrays_disjoint panic message {msg:?} must \
             name the failed AXIS (\"STR-DISJOINTNESS-VIOLATION\") \
             for axis-provenance-preserving failure diagnostics",
        );
    }

    // ── `assert_str_array_within_str_finite_set` — the `&'static str`
    // element-type sibling of `assert_char_array_within_char_finite_
    // set` and `assert_u8_array_within_u8_finite_set` on the (element-
    // type) axis of the (element-type × contract-shape) matrix at the
    // (subset-embedding) column. Sibling posture: same runtime-test
    // surface (accept-empty, accept-singleton, accept-arr-equals-set,
    // accept-each-family-wide-substrate-subset, accept-repeated-array-
    // entries, reject-out-of-set, reject-terminal-out-of-set, panic-
    // message-provenance, delegated-set-well-formedness) restricted to
    // the `&'static str` element type. A regression that silently
    // weakens the helper (e.g. flipping the found flag, dropping the
    // outer `i` loop, or short-circuiting on the first-position match)
    // is caught by the helper's OWN test surface rather than only
    // surfacing as a false-positive on some future `[&'static str; N]`
    // sub-vocabulary array's subset-embedding pin.

    #[test]
    fn assert_str_array_within_str_finite_set_accepts_the_empty_array_within_any_set() {
        // Empty array `arr = []` at the `[&'static str; 0]` corner —
        // vacuously a subset of every set (no `i` position exists to
        // test). Cross-arity coverage on the trivial ARRAY corner of
        // the const-N generic across three witness-set widths (empty,
        // singleton, multi-element) to pin the helper's OUTER-sweep
        // arm across the whole (`N == 0` × `M`) axis. Turbofish
        // binding required because there's no other cue for the const
        // parameters on the empty array literal. Sibling posture to
        // `assert_char_array_within_char_finite_set_accepts_the_empty_array_within_any_set`
        // and `assert_u8_array_within_u8_finite_set_accepts_the_empty_array_within_any_set`
        // on the (char) + (u8) row-dual peers of the SUBSET-EMBEDDING
        // helper — the three share the trivial-arity arm across the
        // element-type column.
        assert_str_array_within_str_finite_set::<0, 0>(&[], &[]);
        assert_str_array_within_str_finite_set::<0, 1>(&[], &["x"]);
        assert_str_array_within_str_finite_set::<0, 3>(&[], &["a", "b", "c"]);
    }

    #[test]
    fn assert_str_array_within_str_finite_set_accepts_singleton_array_when_str_in_set() {
        // Singleton array `arr = [K]` at the `[&'static str; 1]`
        // corner MUST pass when `K ∈ set`. Cross-position coverage:
        // the str can sit at the FIRST, MIDDLE, or LAST position of
        // the `set` — pins the INNER `while j < M` sweep terminates
        // at the first-match position rather than always at position
        // `0` OR always at position `M - 1`. A regression that
        // narrowed the inner sweep to `j == 0` would silently reject
        // singleton arrays hitting non-first set positions.
        assert_str_array_within_str_finite_set::<1, 3>(&["a"], &["a", "b", "c"]);
        assert_str_array_within_str_finite_set::<1, 3>(&["b"], &["a", "b", "c"]);
        assert_str_array_within_str_finite_set::<1, 3>(&["c"], &["a", "b", "c"]);
    }

    #[test]
    fn assert_str_array_within_str_finite_set_accepts_arr_equals_set() {
        // Boundary corner where `arr` and `set` cover byte-for-byte
        // identical distinct-value sets — the SUBSET relation
        // degenerates to EQUALITY. Pins that the helper does NOT
        // gratuitously require the SUBSET to be PROPER (strict):
        // equal-multisets pass the SUBSET check. Sibling posture to
        // `assert_char_array_within_char_finite_set_accepts_arr_equals_set`
        // and `assert_u8_array_within_u8_finite_set_accepts_arr_equals_set`
        // on the (char) + (u8) row-dual peers of the SUBSET-EMBEDDING
        // helper — the three share the EQUAL-SETS corner across the
        // element-type column.
        assert_str_array_within_str_finite_set(&["a", "b"], &["a", "b"]);
        assert_str_array_within_str_finite_set(&[Atom::TRUE_LITERAL], &[Atom::TRUE_LITERAL]);
    }

    #[test]
    fn assert_str_array_within_str_finite_set_accepts_each_family_wide_substrate_subset() {
        // Runtime cross-check that the THREE (subset, superset) pairs
        // the substrate's module-level `const _` witnesses at
        // `error.rs` pin at COMPILE time are PROPER SUBSET embeddings
        // at runtime too. The pairs enforce the theorem at TWO stages
        // of the toolchain: the const witnesses fire FIRST at `cargo
        // check` (through the three module-level `const _: () =
        // crate::ast::assert_str_array_within_str_finite_set::<N, M>
        // (...)` lines in `error.rs`), this runtime pin catches the
        // drift at `cargo test` as a safety net. Sibling posture to
        // `assert_char_array_within_char_finite_set_accepts_each_family_wide_substrate_subset`
        // and `assert_str_array_pairwise_distinct_accepts_every_family_wide_substrate_array`
        // — the first sweeps the (char) subset pairs at the SUBSET-
        // EMBEDDING axis; the second sweeps the (str) five arrays at
        // the INJECTIVITY axis; this pin sweeps the (str) three
        // (subset, superset) PAIRS at the SUBSET-EMBEDDING axis.
        // Cardinality composition: 6 + 4 + 2 = 12 =
        // `SexpShape::LABELS.len()` — the three subsets partition the
        // outer twelve-arm vocabulary (composed with the pre-existing
        // pairwise-disjointness witness of `AtomKind::LABELS ∩
        // QuoteForm::LABELS`).
        assert_str_array_within_str_finite_set::<6, 12>(&AtomKind::LABELS, &SexpShape::LABELS);
        assert_str_array_within_str_finite_set::<4, 12>(&QuoteForm::LABELS, &SexpShape::LABELS);
        assert_str_array_within_str_finite_set::<2, 12>(
            &StructuralKind::LABELS,
            &SexpShape::LABELS,
        );
    }

    #[test]
    fn assert_str_array_within_str_finite_set_accepts_repeated_array_entries_in_set() {
        // Peer corner to a (future-lift) `_covers_str_finite_set`:
        // this helper permits duplicates in `arr` because SUBSET-
        // membership is a DISTINCT-value predicate — `["a", "a", "b"]`
        // is a subset of `{"a", "b", "c"}` even though the array is
        // not pairwise-distinct. Pins that the helper does NOT
        // gratuitously require INJECTIVITY on `arr` (the injectivity
        // axis is a DIFFERENT compile-time contract bound by
        // `assert_str_array_pairwise_distinct`; combining both binds
        // BOTH axes). Sibling posture to
        // `assert_char_array_within_char_finite_set_accepts_repeated_array_entries_in_set`
        // and `assert_u8_array_within_u8_finite_set_accepts_repeated_array_entries_in_set`
        // on the (char) + (u8) row-dual peers of the SUBSET-EMBEDDING
        // helper.
        assert_str_array_within_str_finite_set(&["a", "a", "b"], &["a", "b", "c"]);
    }

    #[test]
    #[should_panic(expected = "STR-SUBSET-VIOLATION")]
    fn assert_str_array_within_str_finite_set_panics_at_runtime_on_out_of_set_entry() {
        // NEGATIVE PIN — STR-SUBSET-VIOLATION corner: an array
        // carrying a single entry NOT in the target set MUST panic
        // at runtime with the STR-SUBSET-VIOLATION-named message.
        // Pins the helper's OWN reject arm — a regression that
        // silently returned without panicking on an out-of-set entry
        // would slip through the compile-time witnesses' failure mode
        // too. The offending str `"z"` is intentionally chosen
        // OUTSIDE the target set to pin the OUT-OF-SET drift mode.
        assert_str_array_within_str_finite_set(&["a", "z"], &["a", "b", "c"]);
    }

    #[test]
    #[should_panic(expected = "STR-SUBSET-VIOLATION")]
    fn assert_str_array_within_str_finite_set_panics_at_runtime_on_terminal_out_of_set_entry() {
        // NEGATIVE PIN — terminal-position drift: an out-of-set entry
        // at the LAST array position MUST panic — pins that the
        // outer `while i < N` loop reaches `i = N - 1` (else the
        // terminal drift would slip through). A regression that
        // narrowed the outer sweep to `while i < N - 1` (off-by-one
        // on the OUTER bound) would silently accept this array.
        // Sibling posture to
        // `assert_char_array_within_char_finite_set_panics_at_runtime_on_terminal_out_of_set_entry`
        // and `assert_u8_array_within_u8_finite_set_panics_at_runtime_on_terminal_out_of_set_entry`
        // on the (char) + (u8) row-dual peers' terminal-position
        // pins — all three bind the outer-sweep terminal bound at
        // the ONE array-side outer loop the helper carries.
        assert_str_array_within_str_finite_set(&["a", "b", "c", "z"], &["a", "b", "c"]);
    }

    #[test]
    fn assert_str_array_within_str_finite_set_rejects_length_prefix_shorter_than_set_entry() {
        // Byte-length gate corner: an `arr` entry that shares a
        // strict-prefix with a `set` entry but is BYTE-SHORTER than
        // that `set` entry MUST fail the subset check (prefix ≠
        // equal-bytes at the `str_bytes_equal` byte-length gate).
        // Pins the cross-array direction of the SAME byte-length
        // gate the pairwise-distinct sibling's test surface
        // (`assert_str_array_pairwise_distinct_rejects_length_zero_collision`,
        // `assert_str_array_pairwise_distinct_accepts_prefix_pair_without_collision`)
        // pins on the intra-array direction. Cross-array prefix
        // mismatch → out-of-set → STR-SUBSET-VIOLATION panic.
        let outcome = std::panic::catch_unwind(|| {
            assert_str_array_within_str_finite_set(&["quo"], &["quote", "quasiquote"]);
        });
        outcome.expect_err(
            "assert_str_array_within_str_finite_set must panic on a \
             STRICT-PREFIX-only entry outside the target set — the \
             byte-length gate at str_bytes_equal separates \
             `\"quo\"` from `\"quote\"` at the length-check arm before \
             any byte comparison, routing to the STR-SUBSET-VIOLATION \
             out-of-set panic",
        );
    }

    #[test]
    fn assert_str_array_within_str_finite_set_accepts_length_zero_entry_in_length_zero_set() {
        // BYTE-LENGTH-ZERO corner: the empty-string entry `""` in
        // `arr` MUST match the empty-string entry `""` in `set` at
        // the byte-length gate (both length 0). Pins the LOWER
        // boundary of the byte-length axis on the cross-array
        // direction of the SAME byte-length gate. A regression that
        // gated `str_bytes_equal` on `a.len() > 0` (rather than
        // `a.len() == b.len()`) would silently reject this pair.
        assert_str_array_within_str_finite_set(&[""], &[""]);
    }

    #[test]
    fn assert_str_array_within_str_finite_set_panic_message_names_the_helper_and_str_subset_violation_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — STR-SUBSET-VIOLATION arm:
        // the panic message MUST begin with the helper's own name AND
        // identify the failed AXIS as "STR-SUBSET-VIOLATION" so
        // downstream diagnostics route the drift back to (a) the
        // helper by string search on
        // `"assert_str_array_within_str_finite_set"` and (b) the axis
        // by string search on `"STR-SUBSET-VIOLATION"`. Sibling
        // posture to
        // `assert_char_array_within_char_finite_set_panic_message_names_the_helper_and_char_subset_violation_axis`
        // on the (char) row-dual peer's provenance pin AND to
        // `assert_u8_array_within_u8_finite_set_panic_message_names_the_helper_and_subset_violation_axis`
        // on the (u8) row-dual peer's provenance pin — the three
        // pins together bind the (helper, failed-axis) provenance
        // triple across the (element-type ∈ {char, u8, `&'static
        // str`}) × (subset-embedding)-column 3-row face with matching
        // provenance-preservation discipline. The axis-provenance
        // string `"STR-SUBSET-VIOLATION"` is chosen DISTINCT from
        // EVERY sibling helper's axis vocabulary (`"duplicate"` on
        // the (str) ARRAY-side pairwise-distinct sibling; `"STR-
        // DISJOINTNESS-VIOLATION"` on the (str) row DISJOINTNESS
        // sibling; `"CHAR-SUBSET-VIOLATION"` on the (char) row-dual
        // SUBSET sibling; `"SUBSET-VIOLATION"` on the (u8) finite-
        // set SUBSET-only sibling; `"RANGE-SUBSET-VIOLATION"` on the
        // (u8) range SUBSET-only sibling; `"CHAR-DISJOINTNESS-
        // VIOLATION"` / `"U8-DISJOINTNESS-VIOLATION"` on the (char)
        // / (u8) row-dual DISJOINTNESS siblings; `"OUT-OF-SET"` /
        // `"SET-BYTE-MISSING"` on the (u8) covers-finite-set
        // sibling; `"OUT-OF-RANGE"` / `"MISSING"` on the (u8)
        // covers-inclusive-range sibling; `"ARITY-MISMATCH"` on both
        // (u8) `_permutes_*` compound helpers; `"SET-NOT-PAIRWISE-
        // DISTINCT"` on the (u8) SET-side well-formedness sibling)
        // so a diagnostic that names the failed axis routes
        // UNAMBIGUOUSLY to (a) this specific `&'static str` SUBSET-
        // embedding helper, (b) the `arr` argument as the drift site
        // rather than the `set` argument specifying the target
        // superset.
        let outcome = std::panic::catch_unwind(|| {
            assert_str_array_within_str_finite_set(&["a", "z"], &["a", "b", "c"]);
        });
        let payload = outcome.expect_err(
            "assert_str_array_within_str_finite_set must panic on an \
             out-of-set entry — the reject-out-of-set arm is the \
             sole STR-SUBSET-VIOLATION failure mode of the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_str_array_within_str_finite_set panic payload \
                 must be a static &str or String",
            );
        assert!(
            msg.contains("assert_str_array_within_str_finite_set"),
            "assert_str_array_within_str_finite_set panic message \
             {msg:?} must name the helper for provenance-preserving \
             failure diagnostics",
        );
        assert!(
            msg.contains("STR-SUBSET-VIOLATION"),
            "assert_str_array_within_str_finite_set panic message \
             {msg:?} must name the failed AXIS (\"STR-SUBSET-\
             VIOLATION\") for axis-provenance-preserving failure \
             diagnostics",
        );
    }

    #[test]
    #[should_panic(expected = "assert_str_array_pairwise_distinct")]
    fn assert_str_array_within_str_finite_set_panics_on_malformed_target_set_spec() {
        // NEGATIVE PIN — DELEGATED SET-side well-formedness: a
        // malformed target-set spec `["a", "a", "b"]` fed into the
        // ARRAY-side within helper MUST panic on the DELEGATED
        // pairwise-distinct arm BEFORE the STR-SUBSET-VIOLATION arm
        // fires. Pins the delegation chain: a regression that
        // dropped the `assert_str_array_pairwise_distinct(set)` call
        // at the top of `assert_str_array_within_str_finite_set`
        // would silently accept a malformed set and produce a false-
        // positive verdict on any `arr` embedded in the DISTINCT-
        // value subset. The panic message here surfaces from the
        // SIBLING helper (containing the ARRAY-side helper's
        // `"assert_str_array_pairwise_distinct"` panic-name prefix
        // rather than a bespoke `"SET-NOT-PAIRWISE-DISTINCT"` axis
        // string) because the (str) row does NOT yet carry a
        // separate `assert_str_finite_set_pairwise_distinct` alias —
        // the delegation reuses the ARRAY-side helper directly per
        // the design choice documented on the SET-side-well-
        // formedness section of the helper's docstring. Sibling
        // posture to
        // `assert_char_array_within_char_finite_set_panics_on_malformed_target_set_spec`
        // and `assert_u8_array_within_u8_finite_set_panics_on_malformed_target_set_spec`
        // on the (char) + (u8) row-dual peers' delegated-SET-well-
        // formedness pins — the three pins together bind the
        // delegation chain at ONE test per element-type row.
        assert_str_array_within_str_finite_set::<2, 3>(&["a", "b"], &["a", "b", "b"]);
    }

    // ── `assert_str_finite_set_covered_by_three_str_arrays` — the
    // (⊆) SET-COVERAGE dual of the SUBSET-embedding sibling on the
    // (`&'static str`) row of the (element-type × contract-shape)
    // matrix, extended to the 3-array-union carrier shape. Sibling
    // posture: same runtime-test surface (accept-empty-parent,
    // accept-parent-covered-by-first-array, accept-parent-covered-
    // by-second-array, accept-parent-covered-by-third-array, accept-
    // sexp-shape-labels-partition, reject-uncovered-parent-entry,
    // reject-terminal-uncovered-parent-entry, panic-message-
    // provenance, delegated-set-well-formedness) specialised to the
    // 3-array coverage shape. A regression that silently weakens the
    // helper (e.g. dropping the second-array probe, dropping the
    // third-array probe, or short-circuiting on the first parent
    // position) is caught by the helper's OWN test surface rather
    // than only surfacing as a false-positive on the
    // `SexpShape::LABELS` disjoint-union witness.

    #[test]
    fn assert_str_finite_set_covered_by_three_str_arrays_accepts_the_empty_parent() {
        // Empty parent `set = []` at the `[&'static str; 0]` corner
        // — vacuously covered by any triple of sub-vocabulary arrays
        // (no `w` position exists to test). Cross-arity coverage on
        // the trivial PARENT corner of the const-W generic across
        // three sub-vocabulary-arity combinations. Turbofish binding
        // required because there's no other cue for the const
        // parameters on the empty array literal.
        assert_str_finite_set_covered_by_three_str_arrays::<0, 0, 0, 0>(&[], &[], &[], &[]);
        assert_str_finite_set_covered_by_three_str_arrays::<1, 0, 0, 0>(&["x"], &[], &[], &[]);
        assert_str_finite_set_covered_by_three_str_arrays::<1, 2, 3, 0>(
            &["a"],
            &["b", "c"],
            &["d", "e", "f"],
            &[],
        );
    }

    #[test]
    fn assert_str_finite_set_covered_by_three_str_arrays_accepts_parent_covered_by_first_array() {
        // Singleton parent `set = [K]` at the `[&'static str; 1]`
        // corner MUST pass when `K` is in the FIRST sub-vocabulary
        // array `a`. Pins the FIRST-ARRAY probe arm's short-circuit
        // discovery — the parent entry is reached without exhausting
        // the second- or third-array probes. Cross-position coverage
        // inside `a`: parent hit at FIRST, MIDDLE, LAST position of
        // `a` pins the INNER `while i < N` sweep terminates at the
        // first-match position rather than always at position `0` OR
        // always at position `N - 1`.
        assert_str_finite_set_covered_by_three_str_arrays::<3, 2, 1, 1>(
            &["k", "b", "c"],
            &["d", "e"],
            &["f"],
            &["k"],
        );
        assert_str_finite_set_covered_by_three_str_arrays::<3, 2, 1, 1>(
            &["a", "k", "c"],
            &["d", "e"],
            &["f"],
            &["k"],
        );
        assert_str_finite_set_covered_by_three_str_arrays::<3, 2, 1, 1>(
            &["a", "b", "k"],
            &["d", "e"],
            &["f"],
            &["k"],
        );
    }

    #[test]
    fn assert_str_finite_set_covered_by_three_str_arrays_accepts_parent_covered_by_second_array() {
        // Singleton parent MUST pass when `K` is in the SECOND sub-
        // vocabulary array `b` but NOT in `a`. Pins the SECOND-ARRAY
        // probe arm — the coverage sweep proceeds from `a` to `b`
        // when `a` returns no hit. A regression that dropped the
        // `if !found { … b sweep … }` block would silently reject
        // this case as SET-STR-MISSING even though `b` carries the
        // covering entry. Cross-position coverage inside `b`: FIRST,
        // MIDDLE, LAST positions of `b` pin the INNER `while j < M`
        // sweep terminates at the first-match position.
        assert_str_finite_set_covered_by_three_str_arrays::<3, 3, 1, 1>(
            &["a", "b", "c"],
            &["k", "e", "f"],
            &["g"],
            &["k"],
        );
        assert_str_finite_set_covered_by_three_str_arrays::<3, 3, 1, 1>(
            &["a", "b", "c"],
            &["d", "k", "f"],
            &["g"],
            &["k"],
        );
        assert_str_finite_set_covered_by_three_str_arrays::<3, 3, 1, 1>(
            &["a", "b", "c"],
            &["d", "e", "k"],
            &["g"],
            &["k"],
        );
    }

    #[test]
    fn assert_str_finite_set_covered_by_three_str_arrays_accepts_parent_covered_by_third_array() {
        // Singleton parent MUST pass when `K` is in the THIRD sub-
        // vocabulary array `c` but NOT in `a` or `b`. Pins the
        // THIRD-ARRAY probe arm — the coverage sweep proceeds all
        // the way to `c` when `a` and `b` both return no hit. A
        // regression that dropped the `if !found { … c sweep … }`
        // block would silently reject this case as SET-STR-MISSING
        // even though `c` carries the covering entry. Cross-position
        // coverage inside `c`: FIRST, MIDDLE, LAST positions of `c`
        // pin the INNER `while k < K` sweep terminates at the first-
        // match position.
        assert_str_finite_set_covered_by_three_str_arrays::<3, 2, 3, 1>(
            &["a", "b", "c"],
            &["d", "e"],
            &["k", "g", "h"],
            &["k"],
        );
        assert_str_finite_set_covered_by_three_str_arrays::<3, 2, 3, 1>(
            &["a", "b", "c"],
            &["d", "e"],
            &["f", "k", "h"],
            &["k"],
        );
        assert_str_finite_set_covered_by_three_str_arrays::<3, 2, 3, 1>(
            &["a", "b", "c"],
            &["d", "e"],
            &["f", "g", "k"],
            &["k"],
        );
    }

    #[test]
    fn assert_str_finite_set_covered_by_three_str_arrays_accepts_sexp_shape_labels_partition() {
        // Runtime cross-check that the twelve-arm
        // (`AtomKind::LABELS`, `QuoteForm::LABELS`,
        // `StructuralKind::LABELS`, `SexpShape::LABELS`) partition
        // quadruple the substrate's module-level `const _` witness at
        // `error.rs` pins at COMPILE time is a well-formed SET-
        // COVERAGE relation at runtime too. The quadruple enforces the
        // (⊆) direction of the disjoint-union theorem at TWO stages
        // of the toolchain: the const witness fires FIRST at `cargo
        // check`, this runtime pin catches the drift at `cargo test`
        // as a safety net. Sibling posture to
        // `assert_str_array_within_str_finite_set_accepts_each_family_wide_substrate_subset`
        // — the sibling sweeps the (⊇) SUBSET direction for the three
        // sub-vocabularies; this pin sweeps the (⊆) COVERAGE direction
        // for the parent. Cardinality composition: 6 + 4 + 2 = 12 =
        // `SexpShape::LABELS.len()`.
        assert_str_finite_set_covered_by_three_str_arrays::<6, 4, 2, 12>(
            &AtomKind::LABELS,
            &QuoteForm::LABELS,
            &crate::error::StructuralKind::LABELS,
            &crate::error::SexpShape::LABELS,
        );
    }

    #[test]
    #[should_panic(expected = "SET-STR-MISSING")]
    fn assert_str_finite_set_covered_by_three_str_arrays_panics_at_runtime_on_uncovered_parent_entry(
    ) {
        // NEGATIVE PIN — SET-STR-MISSING corner: a parent set carrying
        // an entry NOT in any of the three sub-vocabulary arrays MUST
        // panic at runtime with the SET-STR-MISSING-named message.
        // Pins the helper's OWN reject arm — a regression that
        // silently returned without panicking on an uncovered entry
        // would slip through the compile-time witness's failure mode
        // too. The offending str `"z"` is intentionally chosen ABSENT
        // from `a ∪ b ∪ c` to pin the SET-STR-MISSING drift mode.
        assert_str_finite_set_covered_by_three_str_arrays::<1, 1, 1, 2>(
            &["a"],
            &["b"],
            &["c"],
            &["a", "z"],
        );
    }

    #[test]
    #[should_panic(expected = "SET-STR-MISSING")]
    fn assert_str_finite_set_covered_by_three_str_arrays_panics_at_runtime_on_terminal_uncovered_parent_entry(
    ) {
        // NEGATIVE PIN — terminal-position drift: an uncovered entry
        // at the LAST parent position MUST panic — pins that the
        // outer `while w < W` loop reaches `w = W - 1` (else the
        // terminal drift would slip through). A regression that
        // narrowed the outer sweep to `while w < W - 1` (off-by-one
        // on the OUTER bound) would silently accept this parent set
        // even though the trailing `"z"` is uncovered.
        assert_str_finite_set_covered_by_three_str_arrays::<1, 1, 1, 4>(
            &["a"],
            &["b"],
            &["c"],
            &["a", "b", "c", "z"],
        );
    }

    #[test]
    fn assert_str_finite_set_covered_by_three_str_arrays_panic_message_names_the_helper_and_set_str_missing_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — SET-STR-MISSING arm: the
        // panic message MUST begin with the helper's own name AND
        // identify the failed AXIS as "SET-STR-MISSING" so downstream
        // diagnostics route the drift back to (a) the helper by
        // string search on
        // `"assert_str_finite_set_covered_by_three_str_arrays"` and
        // (b) the axis by string search on `"SET-STR-MISSING"`.
        // Sibling posture to
        // `assert_str_array_within_str_finite_set_panic_message_names_the_helper_and_str_subset_violation_axis`
        // on the sibling (str)-row SUBSET-VIOLATION provenance pin
        // AND to the (u8) row-dual peer's `"SET-BYTE-MISSING"` axis
        // vocabulary on `assert_u8_array_covers_finite_set` — the
        // element-type infix `"STR"` vs `"BYTE"` disambiguates the
        // element-type peer while the shared `"SET-…-MISSING"` suffix
        // lets callers grep any row's COVERAGE-side SET-MISSING
        // sibling by the shared suffix pattern alone.
        let outcome = std::panic::catch_unwind(|| {
            assert_str_finite_set_covered_by_three_str_arrays::<1, 1, 1, 2>(
                &["a"],
                &["b"],
                &["c"],
                &["a", "z"],
            );
        });
        let payload = outcome.expect_err(
            "assert_str_finite_set_covered_by_three_str_arrays must \
             panic on an uncovered parent entry — the reject-uncovered \
             arm is the sole SET-STR-MISSING failure mode of the \
             helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_str_finite_set_covered_by_three_str_arrays \
                 panic payload must be a static &str or String",
            );
        assert!(
            msg.contains("assert_str_finite_set_covered_by_three_str_arrays"),
            "assert_str_finite_set_covered_by_three_str_arrays panic \
             message {msg:?} must name the helper for provenance-\
             preserving failure diagnostics",
        );
        assert!(
            msg.contains("SET-STR-MISSING"),
            "assert_str_finite_set_covered_by_three_str_arrays panic \
             message {msg:?} must name the failed AXIS (\"SET-STR-\
             MISSING\") for axis-provenance-preserving failure \
             diagnostics",
        );
    }

    #[test]
    #[should_panic(expected = "assert_str_array_pairwise_distinct")]
    fn assert_str_finite_set_covered_by_three_str_arrays_panics_on_malformed_target_set_spec() {
        // NEGATIVE PIN — DELEGATED SET-side well-formedness: a
        // malformed parent-set spec `["a", "a", "b"]` fed into the
        // COVERAGE helper MUST panic on the DELEGATED pairwise-
        // distinct arm BEFORE the SET-STR-MISSING arm fires. Pins the
        // delegation chain: a regression that dropped the
        // `assert_str_array_pairwise_distinct(set)` call at the top
        // of `assert_str_finite_set_covered_by_three_str_arrays`
        // would silently accept a malformed parent set with duplicate
        // entries (the duplicated byte counts as covered on the first
        // hit even when the second copy is absent from `a ∪ b ∪ c`).
        // The panic message surfaces from the sibling ARRAY-side
        // pairwise-distinct helper directly (containing its
        // `"assert_str_array_pairwise_distinct"` panic-name prefix)
        // because the (str) row does NOT carry a separate
        // `assert_str_finite_set_pairwise_distinct` alias — the
        // delegation reuses the ARRAY-side helper per the design
        // choice documented on the SET-side well-formedness section
        // of the helper's docstring.
        assert_str_finite_set_covered_by_three_str_arrays::<1, 1, 1, 3>(
            &["a"],
            &["b"],
            &["c"],
            &["a", "a", "b"],
        );
    }

    // ── `assert_str_array_is_concatenation_of_two_scalar_replicas` —
    // the MANY-TO-ONE-BLOCK-CONSTANCY sibling of the INJECTIVITY
    // sibling on the (`&'static str`) row of the (element-type ×
    // contract-shape) matrix. Sibling posture: symmetric runtime-test
    // surface (accept-two-block-partition, accept-K-zero-degenerate,
    // accept-K-equals-N-degenerate, accept-empty-array, accept-
    // compiler-spec-io-stage-operations-partition, reject-head-drift,
    // reject-tail-drift, reject-arity-slip, panic-message-provenance)
    // specialised to the MANY-TO-ONE block-constant projection shape.
    // A regression that silently weakens the helper (e.g. flipping
    // `str_bytes_equal` to `!str_bytes_equal`, narrowing the outer
    // sweep to `while i < K - 1` on the HEAD segment, silently
    // skipping the TAIL segment, or returning early past the
    // CARDINALITY-MISMATCH gate) is caught by the helper's OWN test
    // surface rather than only surfacing as a false-positive on the
    // `CompilerSpecIoStage::OPERATIONS` witness.

    #[test]
    fn assert_str_array_is_concatenation_of_two_scalar_replicas_accepts_the_two_block_partition() {
        // Canonical two-block partition `[head; K] ++ [tail; N - K]`
        // at the substrate's ONE non-injective per-index projection
        // array `CompilerSpecIoStage::OPERATIONS` — the `(N, K) =
        // (4, 2)` corner with `(head, tail) = (REALIZE_TO_DISK,
        // LOAD_FROM_DISK)` MUST pass. Cross-partition coverage on
        // arities (3, 1), (4, 2), (5, 3) pins the INNER `while i < K`
        // and `while j < N` sweeps proceed through EACH position of
        // BOTH segments rather than short-circuiting on ANY early
        // position.
        assert_str_array_is_concatenation_of_two_scalar_replicas::<3, 1>(
            &["a", "b", "b"],
            "a",
            "b",
        );
        assert_str_array_is_concatenation_of_two_scalar_replicas::<4, 2>(
            &["a", "a", "b", "b"],
            "a",
            "b",
        );
        assert_str_array_is_concatenation_of_two_scalar_replicas::<5, 3>(
            &["a", "a", "a", "b", "b"],
            "a",
            "b",
        );
    }

    #[test]
    fn assert_str_array_is_concatenation_of_two_scalar_replicas_accepts_the_k_zero_all_tail_degenerate(
    ) {
        // Degenerate `K = 0` corner collapses the array into the ALL-
        // TAIL replica `arr == [tail; N]`. The HEAD segment is empty
        // (`while i < 0` never enters); the TAIL segment covers
        // positions `[0, N)`. Cross-arity coverage on the `K = 0`
        // axis pins the HEAD-segment sweep's outer `while i < K`
        // terminates at `i = 0` when `K = 0`, and the TAIL-segment
        // sweep's outer `while j < N` starts at `j = K = 0` and
        // proceeds through EVERY position. A regression that hard-
        // coded `K > 0` or short-circuited on the empty HEAD-segment
        // arm would silently reject this legal degenerate shape.
        assert_str_array_is_concatenation_of_two_scalar_replicas::<3, 0>(
            &["x", "x", "x"],
            "unused",
            "x",
        );
    }

    #[test]
    fn assert_str_array_is_concatenation_of_two_scalar_replicas_accepts_the_k_equals_n_all_head_degenerate(
    ) {
        // Degenerate `K = N` corner collapses the array into the ALL-
        // HEAD replica `arr == [head; N]`. The HEAD segment covers
        // positions `[0, N)`; the TAIL segment is empty (`while j <
        // N` starts at `j = K = N` and never enters). Peer to the
        // `K = 0` degenerate corner — together the two corners pin
        // the ONE-BLOCK degenerate shapes on BOTH endpoints of the
        // `K ∈ [0, N]` const-generic range. A regression that hard-
        // coded `K < N` or short-circuited on the empty TAIL-segment
        // arm would silently reject this legal degenerate shape.
        assert_str_array_is_concatenation_of_two_scalar_replicas::<3, 3>(
            &["x", "x", "x"],
            "x",
            "unused",
        );
    }

    #[test]
    fn assert_str_array_is_concatenation_of_two_scalar_replicas_accepts_the_empty_array() {
        // Trivial `N = 0, K = 0` corner: the empty array trivially
        // satisfies BOTH the empty HEAD segment `[head; 0]` and the
        // empty TAIL segment `[tail; 0]`. Pins that the vacuous case
        // on the `[&'static str; 0]` corner of the const-N generic
        // passes without either segment sweep entering. Turbofish
        // binding required because there's no cue for the const
        // parameters on the empty array literal.
        assert_str_array_is_concatenation_of_two_scalar_replicas::<0, 0>(
            &[],
            "unused-head",
            "unused-tail",
        );
    }

    #[test]
    fn assert_str_array_is_concatenation_of_two_scalar_replicas_accepts_head_equals_tail_single_block(
    ) {
        // Corner where `head == tail` collapses the two-block
        // partition into a SINGLE-BLOCK replica: `arr == [head; N] ==
        // [tail; N]`. The partition boundary `K` is irrelevant to the
        // observable byte-shape when `head` and `tail` are byte-
        // equal, so ANY `K ∈ [0, N]` accepts. Pins the docstring
        // note "the two scalars `head` and `tail` MAY be byte-equal
        // (in which case the helper degenerates to a SINGLE-BLOCK
        // replica-check)". Cross-K coverage inside `N = 4`: K = 0
        // (empty HEAD), K = 2 (interior split), K = 4 (empty TAIL).
        assert_str_array_is_concatenation_of_two_scalar_replicas::<4, 0>(
            &["z", "z", "z", "z"],
            "z",
            "z",
        );
        assert_str_array_is_concatenation_of_two_scalar_replicas::<4, 2>(
            &["z", "z", "z", "z"],
            "z",
            "z",
        );
        assert_str_array_is_concatenation_of_two_scalar_replicas::<4, 4>(
            &["z", "z", "z", "z"],
            "z",
            "z",
        );
    }

    #[test]
    fn assert_str_array_is_concatenation_of_two_scalar_replicas_accepts_compiler_spec_io_stage_operations_partition(
    ) {
        // Runtime cross-check that the substrate's ONE non-injective
        // per-index projection array `CompilerSpecIoStage::OPERATIONS`
        // — the `(N, K) = (4, 2)` corner with `(head, tail) =
        // (REALIZE_TO_DISK_OPERATION, LOAD_FROM_DISK_OPERATION)` —
        // the substrate's module-level `const _` witness at `error.rs`
        // pins at COMPILE time is a well-formed BLOCK-CONSTANCY
        // relation at runtime too. The pair enforces the theorem at
        // TWO stages of the toolchain: the const witness fires FIRST
        // at `cargo check`, this runtime pin catches the drift at
        // `cargo test` as a safety net. Sibling posture to
        // `compiler_spec_io_stage_operations_align_with_all_by_index`
        // (which pins per-position equality via `stage.operation()`
        // at runtime) and to
        // `compiler_spec_io_stage_operations_partition_all_two_ways`
        // (which pins the two operation-label multiplicities at
        // runtime) — this witness carries the SAME theorem at the
        // ARRAY-LEVEL block-constant shape at COMPILE time.
        assert_str_array_is_concatenation_of_two_scalar_replicas::<4, 2>(
            &crate::error::CompilerSpecIoStage::OPERATIONS,
            crate::error::CompilerSpecIoStage::REALIZE_TO_DISK_OPERATION,
            crate::error::CompilerSpecIoStage::LOAD_FROM_DISK_OPERATION,
        );
    }

    #[test]
    #[should_panic(expected = "HEAD-SEGMENT-BLOCK-CONSTANCY-VIOLATION")]
    fn assert_str_array_is_concatenation_of_two_scalar_replicas_panics_at_runtime_on_head_segment_drift(
    ) {
        // NEGATIVE PIN — HEAD-SEGMENT-BLOCK-CONSTANCY-VIOLATION
        // corner: an entry in the HEAD segment `arr[0..K)` that does
        // NOT byte-equal `head` MUST panic at runtime with the HEAD-
        // segment-named message. Pins the helper's HEAD-segment
        // reject arm — a regression that silently short-circuited on
        // the first HEAD position without checking the middle or
        // terminal HEAD positions would slip through the compile-
        // time witness's failure mode too. The offending str "x" at
        // position 1 (interior HEAD) pins the middle-of-HEAD drift
        // mode. `K = 3, N = 5` so the HEAD segment spans positions
        // `[0, 3)` — the interior drift at position 1 is inside the
        // HEAD, not the TAIL boundary.
        assert_str_array_is_concatenation_of_two_scalar_replicas::<5, 3>(
            &["a", "x", "a", "b", "b"],
            "a",
            "b",
        );
    }

    #[test]
    #[should_panic(expected = "TAIL-SEGMENT-BLOCK-CONSTANCY-VIOLATION")]
    fn assert_str_array_is_concatenation_of_two_scalar_replicas_panics_at_runtime_on_tail_segment_drift(
    ) {
        // NEGATIVE PIN — TAIL-SEGMENT-BLOCK-CONSTANCY-VIOLATION
        // corner: an entry in the TAIL segment `arr[K..N)` that does
        // NOT byte-equal `tail` MUST panic at runtime with the TAIL-
        // segment-named message. Peer to the HEAD-segment drift arm
        // above — the SAME helper, DIFFERENT segment arm. Pins that
        // the outer `while j < N` sweep on the TAIL segment reaches
        // `j = N - 1` (else the terminal drift would slip through).
        // The offending str "x" at position 4 (terminal TAIL) with
        // `K = 3, N = 5` pins the terminal-TAIL drift mode.
        assert_str_array_is_concatenation_of_two_scalar_replicas::<5, 3>(
            &["a", "a", "a", "b", "x"],
            "a",
            "b",
        );
    }

    #[test]
    #[should_panic(expected = "CARDINALITY-MISMATCH")]
    fn assert_str_array_is_concatenation_of_two_scalar_replicas_panics_at_runtime_on_arity_slip() {
        // NEGATIVE PIN — CARDINALITY-MISMATCH gate: a caller-side
        // turbofish arity slip on the `K` const-generic where `K > N`
        // MUST panic at runtime with the CARDINALITY-MISMATCH-named
        // message BEFORE any per-position sweep begins. Pins the
        // gate's placement at the TOP of the helper — a regression
        // that dropped the gate would silently degenerate into a
        // truncated HEAD-only sweep at the caller's `K` cap without
        // ever entering the TAIL sweep, silently accepting an array
        // whose TAIL positions carry arbitrary drift. The offending
        // `K = 5` against `N = 3` pins the strict `K > N` reject
        // arm; the LEGAL `K == N` degenerate is covered by a peer
        // acceptance test above.
        assert_str_array_is_concatenation_of_two_scalar_replicas::<3, 5>(
            &["a", "a", "a"],
            "a",
            "b",
        );
    }

    #[test]
    fn assert_str_array_is_concatenation_of_two_scalar_replicas_panic_message_names_the_helper_and_block_constancy_violation_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — HEAD-SEGMENT-BLOCK-
        // CONSTANCY-VIOLATION arm: the panic message MUST begin with
        // the helper's own name AND identify the failed AXIS as
        // "HEAD-SEGMENT-BLOCK-CONSTANCY-VIOLATION" so downstream
        // diagnostics route the drift back to (a) the helper by
        // string search on
        // `"assert_str_array_is_concatenation_of_two_scalar_replicas"`
        // and (b) the segment + axis by string search on
        // `"HEAD-SEGMENT-BLOCK-CONSTANCY-VIOLATION"`. Sibling posture
        // to `assert_str_array_pairwise_distinct_panic_message_...`
        // on the sibling (str)-row INJECTIVITY provenance pin AND to
        // the sibling ROW-DUAL `_covered_by_three_str_arrays`'s
        // `"SET-STR-MISSING"` axis vocabulary — the shared
        // `"BLOCK-CONSTANCY-VIOLATION"` suffix lets callers grep
        // either the HEAD or TAIL segment arm by the shared suffix
        // pattern alone, while the `HEAD-` / `TAIL-` prefix
        // disambiguates the SEGMENT.
        let outcome = std::panic::catch_unwind(|| {
            assert_str_array_is_concatenation_of_two_scalar_replicas::<3, 2>(
                &["a", "x", "b"],
                "a",
                "b",
            );
        });
        let payload = outcome.expect_err(
            "assert_str_array_is_concatenation_of_two_scalar_replicas \
             must panic on a HEAD-segment drift — the reject-HEAD-drift \
             arm is one of the two BLOCK-CONSTANCY-VIOLATION failure \
             modes of the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_str_array_is_concatenation_of_two_scalar_replicas \
                 panic payload must be a static &str or String",
            );
        assert!(
            msg.contains("assert_str_array_is_concatenation_of_two_scalar_replicas"),
            "assert_str_array_is_concatenation_of_two_scalar_replicas \
             panic message {msg:?} must name the helper for \
             provenance-preserving failure diagnostics",
        );
        assert!(
            msg.contains("HEAD-SEGMENT-BLOCK-CONSTANCY-VIOLATION"),
            "assert_str_array_is_concatenation_of_two_scalar_replicas \
             panic message {msg:?} must name the failed AXIS (\"HEAD-\
             SEGMENT-BLOCK-CONSTANCY-VIOLATION\") for axis-provenance-\
             preserving failure diagnostics",
        );
    }

    // ── `assert_u8_array_slice_is_scalar_replica` — the (`u8`)-row
    // SLICE-BLOCK-CONSTANCY sibling of the (`&'static str`)-row FULL-
    // ARRAY-two-block-partition sibling
    // `assert_str_array_is_concatenation_of_two_scalar_replicas`.
    // Sibling posture: symmetric runtime-test surface (accept-canonical-
    // slice, accept-empty-slice-corners, accept-full-array-degenerate,
    // accept-sexp-shape-atomic-collapse, reject-slice-content-drift,
    // reject-start-out-of-bounds, reject-end-out-of-bounds, reject-
    // inverted-range, panic-message-provenance) specialised to the (u8)
    // sub-slice SINGLE-scalar block-constant shape. A regression that
    // silently weakens the helper (e.g. flipping `arr[i] != scalar`
    // to `==`, moving the START gate BELOW the sweep, narrowing the
    // sweep to `while i < END - 1` and missing the terminal position,
    // or returning early past ANY bounds gate) is caught by the
    // helper's OWN test surface rather than only surfacing as a false-
    // positive on the `SexpShape::HASH_DISCRIMINATORS[1..7)` witness.

    #[test]
    fn assert_u8_array_slice_is_scalar_replica_accepts_a_canonical_middle_slice() {
        // Canonical sub-slice `arr[START..END) == [scalar; END - START]`
        // inside a longer array `arr` whose ENDPOINTS carry DIFFERENT
        // bytes than the slice. Pins the outer `while i < END` sweep
        // enters at `i = START` (skipping positions `[0..START)`) AND
        // terminates at `i = END` (skipping positions `[END..N)`) —
        // BOTH endpoint bytes DIFFER from `scalar` so a regression
        // that widened the sweep beyond the slice would fail here.
        assert_u8_array_slice_is_scalar_replica::<7, 1, 6>(&[9, 1, 1, 1, 1, 1, 9], 1);
    }

    #[test]
    fn assert_u8_array_slice_is_scalar_replica_accepts_the_empty_slice_at_start_equals_end() {
        // LEGAL degenerate: `START == END` collapses the slice into an
        // empty range `[START..START)`. The sweep never enters the
        // loop body and the helper accepts. Cross-position coverage
        // pins the empty-slice acceptance at THREE distinct positions
        // (`START == 0` at the left endpoint, `START == 3` in the
        // interior, `START == N` at the right endpoint) so a
        // regression that hard-coded `START < END` OR panicked on the
        // `START == END` corner is caught on ALL THREE arms. Peer to
        // the `K == N` / `K == 0` degenerate corners of the sibling
        // `assert_str_array_is_concatenation_of_two_scalar_replicas`.
        assert_u8_array_slice_is_scalar_replica::<5, 0, 0>(&[7, 7, 7, 7, 7], 42);
        assert_u8_array_slice_is_scalar_replica::<5, 3, 3>(&[7, 7, 7, 7, 7], 42);
        assert_u8_array_slice_is_scalar_replica::<5, 5, 5>(&[7, 7, 7, 7, 7], 42);
    }

    #[test]
    fn assert_u8_array_slice_is_scalar_replica_accepts_the_full_array_slice() {
        // Full-array-covering slice `[0..N)` collapses to the ALL-
        // scalar-replica shape `arr == [scalar; N]` (peer to the
        // `K == N` degenerate of the sibling str-row helper). Pins
        // that the sweep proceeds through EVERY position of the array
        // when `START = 0` and `END = N`. Cross-arity coverage on
        // `N ∈ {3, 6, 8}` pins the sweep's terminal-position visit
        // across a range of array cardinalities.
        assert_u8_array_slice_is_scalar_replica::<3, 0, 3>(&[5, 5, 5], 5);
        assert_u8_array_slice_is_scalar_replica::<6, 0, 6>(&[0, 0, 0, 0, 0, 0], 0);
        assert_u8_array_slice_is_scalar_replica::<8, 0, 8>(
            &[255, 255, 255, 255, 255, 255, 255, 255],
            255,
        );
    }

    #[test]
    fn assert_u8_array_slice_is_scalar_replica_accepts_sexp_shape_atomic_collapse_slice() {
        // Runtime cross-check that the substrate's ONE MANY-TO-ONE-
        // COLLAPSE `[u8; N]` sub-slice `SexpShape::HASH_DISCRIMINATORS
        // [1..7)` — the six-slot atomic-outer-shape collapse onto
        // `AtomKind::OUTER_HASH_DISCRIMINATOR` — the substrate's
        // module-level `const _` witness at `ast.rs` pins at COMPILE
        // time is a well-formed SLICE-BLOCK-CONSTANCY relation at
        // runtime too. The pair enforces the theorem at TWO stages of
        // the toolchain: the const witness fires FIRST at `cargo
        // check`, this runtime pin catches the drift at `cargo test`
        // as a safety net. Sibling posture to the peer runtime cross-
        // check on the sibling
        // `assert_str_array_is_concatenation_of_two_scalar_replicas_accepts_compiler_spec_io_stage_operations_partition`
        // — this witness carries the SAME class of MANY-TO-ONE-
        // COLLAPSE theorem at the ARRAY-slice level on the (u8) row
        // rather than the FULL-ARRAY-two-block level on the (str) row.
        assert_u8_array_slice_is_scalar_replica::<12, 1, 7>(
            &crate::error::SexpShape::HASH_DISCRIMINATORS,
            AtomKind::OUTER_HASH_DISCRIMINATOR,
        );
    }

    #[test]
    #[should_panic(expected = "SLICE-BLOCK-CONSTANCY-VIOLATION")]
    fn assert_u8_array_slice_is_scalar_replica_panics_at_runtime_on_slice_content_drift() {
        // NEGATIVE PIN — SLICE-BLOCK-CONSTANCY-VIOLATION corner: an
        // entry in the slice `arr[START..END)` that does NOT byte-
        // equal `scalar` MUST panic at runtime with the slice-named
        // message. Pins the helper's slice-content reject arm — a
        // regression that silently short-circuited on the first slice
        // position without checking the middle or terminal slice
        // positions would slip through the compile-time witness's
        // failure mode too. The offending byte `9` at position `3`
        // (interior of the slice) with `START = 1, END = 6` pins the
        // middle-of-slice drift mode.
        assert_u8_array_slice_is_scalar_replica::<7, 1, 6>(&[0, 1, 1, 9, 1, 1, 0], 1);
    }

    #[test]
    #[should_panic(expected = "START-OUT-OF-BOUNDS")]
    fn assert_u8_array_slice_is_scalar_replica_panics_at_runtime_on_start_out_of_bounds() {
        // NEGATIVE PIN — START-OUT-OF-BOUNDS gate: a caller-side
        // turbofish arity slip on the `START` const-generic where
        // `START > N` MUST panic at runtime with the START-OUT-OF-
        // BOUNDS-named message BEFORE any per-position sweep begins.
        // Pins the gate's placement at the TOP of the helper — a
        // regression that dropped the gate would either silently
        // degenerate into a vacuous sweep OR panic deeper in `arr[i]`
        // bounds-checking with a helper-name-less panic message. The
        // offending `START = 7` against `N = 5` pins the strict
        // `START > N` reject arm; the LEGAL `START == N` empty
        // corner is covered by the peer acceptance test above.
        assert_u8_array_slice_is_scalar_replica::<5, 7, 7>(&[1, 1, 1, 1, 1], 1);
    }

    #[test]
    #[should_panic(expected = "END-OUT-OF-BOUNDS")]
    fn assert_u8_array_slice_is_scalar_replica_panics_at_runtime_on_end_out_of_bounds() {
        // NEGATIVE PIN — END-OUT-OF-BOUNDS gate: a caller-side
        // turbofish arity slip on the `END` const-generic where
        // `END > N` MUST panic at runtime with the END-OUT-OF-BOUNDS-
        // named message. Peer to the START-OUT-OF-BOUNDS arm above —
        // the two gates jointly enforce `START, END ∈ [0..N]` before
        // any content sweep. The offending `END = 9` against `N = 5`
        // pins the strict `END > N` reject arm; the LEGAL `END == N`
        // slice-to-end corner is covered by the full-array acceptance
        // test above. `START = 0` sits in-bounds so the START gate
        // does not fire first.
        assert_u8_array_slice_is_scalar_replica::<5, 0, 9>(&[1, 1, 1, 1, 1], 1);
    }

    #[test]
    #[should_panic(expected = "INVERTED-RANGE")]
    fn assert_u8_array_slice_is_scalar_replica_panics_at_runtime_on_inverted_range() {
        // NEGATIVE PIN — INVERTED-RANGE gate: a caller-side turbofish
        // typo that swaps `START` and `END` (both individually in-
        // bounds, but `START > END`) MUST panic at runtime with the
        // INVERTED-RANGE-named message. Pins that the strict `START
        // > END` slip fails-loud on a DISTINCT axis rather than
        // silently accepting the empty sweep — a regression that
        // dropped this gate would silently accept ANY array on the
        // swapped-turbofish call site. The offending `START = 5,
        // END = 2` against `N = 7` pins the strict `START > END`
        // reject arm; the LEGAL `START == END` empty corner is
        // covered by the peer acceptance test above.
        assert_u8_array_slice_is_scalar_replica::<7, 5, 2>(&[1, 1, 1, 1, 1, 1, 1], 1);
    }

    #[test]
    fn assert_u8_array_slice_is_scalar_replica_panic_message_names_the_helper_and_slice_block_constancy_violation_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — SLICE-BLOCK-CONSTANCY-
        // VIOLATION arm: the panic message MUST begin with the
        // helper's own name AND identify the failed AXIS as "SLICE-
        // BLOCK-CONSTANCY-VIOLATION" so downstream diagnostics route
        // the drift back to (a) the helper by string search on
        // `"assert_u8_array_slice_is_scalar_replica"` and (b) the
        // failed axis by string search on `"SLICE-BLOCK-CONSTANCY-
        // VIOLATION"`. Sibling posture to
        // `assert_str_array_is_concatenation_of_two_scalar_replicas_panic_message_...`
        // on the sibling (str)-row FULL-ARRAY BLOCK-CONSTANCY
        // provenance pin — the shared `"BLOCK-CONSTANCY-VIOLATION"`
        // suffix lets callers grep either the SUB-SLICE or FULL-
        // ARRAY variant by the shared suffix pattern alone, while
        // the `SLICE-` / `HEAD-SEGMENT-` / `TAIL-SEGMENT-` prefix
        // disambiguates the CONTRACT SHAPE.
        let outcome = std::panic::catch_unwind(|| {
            assert_u8_array_slice_is_scalar_replica::<5, 1, 4>(&[0, 1, 9, 1, 0], 1);
        });
        let payload = outcome.expect_err(
            "assert_u8_array_slice_is_scalar_replica must panic on a \
             slice-content drift — the reject-slice-drift arm is the \
             CONTENT failure mode of the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_u8_array_slice_is_scalar_replica panic payload \
                 must be a static &str or String",
            );
        assert!(
            msg.contains("assert_u8_array_slice_is_scalar_replica"),
            "assert_u8_array_slice_is_scalar_replica panic message \
             {msg:?} must name the helper for provenance-preserving \
             failure diagnostics",
        );
        assert!(
            msg.contains("SLICE-BLOCK-CONSTANCY-VIOLATION"),
            "assert_u8_array_slice_is_scalar_replica panic message \
             {msg:?} must name the failed AXIS (\"SLICE-BLOCK-\
             CONSTANCY-VIOLATION\") for axis-provenance-preserving \
             failure diagnostics",
        );
    }

    // ── `assert_u8_array_slice_equals_u8_array` — the SLICE-EQUALS-
    // ARRAY sibling of `assert_u8_array_slice_is_scalar_replica` on
    // the SAME (u8) row. Sibling posture: same runtime-test surface
    // (accept-canonical-middle-slice, accept-empty-sub-array, accept-
    // full-array-degenerate, accept-sexp-shape-quote-tail-composition,
    // reject-positionwise-drift, reject-start-out-of-bounds, reject-
    // slice-length-out-of-bounds, panic-message-provenance)
    // specialised to the (u8) SUB-SLICE ARRAY-image composition shape.
    // A regression that silently weakens the helper (e.g. flipping
    // `full[START + i] != sub[i]` to `==`, dropping the `START`
    // offset from the outer read, moving the START gate BELOW the
    // sweep, narrowing the sweep to `while i < M - 1` and missing
    // the terminal position, or returning early past ANY bounds gate)
    // is caught by the helper's OWN test surface rather than only
    // surfacing as a false-positive on the
    // `SexpShape::HASH_DISCRIMINATORS[8..12] ==
    // QuoteForm::HASH_DISCRIMINATORS` witness.

    #[test]
    fn assert_u8_array_slice_equals_u8_array_accepts_a_canonical_middle_slice() {
        // Canonical sub-slice `full[START..START + M) == sub[..]`
        // inside a longer array `full` whose ENDPOINTS carry
        // DIFFERENT bytes than the peer sub-array. Pins the outer
        // `while i < M` sweep reads `full[START + i]` at the
        // OFFSET position (not `full[i]`) — a regression that
        // dropped the `START` offset would compare `full[0..M)`
        // against `sub[..]` and pass on `full[0]=9 != sub[0]=1`
        // silently or panic on the wrong axis. `START = 1` pins
        // the sweep skips position `[0..START)` and reads only
        // `[1..1+3) = [1..4)`.
        assert_u8_array_slice_equals_u8_array::<7, 3, 1>(&[9, 3, 4, 5, 9, 9, 9], &[3, 4, 5]);
    }

    #[test]
    fn assert_u8_array_slice_equals_u8_array_accepts_the_empty_sub_array() {
        // LEGAL degenerate: `M == 0` collapses the sub-array into
        // an empty listing `[]`. The sweep never enters the loop
        // body and the helper accepts. Cross-position coverage
        // pins the empty-sub-array acceptance at THREE distinct
        // `START` positions (`START == 0` at the left endpoint,
        // `START == 3` in the interior, `START == N` at the right
        // endpoint — the latter is the corner `START == N` combined
        // with `M == 0` that the START-OUT-OF-BOUNDS gate's
        // inclusive upper bound must accept). A regression that
        // hard-coded `START < N` OR panicked on the `M == 0` corner
        // is caught on ALL THREE arms.
        assert_u8_array_slice_equals_u8_array::<5, 0, 0>(&[7, 7, 7, 7, 7], &[]);
        assert_u8_array_slice_equals_u8_array::<5, 0, 3>(&[7, 7, 7, 7, 7], &[]);
        assert_u8_array_slice_equals_u8_array::<5, 0, 5>(&[7, 7, 7, 7, 7], &[]);
    }

    #[test]
    fn assert_u8_array_slice_equals_u8_array_accepts_the_full_array_degenerate() {
        // Full-array-covering slice `M == N, START == 0` collapses
        // to the ALL-positions-equal-peer-array shape `full == sub`
        // pointwise. Pins that the sweep proceeds through EVERY
        // position of the outer array when `START = 0` and `M = N`.
        // Cross-arity coverage on `N ∈ {3, 4, 6}` pins the sweep's
        // terminal-position visit across a range of array
        // cardinalities.
        assert_u8_array_slice_equals_u8_array::<3, 3, 0>(&[10, 20, 30], &[10, 20, 30]);
        assert_u8_array_slice_equals_u8_array::<4, 4, 0>(&[3, 4, 5, 6], &[3, 4, 5, 6]);
        assert_u8_array_slice_equals_u8_array::<6, 6, 0>(&[0, 1, 2, 3, 4, 5], &[0, 1, 2, 3, 4, 5]);
    }

    #[test]
    fn assert_u8_array_slice_equals_u8_array_accepts_sexp_shape_quote_tail_composition() {
        // Runtime cross-check that the substrate's ONE
        // POSITIONWISE-COMPOSITION `[u8; N]` sub-slice
        // `SexpShape::HASH_DISCRIMINATORS[8..12]` byte-for-byte
        // equal to the peer `QuoteForm::HASH_DISCRIMINATORS` is a
        // well-formed SLICE-EQUALS-ARRAY relation at runtime too.
        // The pair enforces the theorem at TWO stages of the
        // toolchain: the const witness fires FIRST at `cargo
        // check`, this runtime pin catches the drift at `cargo
        // test` as a safety net. Sibling posture to the peer
        // runtime cross-check
        // `assert_u8_array_slice_is_scalar_replica_accepts_sexp_shape_atomic_collapse_slice`
        // — this witness carries the SLICE-EQUALS-ARRAY theorem
        // (positionwise composition with a peer array of arity
        // `M`) on the SAME (u8) row's quote-family tail slice
        // rather than the MANY-TO-ONE-COLLAPSE theorem
        // (positionwise composition with a SCALAR) on the atomic-
        // collapse mid slice.
        assert_u8_array_slice_equals_u8_array::<12, 4, 8>(
            &crate::error::SexpShape::HASH_DISCRIMINATORS,
            &QuoteForm::HASH_DISCRIMINATORS,
        );
    }

    #[test]
    fn assert_u8_array_slice_equals_u8_array_accepts_sub_carving_hash_discriminators_per_position_order(
    ) {
        // Runtime cross-check that the FOUR sub-carving
        // `HASH_DISCRIMINATORS` arrays each byte-equal their
        // canonical literal-byte listing pointwise at the FULL-ARRAY
        // corner (`M == N`, `START == 0`). Runs the SAME helper the
        // four `const _` witnesses above line 5842 in this file run
        // at rustc time — a runtime safety net enforcing the
        // theorem at BOTH stages of the toolchain (const at `cargo
        // check`, runtime at `cargo test`). A regression that
        // renamed one of the per-role `*_HASH_DISCRIMINATOR` aliases
        // (or drifted its literal byte value at the declaration
        // site, or reordered a slot in the outer array's
        // initializer) fails HERE at the substrate callsite AND at
        // the const witness above. Peer of
        // `assert_u8_array_slice_equals_u8_array_accepts_sexp_shape_quote_tail_composition`
        // above — that witness carries the SLICE-EQUALS-ARRAY
        // theorem for the OUTER container against a SUB-CARVING
        // array; this witness carries the theorem for each of the
        // FOUR sub-carving arrays against a literal-byte listing.
        //
        // The four sub-carvings appear here in canonical order
        // (`{0..=6}` outer-`Sexp` cache-key partition, top-to-
        // bottom):
        // * `StructuralKind::HASH_DISCRIMINATORS == [0u8, 2]` — the
        //   structural-residual carving. Non-contiguous (gap at
        //   `1u8` reserved for the atomic-carve outer marker).
        // * `AtomKind::HASH_DISCRIMINATORS == [0u8, 1, 2, 3, 4, 5]`
        //   — the nested-inner atomic-payload carving specialising
        //   the outer `1u8` atomic marker inside `Hash for Atom`.
        // * `QuoteForm::HASH_DISCRIMINATORS == [3u8, 4, 5, 6]` —
        //   the quote-family carving covering the four homoiconic
        //   prefixes.
        // * `UnquoteForm::HASH_DISCRIMINATORS == [5u8, 6]` — the
        //   two-of-four substitution subset of `QuoteForm`
        //   projecting through `to_quote_form()`.
        assert_u8_array_slice_equals_u8_array::<2, 2, 0>(
            &crate::error::StructuralKind::HASH_DISCRIMINATORS,
            &[0u8, 2],
        );
        assert_u8_array_slice_equals_u8_array::<6, 6, 0>(
            &AtomKind::HASH_DISCRIMINATORS,
            &[0u8, 1, 2, 3, 4, 5],
        );
        assert_u8_array_slice_equals_u8_array::<4, 4, 0>(
            &QuoteForm::HASH_DISCRIMINATORS,
            &[3u8, 4, 5, 6],
        );
        assert_u8_array_slice_equals_u8_array::<2, 2, 0>(
            &crate::error::UnquoteForm::HASH_DISCRIMINATORS,
            &[5u8, 6],
        );
    }

    /// Runtime SLICE-EQUALS-ARRAY safety net for the (UnquoteForm ⊂
    /// QuoteForm) 2-of-4 sub-carve on the (u8) HASH_DISCRIMINATORS
    /// vocabulary axis — mirrors the module-level `const _: () =
    /// assert_u8_array_slice_equals_u8_array::<4, 2, 2>(&QuoteForm::
    /// HASH_DISCRIMINATORS, &UnquoteForm::HASH_DISCRIMINATORS)` witness
    /// added below line 5617 in this file. The `const _` witness fires
    /// 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.
    ///
    /// (U8)-row peer to `assert_str_array_slice_equals_str_array_
    /// accepts_unquote_form_sub_carve_of_quote_form` at `error.rs`'s
    /// tests submodule — that test sweeps the SAME 2-of-4 sub-carve at
    /// the (str) row across three vocabulary axes (`LABELS`,
    /// `MARKERS↔PREFIXES`, `IAC_FORGE_TAGS`); this test sweeps the same
    /// carve at the (u8) row on the ONE `HASH_DISCRIMINATORS` axis.
    /// Together the four runtime witnesses close the (element-type ×
    /// vocabulary-axis) matrix of the substitution-subset carve at the
    /// SLICE-EQUALS positionwise-composition contract, on the runtime-
    /// pin sibling face of the four-witness compile-time cluster.
    ///
    /// A regression that (a) swaps `UnquoteForm::HASH_DISCRIMINATORS`
    /// from `[UNQUOTE_HASH_DISCRIMINATOR, SPLICE_HASH_DISCRIMINATOR]`
    /// to `[SPLICE_HASH_DISCRIMINATOR, UNQUOTE_HASH_DISCRIMINATOR]`, or
    /// (b) reorders `QuoteForm::HASH_DISCRIMINATORS` such that the two
    /// `UnquoteForm` bytes no longer sit contiguously at slots
    /// `[2..4)`, fails HERE with the `SLICE-EQUALS-ARRAY-VIOLATION`
    /// axis panic naming the drifted position — where the sibling
    /// SET-level SUBSET safety-net stays silent (both bytes still
    /// appear in the superset, just at different positions).
    #[test]
    fn assert_u8_array_slice_equals_u8_array_accepts_unquote_form_sub_carve_of_quote_form() {
        assert_u8_array_slice_equals_u8_array::<4, 2, 2>(
            &QuoteForm::HASH_DISCRIMINATORS,
            &crate::error::UnquoteForm::HASH_DISCRIMINATORS,
        );
    }

    #[test]
    #[should_panic(expected = "SLICE-EQUALS-ARRAY-VIOLATION")]
    fn assert_u8_array_slice_equals_u8_array_panics_at_runtime_on_positionwise_drift() {
        // NEGATIVE PIN — SLICE-EQUALS-ARRAY-VIOLATION corner: a
        // byte at some position in `full[START..START + M)` that
        // does NOT byte-equal the peer sub-array `sub` at the
        // offset-matched position MUST panic at runtime with the
        // slice-named message. Pins the helper's positionwise-
        // drift reject arm — a regression that silently short-
        // circuited on the first slice position without checking
        // the middle or terminal slice positions would slip
        // through the compile-time witness's failure mode too.
        // The offending byte `9` at outer position `3` (interior
        // of the sub-slice `[1..4)`, offset `2` inside `sub`)
        // pins the middle-of-slice drift mode.
        assert_u8_array_slice_equals_u8_array::<5, 3, 1>(&[0, 3, 4, 9, 0], &[3, 4, 5]);
    }

    #[test]
    #[should_panic(expected = "START-OUT-OF-BOUNDS")]
    fn assert_u8_array_slice_equals_u8_array_panics_at_runtime_on_start_out_of_bounds() {
        // NEGATIVE PIN — START-OUT-OF-BOUNDS gate: a caller-side
        // turbofish arity slip on the `START` const-generic where
        // `START > N` MUST panic at runtime with the START-OUT-OF-
        // BOUNDS-named message BEFORE the peer SLICE-LENGTH-OUT-OF-
        // BOUNDS gate reads `N - START` (which would `usize`-
        // underflow had this gate not caught the slip first). Pins
        // the gate's placement at the TOP of the helper — a
        // regression that dropped the gate would either underflow
        // subtraction at the peer gate OR panic deeper in
        // `full[START + i]` bounds-checking with a helper-name-less
        // panic message. The offending `START = 7` against `N = 5`
        // pins the strict `START > N` reject arm; the LEGAL
        // `START == N` empty-slice-at-right-endpoint corner is
        // covered by the peer acceptance test above.
        assert_u8_array_slice_equals_u8_array::<5, 0, 7>(&[1, 1, 1, 1, 1], &[]);
    }

    #[test]
    #[should_panic(expected = "SLICE-LENGTH-OUT-OF-BOUNDS")]
    fn assert_u8_array_slice_equals_u8_array_panics_at_runtime_on_slice_length_out_of_bounds() {
        // NEGATIVE PIN — SLICE-LENGTH-OUT-OF-BOUNDS gate: a peer
        // sub-array arity `M` that exceeds the outer array's tail
        // cardinality `N - START` MUST panic at runtime with the
        // slice-length-out-of-bounds-named message. Peer gate to
        // the START-OUT-OF-BOUNDS arm above — the two gates
        // jointly enforce `START ≤ N` and `M ≤ N - START` before
        // any content sweep. The offending `M = 5` against
        // `N - START = 5 - 3 = 2` pins the strict `M > N - START`
        // reject arm; the LEGAL exact-fit corner `M == N - START`
        // is covered by the middle-slice acceptance test above.
        assert_u8_array_slice_equals_u8_array::<5, 5, 3>(&[1, 1, 1, 1, 1], &[1, 1, 1, 1, 1]);
    }

    #[test]
    fn assert_u8_array_slice_equals_u8_array_panic_message_names_the_helper_and_slice_equals_array_violation_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — SLICE-EQUALS-ARRAY-
        // VIOLATION arm: the panic message MUST begin with the
        // helper's own name AND identify the failed AXIS as
        // "SLICE-EQUALS-ARRAY-VIOLATION" so downstream diagnostics
        // route the drift back to (a) the helper by string search
        // on `"assert_u8_array_slice_equals_u8_array"` and (b) the
        // failed axis by string search on `"SLICE-EQUALS-ARRAY-
        // VIOLATION"`. Sibling posture to
        // `assert_u8_array_slice_is_scalar_replica_panic_message_names_the_helper_and_slice_block_constancy_violation_axis`
        // on the sibling SLICE-BLOCK-CONSTANCY corner — the shared
        // `"SLICE-"` prefix lets callers grep either the SINGLE-
        // scalar-image or ARRAY-of-length-`M`-image variant by
        // the shared prefix, while the `-BLOCK-CONSTANCY-` /
        // `-EQUALS-ARRAY-` infix disambiguates the CONTRACT
        // SHAPE.
        let outcome = std::panic::catch_unwind(|| {
            assert_u8_array_slice_equals_u8_array::<5, 3, 1>(&[0, 3, 4, 9, 0], &[3, 4, 5]);
        });
        let payload = outcome.expect_err(
            "assert_u8_array_slice_equals_u8_array must panic on a \
             positionwise drift — the reject-positionwise-drift arm \
             is the CONTENT failure mode of the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_u8_array_slice_equals_u8_array panic payload \
                 must be a static &str or String",
            );
        assert!(
            msg.contains("assert_u8_array_slice_equals_u8_array"),
            "assert_u8_array_slice_equals_u8_array panic message \
             {msg:?} must name the helper for provenance-preserving \
             failure diagnostics",
        );
        assert!(
            msg.contains("SLICE-EQUALS-ARRAY-VIOLATION"),
            "assert_u8_array_slice_equals_u8_array panic message \
             {msg:?} must name the failed AXIS (\"SLICE-EQUALS-\
             ARRAY-VIOLATION\") for axis-provenance-preserving \
             failure diagnostics",
        );
    }

    // ── `assert_u8_array_pairwise_distinct` — the `u8` element-type
    // sibling of `assert_char_array_pairwise_distinct` and
    // `assert_str_array_pairwise_distinct`. Sibling posture: same
    // runtime-test surface (accept-empty, accept-singleton, accept-
    // every-family-wide-substrate-array, reject-binary, reject-non-
    // adjacent, reject-terminal, panic-message-provenance) restricted
    // to the `u8` element type. A regression that silently weakens the
    // helper (e.g. flipping `==` to `!=`, dropping the inner `j` loop,
    // or returning early on collision) is caught by the helper's OWN
    // test surface rather than only surfacing as a false-positive on
    // some future `[u8; N]`-typed discriminator array's distinctness pin.

    #[test]
    fn assert_u8_array_pairwise_distinct_accepts_the_empty_array() {
        // Empty array — vacuously pairwise distinct (no pair to
        // collide). The compile-time `const _: () =
        // assert_u8_array_pairwise_distinct(&EMPTY);` would land on
        // this arm, so the runtime call MUST return normally.
        assert_u8_array_pairwise_distinct::<0>(&[]);
    }

    #[test]
    fn assert_u8_array_pairwise_distinct_accepts_singleton_arrays() {
        // Singleton array — vacuously pairwise distinct (only one
        // element, no pair). Cross-arity coverage on the `[u8; 1]`
        // corner of the const-N generic.
        assert_u8_array_pairwise_distinct(&[0u8]);
        assert_u8_array_pairwise_distinct(&[AtomKind::SYMBOL_HASH_DISCRIMINATOR]);
    }

    #[test]
    fn assert_u8_array_pairwise_distinct_accepts_every_family_wide_substrate_array() {
        // Runtime cross-check that the SAME four arrays the module-
        // level `const _: () = ...` witnesses cover at COMPILE time
        // are pairwise distinct. 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 collision at `cargo
        // test`. The pair enforces the theorem at TWO stages of the
        // toolchain. `SexpShape::HASH_DISCRIMINATORS` is excluded
        // per the intentionally-non-injective twelve-shape → seven-
        // byte collapse rule documented on the helper.
        assert_u8_array_pairwise_distinct(&AtomKind::HASH_DISCRIMINATORS);
        assert_u8_array_pairwise_distinct(&QuoteForm::HASH_DISCRIMINATORS);
        assert_u8_array_pairwise_distinct(&crate::error::StructuralKind::HASH_DISCRIMINATORS);
        assert_u8_array_pairwise_distinct(&crate::error::UnquoteForm::HASH_DISCRIMINATORS);
    }

    #[test]
    #[should_panic(expected = "assert_u8_array_pairwise_distinct")]
    fn assert_u8_array_pairwise_distinct_panics_at_runtime_on_binary_collision() {
        // NEGATIVE PIN — binary corner: a two-element array carrying
        // the same byte twice MUST panic at runtime (the const-eval
        // panic surfaces normally when the function is invoked from a
        // runtime context, not just a `const _` context). Pins the
        // helper's OWN reject-collision arm — a regression that
        // silently returned without panicking on a duplicate would
        // slip through the compile-time witnesses' failure mode too.
        assert_u8_array_pairwise_distinct(&[0u8, 0u8]);
    }

    #[test]
    #[should_panic(expected = "assert_u8_array_pairwise_distinct")]
    fn assert_u8_array_pairwise_distinct_panics_at_runtime_on_non_adjacent_collision() {
        // NEGATIVE PIN — non-adjacent corner: the collision fires on
        // ANY (i, j) pair with i < j, not just the adjacent (0, 1)
        // corner. Pins the nested-loop shape of the helper — a
        // regression that walked ONLY the adjacent pairs (i.e., swept
        // `while i + 1 < N { if arr[i] == arr[i+1] { panic } … }`)
        // would silently accept `[0, 1, 0]` (non-adjacent collision
        // at positions 0 and 2), missing the contract.
        assert_u8_array_pairwise_distinct(&[0u8, 1u8, 0u8]);
    }

    #[test]
    #[should_panic(expected = "assert_u8_array_pairwise_distinct")]
    fn assert_u8_array_pairwise_distinct_panics_at_runtime_on_terminal_collision() {
        // NEGATIVE PIN — terminal corner: the collision at the LAST
        // pair (positions N-2 and N-1) MUST also fire. Pins the outer
        // `while i < N` bound — a regression that walked `while i <
        // N - 1` (dropping the last row) would silently accept a
        // collision at the tail.
        assert_u8_array_pairwise_distinct(&[0u8, 1u8, 2u8, 3u8, 3u8]);
    }

    #[test]
    #[should_panic(expected = "assert_u8_array_pairwise_distinct")]
    fn assert_u8_array_pairwise_distinct_panics_at_runtime_on_boundary_byte_collision() {
        // NEGATIVE PIN — u8-domain boundary corner: the reject-arm
        // fires equivalently at the two u8-domain endpoints (`0x00`,
        // `0xff`). Pins the element-type-native `==` on `u8` — a
        // regression that widened the comparison via `as u32` (from
        // an over-mechanical copy of the char sibling's shape) or
        // via a signed-cast (`as i8` collapsing `0xff` to `-1`)
        // would still fire on the `0x00` corner AND on the
        // `0xff` corner because both survive any widening; a truly
        // load-bearing regression here would silently drop the
        // comparison altogether.
        assert_u8_array_pairwise_distinct(&[0xffu8, 0xffu8]);
    }

    #[test]
    fn assert_u8_array_pairwise_distinct_panic_message_names_the_helper() {
        // PANIC-MESSAGE PROVENANCE PIN: the panic message MUST begin
        // with the helper's own name so downstream diagnostics
        // (`cargo check` const-eval error output, test-suite failure
        // reports) route the drift back to the helper by string
        // search — the family-wide contract's failure mode surfaces
        // as an identifiable panic-message prefix rather than as an
        // opaque const-eval error. Sibling posture to the runtime
        // pairwise-distinctness tests that name the ARRAY in their
        // failure message; this pin names the HELPER.
        let outcome = std::panic::catch_unwind(|| {
            assert_u8_array_pairwise_distinct(&[7u8, 7u8]);
        });
        let payload = outcome.expect_err(
            "assert_u8_array_pairwise_distinct must panic on a \
             duplicate — the reject-collision arm is the point of \
             the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_u8_array_pairwise_distinct panic payload \
                 must be a static &str or String",
            );
        assert!(
            msg.contains("assert_u8_array_pairwise_distinct"),
            "assert_u8_array_pairwise_distinct panic message \
             {msg:?} must name the helper for provenance-preserving \
             failure diagnostics",
        );
    }

    // ── `assert_char_pair_array_bijective` — the product-element
    // sibling of the three scalar-element `assert_{char,str,u8}_array_
    // pairwise_distinct` compile-time contract verifiers, restricted
    // to the `(char, char)` product element type at the paired
    // escape-table substrate vocabulary (`Atom::NAMED_ESCAPE_TABLE`,
    // `Atom::ESCAPE_TABLE`). The runtime test surface here matches
    // the scalar-sibling shape (accept-empty, accept-singleton,
    // accept-every-family-wide-substrate-array, reject-left-column-
    // collision, reject-right-column-collision, reject-non-adjacent,
    // reject-terminal, panic-message-provenance-left, panic-message-
    // provenance-right) split across BOTH columns so a regression that
    // silently weakens the helper on EITHER column (e.g. dropping ONE
    // of the two `if arr[i].{0,1} == arr[j].{0,1}` checks, or
    // conflating the two `panic!` calls into one column-anonymous
    // message) is caught by the helper's OWN test surface rather than
    // only surfacing as a false-positive on some future
    // `[(char, char); N]`-typed paired array's bijection pin.

    #[test]
    fn assert_char_pair_array_bijective_accepts_the_empty_array() {
        // Empty array — vacuously bijective (no pair to collide on
        // EITHER column). The compile-time `const _: () =
        // assert_char_pair_array_bijective(&EMPTY);` would land on
        // this arm, so the runtime call MUST return normally.
        assert_char_pair_array_bijective::<0>(&[]);
    }

    #[test]
    fn assert_char_pair_array_bijective_accepts_singleton_arrays() {
        // Singleton array — vacuously bijective (only one pair, so
        // no cross-pair collision is possible on EITHER column even
        // if the two components alias each other WITHIN the pair —
        // that's not a bijection failure, it's the pattern-equals-
        // value SELF-escape shape at `SELF_ESCAPE_TABLE`'s two rows).
        // Cross-arity coverage on the `[(char, char); 1]` corner of
        // the const-N generic.
        assert_char_pair_array_bijective(&[('a', 'b')]);
        assert_char_pair_array_bijective(&[('x', 'x')]);
    }

    #[test]
    fn assert_char_pair_array_bijective_accepts_every_family_wide_substrate_array() {
        // Runtime cross-check that the SAME two paired arrays the
        // module-level `const _: () = ...` witnesses cover at COMPILE
        // time are bijective. 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 collision at `cargo test`. The
        // pair enforces the theorem at TWO stages of the toolchain.
        assert_char_pair_array_bijective(&Atom::NAMED_ESCAPE_TABLE);
        assert_char_pair_array_bijective(&Atom::ESCAPE_TABLE);
    }

    #[test]
    #[should_panic(expected = "assert_char_pair_array_bijective: LEFT column")]
    fn assert_char_pair_array_bijective_panics_at_runtime_on_left_column_collision() {
        // NEGATIVE PIN — LEFT-column corner: a two-element array
        // whose two SOURCE chars alias (regardless of whether the two
        // DECODED chars alias) MUST panic at runtime with the LEFT-
        // column-named message. Pins the helper's OWN LEFT-column
        // reject-arm — a regression that silently returned without
        // panicking on a source-column duplicate would slip through
        // the compile-time witnesses' failure mode too. The two
        // distinct DECODED chars witness that the RIGHT column is
        // INTACT — the panic MUST fire specifically on the LEFT-
        // column disjointness failure.
        assert_char_pair_array_bijective(&[('a', 'x'), ('a', 'y')]);
    }

    #[test]
    #[should_panic(expected = "assert_char_pair_array_bijective: RIGHT column")]
    fn assert_char_pair_array_bijective_panics_at_runtime_on_right_column_collision() {
        // NEGATIVE PIN — RIGHT-column corner: a two-element array
        // whose two DECODED chars alias (with distinct SOURCE chars
        // so the LEFT column is intact) MUST panic at runtime with
        // the RIGHT-column-named message. Column-provenance in the
        // panic message is load-bearing: downstream diagnostics
        // route the drift back to the failed COLUMN (LEFT vs.
        // RIGHT) by string search — the two panic sites MUST NOT
        // collapse into one column-anonymous message.
        assert_char_pair_array_bijective(&[('a', 'x'), ('b', 'x')]);
    }

    #[test]
    #[should_panic(expected = "assert_char_pair_array_bijective")]
    fn assert_char_pair_array_bijective_panics_at_runtime_on_non_adjacent_collision() {
        // NEGATIVE PIN — non-adjacent corner: the collision fires on
        // ANY (i, j) pair with i < j, not just the adjacent (0, 1)
        // corner. Pins the nested-loop shape of the helper — a
        // regression that walked ONLY the adjacent pairs (i.e., swept
        // `while i + 1 < N { if arr[i].0 == arr[i+1].0 { panic } … }`)
        // would silently accept the non-adjacent collision at
        // positions 0 and 2 tested here (a LEFT-column collision
        // `'a'` at [0].0 and [2].0, with `'b'` at [1].0 breaking
        // adjacency).
        assert_char_pair_array_bijective(&[('a', 'x'), ('b', 'y'), ('a', 'z')]);
    }

    #[test]
    #[should_panic(expected = "assert_char_pair_array_bijective")]
    fn assert_char_pair_array_bijective_panics_at_runtime_on_terminal_collision() {
        // NEGATIVE PIN — terminal corner: the collision at the LAST
        // pair (positions N-2 and N-1) MUST also fire. Pins the outer
        // `while i < N` bound — a regression that walked `while i <
        // N - 1` (dropping the last row) would silently accept a
        // collision at the tail. Uses a RIGHT-column collision at
        // the terminal pair to also exercise the second (RIGHT)
        // panic arm's terminal-index reachability, symmetric to the
        // LEFT-column non-adjacent pin above.
        assert_char_pair_array_bijective(&[
            ('a', 'w'),
            ('b', 'x'),
            ('c', 'y'),
            ('d', 'z'),
            ('e', 'z'),
        ]);
    }

    #[test]
    fn assert_char_pair_array_bijective_panic_message_names_the_helper_and_left_column() {
        // PANIC-MESSAGE PROVENANCE PIN — LEFT-column arm: the panic
        // message MUST begin with the helper's own name AND identify
        // the failed COLUMN as "LEFT column" so downstream diagnostics
        // route the drift back to (a) the helper by string search on
        // `"assert_char_pair_array_bijective"` and (b) the column by
        // string search on `"LEFT column"`. Sibling posture to the
        // scalar-sibling `_panic_message_names_the_helper` tests
        // (which name only the helper); the column-provenance
        // extension is load-bearing on the paired-array vocabulary
        // where a bijection failure has TWO distinguishable failure
        // modes (source-column non-injective vs. decoded-column
        // non-injective).
        let outcome = std::panic::catch_unwind(|| {
            assert_char_pair_array_bijective(&[('a', 'x'), ('a', 'y')]);
        });
        let payload = outcome.expect_err(
            "assert_char_pair_array_bijective must panic on a LEFT-\
             column duplicate — the reject-collision arm is the \
             point of the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_pair_array_bijective panic payload \
                 must be a static &str or String",
            );
        assert!(
            msg.contains("assert_char_pair_array_bijective"),
            "assert_char_pair_array_bijective LEFT-column panic \
             message {msg:?} must name the helper for provenance-\
             preserving failure diagnostics",
        );
        assert!(
            msg.contains("LEFT column"),
            "assert_char_pair_array_bijective LEFT-column panic \
             message {msg:?} must name the failed COLUMN (\"LEFT \
             column\") for column-provenance-preserving failure \
             diagnostics",
        );
    }

    #[test]
    fn assert_char_pair_array_bijective_panic_message_names_the_helper_and_right_column() {
        // PANIC-MESSAGE PROVENANCE PIN — RIGHT-column arm: the panic
        // message MUST begin with the helper's own name AND identify
        // the failed COLUMN as "RIGHT column". Column-symmetric
        // sibling of the LEFT-column pin above — a regression that
        // silently unified the two panic sites into ONE column-
        // anonymous message would collapse THIS pin's RIGHT-column
        // substring assertion.
        let outcome = std::panic::catch_unwind(|| {
            assert_char_pair_array_bijective(&[('a', 'x'), ('b', 'x')]);
        });
        let payload = outcome.expect_err(
            "assert_char_pair_array_bijective must panic on a RIGHT-\
             column duplicate — the reject-collision arm is the \
             point of the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_pair_array_bijective panic payload \
                 must be a static &str or String",
            );
        assert!(
            msg.contains("assert_char_pair_array_bijective"),
            "assert_char_pair_array_bijective RIGHT-column panic \
             message {msg:?} must name the helper for provenance-\
             preserving failure diagnostics",
        );
        assert!(
            msg.contains("RIGHT column"),
            "assert_char_pair_array_bijective RIGHT-column panic \
             message {msg:?} must name the failed COLUMN (\"RIGHT \
             column\") for column-provenance-preserving failure \
             diagnostics",
        );
    }

    // ── `assert_char_pair_array_pairwise_distinct` — the (char, char)
    // product-element TUPLE-level pairwise-distinctness verifier that
    // binds `∀ i < j. arr[i] ≠ arr[j]` at compile time on the paired-
    // array vocabulary via CONJOINED-tuple equality, WEAKER peer of
    // `assert_char_pair_array_bijective`'s column-INDEPENDENT
    // INJECTIVITY axis on the SAME (char, char) row of the
    // (element-type × contract-shape) matrix. Both bijective ⇒
    // pairwise-distinct-as-tuples witnesses hold on the substrate's
    // two family-wide `[(char, char); N]` arrays (NAMED_ESCAPE_TABLE
    // + ESCAPE_TABLE), so the runtime test surface pins ONLY the
    // helper's OWN reject-arm (tuple-collision at three (adjacent,
    // non-adjacent, terminal) positions) + accept-arms (empty,
    // singletons, per-column-alias-with-distinct-tuples, family-wide
    // substrate arrays) + panic-message-provenance on the CHAR-PAIR-
    // TUPLE-COLLISION axis so a regression that silently weakened
    // the helper on ANY arm is caught by the helper's OWN test
    // surface rather than only surfacing as a false-positive on
    // some future tuple-level pairwise-distinct-but-NOT-bijective
    // `[(char, char); N]` array's compound pin.

    #[test]
    fn assert_char_pair_array_pairwise_distinct_accepts_the_empty_array() {
        // Empty array `arr = []` at the `[(char, char); 0]` corner —
        // vacuously pairwise-distinct at the tuple level (no (i, j)
        // pair with i < j exists to test). Pins the outer `while i <
        // N` guard's short-circuit on `N == 0` — a regression that
        // panicked on the empty array would collapse this pin.
        assert_char_pair_array_pairwise_distinct::<0>(&[]);
    }

    #[test]
    fn assert_char_pair_array_pairwise_distinct_accepts_a_singleton_array() {
        // Singleton array `arr = [(a, b)]` — vacuously pairwise-
        // distinct at the tuple level (no `j > i == 0` position
        // exists to compare against). Cross-corner coverage on the
        // trivial-array face of the const-N generic past the empty
        // corner, closing the two edge cases (N == 0, N == 1) at
        // which the inner sweep is vacuous.
        assert_char_pair_array_pairwise_distinct(&[('a', 'x')]);
    }

    #[test]
    fn assert_char_pair_array_pairwise_distinct_accepts_two_distinct_tuples() {
        // Two-element array with two BYTE-FOR-BYTE-DISTINCT tuples —
        // the smallest non-trivial well-formed case. Both column
        // projections happen to be distinct too (`'a' ≠ 'b'` on the
        // LEFT column, `'x' ≠ 'y'` on the RIGHT column) but the
        // helper reads ONLY the CONJOINED-tuple gate, not the per-
        // column gates — pinned in isolation from the sibling
        // bijective helper's stricter column-independent axis.
        assert_char_pair_array_pairwise_distinct(&[('a', 'x'), ('b', 'y')]);
    }

    #[test]
    fn assert_char_pair_array_pairwise_distinct_accepts_per_column_alias_when_conjoined_tuple_differs(
    ) {
        // Accept-corner load-bearing to the helper's DISTINCTION from
        // the sibling `assert_char_pair_array_bijective`: a pair-
        // array with LEFT-column collision (`'a'` at [0].0 and
        // [1].0) but with DISTINCT RIGHT columns (`'x' ≠ 'y'`) has
        // TWO CONJOINED-tuples `('a', 'x') ≠ ('a', 'y')` that DIFFER
        // — this helper MUST accept it. The bijective sibling would
        // REJECT this pair on its LEFT-column arm because
        // bijectivity is per-column-INDEPENDENT. The two helpers'
        // divergence here is THE point of opening the tuple-level
        // INJECTIVITY axis as a distinct sub-shape past the column-
        // INDEPENDENT INJECTIVITY axis.
        assert_char_pair_array_pairwise_distinct(&[('a', 'x'), ('a', 'y')]);
        // Symmetric RIGHT-column-alias corner with distinct LEFT
        // columns — same accept posture on the OTHER column-alias
        // sibling.
        assert_char_pair_array_pairwise_distinct(&[('a', 'x'), ('b', 'x')]);
    }

    #[test]
    fn assert_char_pair_array_pairwise_distinct_accepts_the_family_wide_substrate_arrays() {
        // Positive pin on the TWO family-wide `[(char, char); N]`
        // paired arrays this helper is applied to at compile time
        // via the module-level `const _:` witnesses: `NAMED_ESCAPE_
        // TABLE` (`[(char, char); 3]`) and `ESCAPE_TABLE` (`[(char,
        // char); 5]`). Both bijective ⇒ pairwise-distinct-as-tuples
        // WITNESSES the compile-time `const _:` pass at runtime for
        // a second-stage safety net if the const-eval sweep is ever
        // silently dropped. Sibling posture to
        // `assert_char_pair_array_bijective`'s
        // `_accepts_the_family_wide_substrate_bijections` on the
        // SAME two arrays — this pin binds the WEAKER tuple-level
        // axis; that pin binds the STRONGER column-independent axis.
        assert_char_pair_array_pairwise_distinct(&Atom::NAMED_ESCAPE_TABLE);
        assert_char_pair_array_pairwise_distinct(&Atom::ESCAPE_TABLE);
    }

    #[test]
    #[should_panic(expected = "assert_char_pair_array_pairwise_distinct")]
    fn assert_char_pair_array_pairwise_distinct_panics_at_runtime_on_adjacent_tuple_collision() {
        // NEGATIVE PIN — adjacent (0, 1) corner: two adjacent
        // CONJOINED-tuples byte-for-byte equal (BOTH columns match
        // in lockstep) MUST panic at runtime. Pins the helper's OWN
        // reject-arm — a regression that silently returned without
        // panicking on a tuple duplicate would slip through the
        // compile-time witnesses' failure mode too.
        assert_char_pair_array_pairwise_distinct(&[('a', 'x'), ('a', 'x')]);
    }

    #[test]
    #[should_panic(expected = "assert_char_pair_array_pairwise_distinct")]
    fn assert_char_pair_array_pairwise_distinct_panics_at_runtime_on_non_adjacent_tuple_collision()
    {
        // NEGATIVE PIN — non-adjacent (0, 2) corner: the collision
        // fires on ANY (i, j) pair with i < j, not just the
        // adjacent (0, 1) corner. Pins the nested-loop shape of the
        // helper — a regression that walked ONLY the adjacent pairs
        // (i.e., swept `while i + 1 < N { if arr[i] == arr[i+1] {
        // panic } … }`) would silently accept the non-adjacent
        // collision at positions 0 and 2 tested here (a tuple
        // collision at ('a', 'x') across [0] and [2], with the
        // distinct ('b', 'y') at [1] breaking adjacency). Sibling
        // posture to `assert_char_pair_array_bijective_panics_at_
        // runtime_on_non_adjacent_collision` on the column-
        // independent axis — the loop-shape pin is row-parallel.
        assert_char_pair_array_pairwise_distinct(&[('a', 'x'), ('b', 'y'), ('a', 'x')]);
    }

    #[test]
    #[should_panic(expected = "assert_char_pair_array_pairwise_distinct")]
    fn assert_char_pair_array_pairwise_distinct_panics_at_runtime_on_terminal_tuple_collision() {
        // NEGATIVE PIN — terminal corner: the collision at the LAST
        // pair (positions N-2 and N-1) MUST also fire. Pins the
        // outer `while i < N` bound — a regression that walked
        // `while i < N - 1` (dropping the last row) would silently
        // accept a collision at the tail. Uses a tuple collision at
        // the terminal pair (`('e', 'z')` at [3] and [4]).
        assert_char_pair_array_pairwise_distinct(&[
            ('a', 'w'),
            ('b', 'x'),
            ('c', 'y'),
            ('e', 'z'),
            ('e', 'z'),
        ]);
    }

    #[test]
    fn assert_char_pair_array_pairwise_distinct_panic_message_names_the_helper_and_char_pair_tuple_collision_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — CHAR-PAIR-TUPLE-COLLISION
        // arm: the panic message MUST begin with the helper's own
        // name AND identify the failed AXIS as "CHAR-PAIR-TUPLE-
        // COLLISION" so downstream diagnostics route the drift back
        // to (a) the helper by string search on
        // `"assert_char_pair_array_pairwise_distinct"` and (b) the
        // axis by string search on `"CHAR-PAIR-TUPLE-COLLISION"`.
        // The axis-provenance string `"CHAR-PAIR-TUPLE-COLLISION"`
        // is chosen DISTINCT from EVERY sibling helper's axis
        // vocabulary (`"LEFT column"` / `"RIGHT column"` on the
        // paired-array BIJECTIVITY sibling; `"CHAR-PAIR-SUBSET-
        // VIOLATION"` on the paired-array SUBSET-embedding sibling;
        // `"CHAR-PAIR-DISJOINTNESS-VIOLATION"` on the paired-array
        // DISJOINTNESS sibling) so a diagnostic that names the
        // failed axis routes UNAMBIGUOUSLY to (a) this specific
        // paired-array TUPLE-LEVEL PAIRWISE-DISTINCTNESS helper,
        // (b) the failed axis-shape by the `"TUPLE-COLLISION"`
        // suffix stem distinguishing the CONJOINED-tuple axis from
        // the column-INDEPENDENT axis names used by the bijective
        // sibling.
        let outcome = std::panic::catch_unwind(|| {
            assert_char_pair_array_pairwise_distinct(&[('a', 'x'), ('a', 'x')]);
        });
        let payload = outcome.expect_err(
            "assert_char_pair_array_pairwise_distinct must panic on \
             a CONJOINED-tuple duplicate — the reject-collision arm \
             is the sole CHAR-PAIR-TUPLE-COLLISION failure mode of \
             the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_pair_array_pairwise_distinct panic \
                 payload must be a static &str or String",
            );
        assert!(
            msg.contains("assert_char_pair_array_pairwise_distinct"),
            "assert_char_pair_array_pairwise_distinct panic message \
             {msg:?} must name the helper for provenance-preserving \
             failure diagnostics",
        );
        assert!(
            msg.contains("CHAR-PAIR-TUPLE-COLLISION"),
            "assert_char_pair_array_pairwise_distinct panic message \
             {msg:?} must name the failed AXIS (\"CHAR-PAIR-TUPLE-\
             COLLISION\") for axis-provenance-preserving failure \
             diagnostics",
        );
    }

    // ── `assert_char_pair_array_columns_equal_char_arrays` — the
    // `(char, char)` product-element COLUMN-PROJECTION-EQUALITY
    // verifier that binds a JOINT (LEFT_col == left) ∧ (RIGHT_col ==
    // right) POSITIONWISE-EQUALITY contract at compile time on the
    // (paired-array, peer-scalar-LEFT, peer-scalar-RIGHT) three-way
    // column bond. Opens the (column-projection-equality) column on
    // the (char, char) row of the (element-type × contract-shape)
    // matrix past the pre-existing (INJECTIVITY, SUBSET-EMBEDDING,
    // DISJOINTNESS) triple. Runtime test surface pins each of the
    // helper's arms (accept-empty, accept-singleton-equal, accept-
    // multi-element-equal, accept-family-wide-substrate-triple on
    // the pinned (`ESCAPE_TABLE`, `ESCAPE_SOURCES`, `ESCAPE_DECODED`)
    // triple, reject-LEFT-divergence at head / middle / tail, reject-
    // RIGHT-divergence at head / middle / tail, panic-message-
    // provenance on BOTH the LEFT-COLUMN-DIVERGENCE and RIGHT-
    // COLUMN-DIVERGENCE axes) so a regression that silently weakened
    // the helper on ANY arm is caught by the helper's OWN test
    // surface rather than only surfacing as a false-positive on some
    // future column-bonded `[(char, char); N]` array's compound pin.

    #[test]
    fn assert_char_pair_array_columns_equal_char_arrays_accepts_the_empty_triple() {
        // Empty arrays `pairs = []`, `left = []`, `right = []` at
        // the `[(char, char); 0]` + two `[char; 0]` corner —
        // vacuously column-equal (no `i` position exists to test).
        // Pins the outer `while i < N` guard's short-circuit on
        // `N == 0`. Turbofish binding required because there's no
        // other cue for the const parameter on the three empty
        // array literals.
        assert_char_pair_array_columns_equal_char_arrays::<0>(&[], &[], &[]);
    }

    #[test]
    fn assert_char_pair_array_columns_equal_char_arrays_accepts_a_singleton_triple() {
        // Singleton triple `pairs = [('a', 'x')]`, `left = ['a']`,
        // `right = ['x']` — the smallest non-trivial well-formed
        // case. Both column-projections match position-for-position.
        assert_char_pair_array_columns_equal_char_arrays(&[('a', 'x')], &['a'], &['x']);
    }

    #[test]
    fn assert_char_pair_array_columns_equal_char_arrays_accepts_a_multi_element_triple() {
        // Three-element triple with three BYTE-FOR-BYTE-EQUAL
        // column projections — pins the inner loop's `i += 1`
        // advancement and the sweep's coverage of BOTH clauses at
        // EACH position (a regression that returned early after
        // position 0 would silently accept a mismatch at position
        // 1 or 2).
        assert_char_pair_array_columns_equal_char_arrays(
            &[('a', 'x'), ('b', 'y'), ('c', 'z')],
            &['a', 'b', 'c'],
            &['x', 'y', 'z'],
        );
    }

    #[test]
    fn assert_char_pair_array_columns_equal_char_arrays_accepts_the_family_wide_substrate_triple() {
        // Positive pin on the family-wide (`ESCAPE_TABLE`,
        // `ESCAPE_SOURCES`, `ESCAPE_DECODED`) triple this helper is
        // applied to at compile time via the module-level `const _:`
        // witness. Runtime pin as a second-stage safety net if the
        // const-eval sweep is ever silently dropped. Sibling posture
        // to the `_bijective` + `_pairwise_distinct` family-wide pins
        // on the same paired array — the three pins bind
        // complementary axes of the same substrate table.
        assert_char_pair_array_columns_equal_char_arrays(
            &Atom::ESCAPE_TABLE,
            &Atom::ESCAPE_SOURCES,
            &Atom::ESCAPE_DECODED,
        );
    }

    #[test]
    #[should_panic(expected = "assert_char_pair_array_columns_equal_char_arrays")]
    fn assert_char_pair_array_columns_equal_char_arrays_panics_at_runtime_on_left_head_divergence()
    {
        // NEGATIVE PIN — LEFT-column head-position (i == 0) corner:
        // `pairs[0].0 = 'a'` diverges from `left[0] = 'z'` on the
        // FIRST position. Pins the LEFT arm firing at the head — a
        // regression that started the sweep at `i = 1` would
        // silently accept a head-position divergence.
        assert_char_pair_array_columns_equal_char_arrays(
            &[('a', 'x'), ('b', 'y')],
            &['z', 'b'],
            &['x', 'y'],
        );
    }

    #[test]
    #[should_panic(expected = "assert_char_pair_array_columns_equal_char_arrays")]
    fn assert_char_pair_array_columns_equal_char_arrays_panics_at_runtime_on_left_middle_divergence(
    ) {
        // NEGATIVE PIN — LEFT-column middle-position (i == 1)
        // corner: divergence fires on ANY interior position, not
        // just the head. Pins the loop-shape of the LEFT arm — a
        // regression that walked ONLY the head would silently
        // accept the middle-position divergence at position 1.
        assert_char_pair_array_columns_equal_char_arrays(
            &[('a', 'x'), ('b', 'y'), ('c', 'z')],
            &['a', 'q', 'c'],
            &['x', 'y', 'z'],
        );
    }

    #[test]
    #[should_panic(expected = "assert_char_pair_array_columns_equal_char_arrays")]
    fn assert_char_pair_array_columns_equal_char_arrays_panics_at_runtime_on_left_tail_divergence()
    {
        // NEGATIVE PIN — LEFT-column tail-position (i == N-1)
        // corner: divergence at the LAST position MUST also fire.
        // Pins the outer `while i < N` bound — a regression that
        // walked `while i < N - 1` (dropping the last row) would
        // silently accept a tail LEFT-column divergence.
        assert_char_pair_array_columns_equal_char_arrays(
            &[('a', 'x'), ('b', 'y'), ('c', 'z')],
            &['a', 'b', 'q'],
            &['x', 'y', 'z'],
        );
    }

    #[test]
    #[should_panic(expected = "assert_char_pair_array_columns_equal_char_arrays")]
    fn assert_char_pair_array_columns_equal_char_arrays_panics_at_runtime_on_right_head_divergence()
    {
        // NEGATIVE PIN — RIGHT-column head-position (i == 0) corner:
        // symmetric to the LEFT arm at the head — pins the RIGHT
        // arm firing at position 0 with the LEFT arm satisfied.
        assert_char_pair_array_columns_equal_char_arrays(
            &[('a', 'x'), ('b', 'y')],
            &['a', 'b'],
            &['q', 'y'],
        );
    }

    #[test]
    #[should_panic(expected = "assert_char_pair_array_columns_equal_char_arrays")]
    fn assert_char_pair_array_columns_equal_char_arrays_panics_at_runtime_on_right_middle_divergence(
    ) {
        // NEGATIVE PIN — RIGHT-column middle-position (i == 1)
        // corner: symmetric to the LEFT-middle arm — pins the
        // RIGHT arm firing at an interior position with the LEFT
        // arm satisfied at every position.
        assert_char_pair_array_columns_equal_char_arrays(
            &[('a', 'x'), ('b', 'y'), ('c', 'z')],
            &['a', 'b', 'c'],
            &['x', 'q', 'z'],
        );
    }

    #[test]
    #[should_panic(expected = "assert_char_pair_array_columns_equal_char_arrays")]
    fn assert_char_pair_array_columns_equal_char_arrays_panics_at_runtime_on_right_tail_divergence()
    {
        // NEGATIVE PIN — RIGHT-column tail-position (i == N-1)
        // corner: symmetric to the LEFT-tail arm — pins the outer
        // sweep bound on the RIGHT arm with the LEFT arm satisfied.
        assert_char_pair_array_columns_equal_char_arrays(
            &[('a', 'x'), ('b', 'y'), ('c', 'z')],
            &['a', 'b', 'c'],
            &['x', 'y', 'q'],
        );
    }

    #[test]
    fn assert_char_pair_array_columns_equal_char_arrays_panic_message_names_the_helper_and_left_column_divergence_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — LEFT-COLUMN-DIVERGENCE
        // arm: the panic message MUST begin with the helper's own
        // name AND identify the failed AXIS as "LEFT-COLUMN-
        // DIVERGENCE" so downstream diagnostics route the drift
        // back to (a) the helper by string search on
        // `"assert_char_pair_array_columns_equal_char_arrays"` and
        // (b) the axis by string search on
        // `"LEFT-COLUMN-DIVERGENCE"`. The axis-provenance string
        // is chosen DISTINCT from every sibling helper's axis
        // vocabulary — a diagnostic that names the failed axis
        // routes UNAMBIGUOUSLY to this specific paired-array
        // COLUMN-PROJECTION-EQUALITY helper's LEFT arm.
        let outcome = std::panic::catch_unwind(|| {
            assert_char_pair_array_columns_equal_char_arrays(
                &[('a', 'x'), ('b', 'y')],
                &['z', 'b'],
                &['x', 'y'],
            );
        });
        let payload = outcome.expect_err(
            "assert_char_pair_array_columns_equal_char_arrays must \
             panic on a LEFT-column POSITIONWISE-EQUALITY divergence",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_pair_array_columns_equal_char_arrays \
                 panic payload must be a static &str or String",
            );
        assert!(
            msg.contains("assert_char_pair_array_columns_equal_char_arrays"),
            "assert_char_pair_array_columns_equal_char_arrays panic \
             message {msg:?} must name the helper for provenance-\
             preserving failure diagnostics",
        );
        assert!(
            msg.contains("LEFT-COLUMN-DIVERGENCE"),
            "assert_char_pair_array_columns_equal_char_arrays panic \
             message {msg:?} must name the failed AXIS (\"LEFT-\
             COLUMN-DIVERGENCE\") for axis-provenance-preserving \
             failure diagnostics",
        );
    }

    #[test]
    fn assert_char_pair_array_columns_equal_char_arrays_panic_message_names_the_helper_and_right_column_divergence_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — RIGHT-COLUMN-DIVERGENCE
        // arm: symmetric to the LEFT-column-divergence provenance
        // pin. The panic message MUST begin with the helper's own
        // name AND identify the failed AXIS as "RIGHT-COLUMN-
        // DIVERGENCE" — the two axis-provenance strings
        // (`"LEFT-COLUMN-DIVERGENCE"` + `"RIGHT-COLUMN-DIVERGENCE"`)
        // partition the helper's failure modes into TWO disjoint
        // arms so a diagnostic that names the axis routes
        // UNAMBIGUOUSLY to the specific COLUMN that diverged.
        let outcome = std::panic::catch_unwind(|| {
            assert_char_pair_array_columns_equal_char_arrays(
                &[('a', 'x'), ('b', 'y')],
                &['a', 'b'],
                &['q', 'y'],
            );
        });
        let payload = outcome.expect_err(
            "assert_char_pair_array_columns_equal_char_arrays must \
             panic on a RIGHT-column POSITIONWISE-EQUALITY \
             divergence",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_pair_array_columns_equal_char_arrays \
                 panic payload must be a static &str or String",
            );
        assert!(
            msg.contains("assert_char_pair_array_columns_equal_char_arrays"),
            "assert_char_pair_array_columns_equal_char_arrays panic \
             message {msg:?} must name the helper for provenance-\
             preserving failure diagnostics",
        );
        assert!(
            msg.contains("RIGHT-COLUMN-DIVERGENCE"),
            "assert_char_pair_array_columns_equal_char_arrays panic \
             message {msg:?} must name the failed AXIS (\"RIGHT-\
             COLUMN-DIVERGENCE\") for axis-provenance-preserving \
             failure diagnostics",
        );
    }

    // ── `assert_char_pair_array_columns_cross_disjoint` — the
    // `(char, char)` product-element WITHIN-ARRAY CROSS-COLUMN
    // disjointness verifier that binds `LEFT column ∩ RIGHT column
    // = ∅` at compile time on a pattern-DISTINCT-from-value paired-
    // array vocabulary. Peer to the four prior paired-array verifiers
    // on the SAME row (`_pairwise_distinct` — CONJOINED-tuple
    // INJECTIVITY; `_bijective` — per-column INJECTIVITY;
    // `_within_char_pair_finite_set` — SUBSET-EMBEDDING;
    // `_arrays_disjoint` — BETWEEN-ARRAY CONJOINED-tuple
    // DISJOINTNESS): where the four siblings close within-tuple /
    // within-column / between-array axes, this helper closes the
    // WITHIN-ARRAY CROSS-COLUMN-CHARACTER axis. The runtime test
    // surface pins each of the helper's arms (accept-empty-array,
    // accept-singleton-when-left-disjoint-from-right, accept-multi-
    // element-when-cross-disjoint, accept-substrate-family-wide-
    // NAMED_ESCAPE_TABLE, accept-when-left-column-duplicates-with-
    // cross-disjoint-preserved, reject-diagonal-collision, reject-
    // head-left-matches-head-right-off-diagonal, reject-head-left-
    // matches-tail-right, reject-tail-left-matches-head-right,
    // reject-tail-left-matches-tail-right, panic-message-provenance
    // on the CROSS-COLUMN-COLLISION axis) so a regression that
    // silently weakened the helper on ANY arm is caught by the
    // helper's OWN test surface rather than only surfacing as a
    // false-positive on some future pattern-DISTINCT-from-value
    // `[(char, char); N]` array's compound pin.

    #[test]
    fn assert_char_pair_array_columns_cross_disjoint_accepts_the_empty_array() {
        // Empty array `arr = []` at the `[(char, char); 0]` corner —
        // vacuously cross-column-disjoint (no `(i, j)` position pair
        // exists to test). Pins the outer `while i < N` guard's
        // short-circuit on `N == 0`. Turbofish binding required
        // because there's no other cue for the const parameter on
        // the empty array literal.
        assert_char_pair_array_columns_cross_disjoint::<0>(&[]);
    }

    #[test]
    fn assert_char_pair_array_columns_cross_disjoint_accepts_a_singleton_when_left_disjoint_from_right(
    ) {
        // Singleton `arr = [('a', 'x')]` — LEFT column = {'a'},
        // RIGHT column = {'x'}, disjoint. Pins the singleton corner
        // where the ONLY `(i, j)` position pair is `(0, 0)` on the
        // diagonal and `arr[0].0 != arr[0].1` so the diagonal arm
        // does NOT fire.
        assert_char_pair_array_columns_cross_disjoint(&[('a', 'x')]);
    }

    #[test]
    fn assert_char_pair_array_columns_cross_disjoint_accepts_a_multi_element_when_cross_disjoint() {
        // Three-element `arr = [('a', 'x'), ('b', 'y'), ('c', 'z')]`
        // with LEFT = {'a', 'b', 'c'}, RIGHT = {'x', 'y', 'z'},
        // disjoint. Pins the inner sweep's coverage of BOTH
        // diagonal AND off-diagonal `(i, j)` position pairs at
        // EACH `i` — a regression that returned early after
        // position 0 would silently accept a cross-column collision
        // at position 1 or 2 or an off-diagonal cross-column
        // collision at `(0, 1)`, `(1, 0)`, `(0, 2)`, `(2, 0)`,
        // `(1, 2)`, `(2, 1)`.
        assert_char_pair_array_columns_cross_disjoint(&[('a', 'x'), ('b', 'y'), ('c', 'z')]);
    }

    #[test]
    fn assert_char_pair_array_columns_cross_disjoint_accepts_the_family_wide_substrate_named_escape_table(
    ) {
        // Positive pin on the family-wide `Atom::NAMED_ESCAPE_TABLE`
        // paired array this helper is applied to at compile time via
        // the module-level `const _:` witness. Runtime pin as a
        // second-stage safety net if the const-eval sweep is ever
        // silently dropped. Sibling posture to the `_bijective` +
        // `_pairwise_distinct` family-wide pins on the same paired
        // array — the three pins bind complementary INJECTIVITY axes
        // (per-column, per-tuple, per-CROSS-column) of the same
        // substrate table. LEFT column = {'n', 't', 'r'} (printable
        // ASCII source chars), RIGHT column = {'\n', '\t', '\r'}
        // (control character decoded values), disjoint by algebra
        // design.
        assert_char_pair_array_columns_cross_disjoint(&Atom::NAMED_ESCAPE_TABLE);
    }

    #[test]
    fn assert_char_pair_array_columns_cross_disjoint_accepts_when_left_column_duplicates_but_cross_disjoint_preserved(
    ) {
        // Orthogonality with `_bijective`: a table like
        // `[('a', 'x'), ('a', 'y')]` VIOLATES per-column INJECTIVITY
        // (LEFT column repeats 'a') but PASSES cross-column
        // disjointness (LEFT = {'a'}, RIGHT = {'x', 'y'} are
        // disjoint). Pins this helper's axis as INDEPENDENT of
        // `_bijective` — a diagnostic that names CROSS-COLUMN-
        // COLLISION routes UNAMBIGUOUSLY to a cross-column drift,
        // not to a per-column duplicate.
        assert_char_pair_array_columns_cross_disjoint(&[('a', 'x'), ('a', 'y')]);
        // Symmetric orthogonality on the RIGHT column: a table like
        // `[('a', 'x'), ('b', 'x')]` VIOLATES per-column INJECTIVITY
        // (RIGHT column repeats 'x') but PASSES cross-column
        // disjointness (LEFT = {'a', 'b'}, RIGHT = {'x'} are
        // disjoint).
        assert_char_pair_array_columns_cross_disjoint(&[('a', 'x'), ('b', 'x')]);
    }

    #[test]
    #[should_panic(expected = "assert_char_pair_array_columns_cross_disjoint")]
    fn assert_char_pair_array_columns_cross_disjoint_panics_at_runtime_on_diagonal_collision() {
        // NEGATIVE PIN — diagonal `(i == j == 0)` corner: `arr[0] =
        // ('a', 'a')` collides with itself across columns. Pins the
        // inner sweep INCLUDING the `j == i` case — a regression that
        // set `j = i + 1` (skipping the diagonal) would silently
        // accept a `('a', 'a')` self-mapping pair, which is EXACTLY
        // the SELF-arm identity-relation shape the pattern-DISTINCT-
        // from-value sub-vocabulary MUST NOT carry.
        assert_char_pair_array_columns_cross_disjoint(&[('a', 'a')]);
    }

    #[test]
    #[should_panic(expected = "assert_char_pair_array_columns_cross_disjoint")]
    fn assert_char_pair_array_columns_cross_disjoint_panics_at_runtime_on_diagonal_collision_at_interior_position(
    ) {
        // NEGATIVE PIN — interior diagonal `(i == j == 1)` corner:
        // pins the diagonal arm firing at ANY interior position,
        // not just the head. A regression that started the sweep
        // at `i = 1` for `j` (skipping the diagonal at each `i`)
        // would silently accept a `('b', 'b')` self-mapping pair at
        // position 1.
        assert_char_pair_array_columns_cross_disjoint(&[('a', 'x'), ('b', 'b'), ('c', 'z')]);
    }

    #[test]
    #[should_panic(expected = "assert_char_pair_array_columns_cross_disjoint")]
    fn assert_char_pair_array_columns_cross_disjoint_panics_at_runtime_on_head_left_matches_tail_right(
    ) {
        // NEGATIVE PIN — off-diagonal `(i, j) = (0, 1)` corner:
        // `arr[0].0 == 'a'` collides with `arr[1].1 == 'a'` at
        // an off-diagonal position pair. Pins the inner sweep
        // covering `j > i` — a regression that only checked the
        // diagonal `i == j` would silently accept the head LEFT
        // aliasing the tail RIGHT.
        assert_char_pair_array_columns_cross_disjoint(&[('a', 'x'), ('b', 'a')]);
    }

    #[test]
    #[should_panic(expected = "assert_char_pair_array_columns_cross_disjoint")]
    fn assert_char_pair_array_columns_cross_disjoint_panics_at_runtime_on_tail_left_matches_head_right(
    ) {
        // NEGATIVE PIN — off-diagonal `(i, j) = (1, 0)` corner:
        // `arr[1].0 == 'a'` collides with `arr[0].1 == 'a'` at the
        // OTHER off-diagonal orientation. Pins the inner sweep
        // covering `j < i` — a regression that only checked `j >=
        // i` would silently accept the tail LEFT aliasing the head
        // RIGHT.
        assert_char_pair_array_columns_cross_disjoint(&[('x', 'a'), ('a', 'y')]);
    }

    #[test]
    #[should_panic(expected = "assert_char_pair_array_columns_cross_disjoint")]
    fn assert_char_pair_array_columns_cross_disjoint_panics_at_runtime_on_tail_position_diagonal_collision(
    ) {
        // NEGATIVE PIN — tail-position diagonal `(i == j == N-1)`
        // corner: pins the outer `while i < N` bound INCLUDING the
        // last row — a regression that walked `while i < N - 1`
        // (dropping the last row) would silently accept a tail-
        // position `('c', 'c')` diagonal collision.
        assert_char_pair_array_columns_cross_disjoint(&[('a', 'x'), ('b', 'y'), ('c', 'c')]);
    }

    #[test]
    fn assert_char_pair_array_columns_cross_disjoint_panic_message_names_the_helper_and_cross_column_collision_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — CROSS-COLUMN-COLLISION arm:
        // the panic message MUST begin with the helper's own name
        // AND identify the failed AXIS as "CROSS-COLUMN-COLLISION"
        // so downstream diagnostics route the drift back to (a) the
        // helper by string search on
        // `"assert_char_pair_array_columns_cross_disjoint"` and (b)
        // the axis by string search on `"CROSS-COLUMN-COLLISION"`.
        // The axis-provenance string is chosen DISTINCT from every
        // sibling helper's axis vocabulary (`"CHAR-PAIR-TUPLE-
        // COLLISION"` on `_pairwise_distinct`, `"LEFT column"` /
        // `"RIGHT column"` on `_bijective`, `"CHAR-PAIR-SUBSET-
        // VIOLATION"` on `_within_char_pair_finite_set`, `"CHAR-
        // PAIR-DISJOINTNESS-VIOLATION"` on `_arrays_disjoint`,
        // `"LEFT-COLUMN-DIVERGENCE"` / `"RIGHT-COLUMN-DIVERGENCE"`
        // on `_columns_equal_char_arrays`) — a diagnostic that
        // names the failed axis routes UNAMBIGUOUSLY to this
        // specific cross-column-disjointness helper's arm.
        let outcome = std::panic::catch_unwind(|| {
            assert_char_pair_array_columns_cross_disjoint(&[('a', 'a')]);
        });
        let payload = outcome.expect_err(
            "assert_char_pair_array_columns_cross_disjoint must \
             panic on a diagonal `('a', 'a')` self-mapping pair",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_pair_array_columns_cross_disjoint \
                 panic payload must be a static &str or String",
            );
        assert!(
            msg.contains("assert_char_pair_array_columns_cross_disjoint"),
            "assert_char_pair_array_columns_cross_disjoint panic \
             message {msg:?} must name the helper for provenance-\
             preserving failure diagnostics",
        );
        assert!(
            msg.contains("CROSS-COLUMN-COLLISION"),
            "assert_char_pair_array_columns_cross_disjoint panic \
             message {msg:?} must name the failed AXIS (\"CROSS-\
             COLUMN-COLLISION\") for axis-provenance-preserving \
             failure diagnostics",
        );
    }

    // ── `assert_char_pair_array_is_concatenation_of_char_pair_array_
    // and_char_array_diagonal` — the `(char, char)` product-element
    // SEGMENTED-CONCATENATION-with-DIAGONAL-TAIL verifier that binds
    // the composite-construction identity `arr == head ++
    // diagonal(tail_diag)` at compile time on a paired-array
    // vocabulary composed from a peer paired HEAD + a peer scalar
    // DIAGONAL TAIL. Peer to the `_columns_equal_char_arrays` cross-
    // row-bond sibling — where the sibling binds the FULL column-
    // projection bond across TWO peer scalar arrays at EVERY position,
    // this helper binds the SEGMENTED composite-construction bond
    // across a peer paired vocabulary (head) and a peer scalar
    // vocabulary (diagonally embedded tail). The runtime test surface
    // pins each of the helper's arms (accept-empty-triple, accept-
    // head-only, accept-diagonal-tail-only, accept-mixed-small-triple,
    // accept-family-wide-substrate-triple, reject-head-left-head-
    // position, reject-head-left-tail-position, reject-head-right-
    // head-position, reject-head-right-tail-position, reject-
    // diagonal-tail-left-head-position, reject-diagonal-tail-left-
    // tail-position, reject-diagonal-tail-right-head-position, reject-
    // diagonal-tail-right-tail-position, reject-cardinality-mismatch
    // on `K + M != N`, panic-message-provenance on FIVE distinct
    // AXES) so a regression that silently weakened the helper on ANY
    // arm is caught by the helper's OWN test surface rather than only
    // surfacing as a false-positive on some future composite-
    // constructed `[(char, char); N]` array's compound pin.

    #[test]
    fn assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal_accepts_the_empty_triple(
    ) {
        // Empty arrays `arr = []`, `head = []`, `tail_diag = []` at
        // the `[(char, char); 0]` + `[(char, char); 0]` + `[char; 0]`
        // corner — vacuously composite (no position exists to test).
        // Pins the outer sweep bounds' short-circuit on `N == K ==
        // M == 0`. Turbofish binding required because there's no
        // other cue for the const parameters on the three empty
        // array literals.
        assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal::<0, 0, 0>(
            &[],
            &[],
            &[],
        );
    }

    #[test]
    fn assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal_accepts_head_only_triple(
    ) {
        // Head-only triple `arr = [('a','x')]`, `head = [('a','x')]`,
        // `tail_diag = []` at the `M == 0` corner — the composite
        // reduces to the peer paired HEAD verbatim, no diagonal-
        // embedding. Pins the outer `while j < M` guard's short-
        // circuit on empty tail. Turbofish binding required for the
        // three const parameters.
        assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal::<1, 1, 0>(
            &[('a', 'x')],
            &[('a', 'x')],
            &[],
        );
    }

    #[test]
    fn assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal_accepts_diagonal_tail_only_triple(
    ) {
        // Diagonal-tail-only triple `arr = [('q','q')]`, `head = []`,
        // `tail_diag = ['q']` at the `K == 0` corner — the composite
        // reduces to the DIAGONAL-EMBEDDING of the peer scalar
        // `tail_diag` verbatim, no head. Pins the outer `while i < K`
        // guard's short-circuit on empty head. Turbofish binding
        // required for the three const parameters.
        assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal::<1, 0, 1>(
            &[('q', 'q')],
            &[],
            &['q'],
        );
    }

    #[test]
    fn assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal_accepts_mixed_small_triple(
    ) {
        // Mixed small triple `arr = [('a','x'), ('q','q')]`, `head =
        // [('a','x')]`, `tail_diag = ['q']` at the `K == 1, M == 1`
        // corner — the smallest non-trivial case that exercises BOTH
        // segments. Pins that BOTH sweeps advance and that BOTH arms
        // cover their columns at their positions. A regression that
        // silently walked ONLY the head OR ONLY the tail would
        // silently accept a divergence on the un-swept segment.
        assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal::<2, 1, 1>(
            &[('a', 'x'), ('q', 'q')],
            &[('a', 'x')],
            &['q'],
        );
    }

    #[test]
    fn assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal_accepts_the_family_wide_substrate_triple(
    ) {
        // Positive pin on the family-wide (`Atom::ESCAPE_TABLE`,
        // `Atom::NAMED_ESCAPE_TABLE`, `Atom::SELF_ESCAPE_TABLE`)
        // triple this helper is applied to at compile time via the
        // module-level `const _:` witness. Runtime pin as a second-
        // stage safety net if the const-eval sweep is ever silently
        // dropped. SIXTH witness posture on the same paired array in
        // complementary posture to the FIVE prior sibling helper
        // family-wide pins (`_pairwise_distinct`, `_bijective`,
        // `_within_char_pair_finite_set`, `_arrays_disjoint`,
        // `_columns_equal_char_arrays`) — the six pins bind six
        // complementary axes of the same substrate table.
        assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal(
            &Atom::ESCAPE_TABLE,
            &Atom::NAMED_ESCAPE_TABLE,
            &Atom::SELF_ESCAPE_TABLE,
        );
    }

    #[test]
    #[should_panic(
        expected = "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal"
    )]
    fn assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal_panics_at_runtime_on_head_left_head_position_divergence(
    ) {
        // NEGATIVE PIN — HEAD-SEGMENT LEFT-column head-position
        // (i == 0) corner: `arr[0].0 = 'z'` diverges from `head[0].0
        // = 'a'` on the FIRST head-segment position. Pins the HEAD-
        // LEFT arm firing at the head — a regression that started
        // the head sweep at `i = 1` would silently accept a head-
        // position divergence.
        assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal::<3, 2, 1>(
            &[('z', 'x'), ('b', 'y'), ('q', 'q')],
            &[('a', 'x'), ('b', 'y')],
            &['q'],
        );
    }

    #[test]
    #[should_panic(
        expected = "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal"
    )]
    fn assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal_panics_at_runtime_on_head_left_tail_position_divergence(
    ) {
        // NEGATIVE PIN — HEAD-SEGMENT LEFT-column tail-position
        // (i == K-1) corner: divergence at the LAST head-segment
        // position MUST also fire. Pins the outer head-sweep bound
        // `while i < K` — a regression that walked `while i < K - 1`
        // (dropping the last head row) would silently accept a tail-
        // of-head LEFT-column divergence.
        assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal::<3, 2, 1>(
            &[('a', 'x'), ('z', 'y'), ('q', 'q')],
            &[('a', 'x'), ('b', 'y')],
            &['q'],
        );
    }

    #[test]
    #[should_panic(
        expected = "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal"
    )]
    fn assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal_panics_at_runtime_on_head_right_head_position_divergence(
    ) {
        // NEGATIVE PIN — HEAD-SEGMENT RIGHT-column head-position
        // (i == 0) corner: symmetric to the HEAD-LEFT arm at the
        // head — pins the HEAD-RIGHT arm firing at position 0 with
        // the HEAD-LEFT arm satisfied.
        assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal::<3, 2, 1>(
            &[('a', 'z'), ('b', 'y'), ('q', 'q')],
            &[('a', 'x'), ('b', 'y')],
            &['q'],
        );
    }

    #[test]
    #[should_panic(
        expected = "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal"
    )]
    fn assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal_panics_at_runtime_on_head_right_tail_position_divergence(
    ) {
        // NEGATIVE PIN — HEAD-SEGMENT RIGHT-column tail-position
        // (i == K-1) corner: symmetric to the HEAD-LEFT-tail arm —
        // pins the outer head-sweep bound on the RIGHT arm with the
        // LEFT arm satisfied at every position.
        assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal::<3, 2, 1>(
            &[('a', 'x'), ('b', 'z'), ('q', 'q')],
            &[('a', 'x'), ('b', 'y')],
            &['q'],
        );
    }

    #[test]
    #[should_panic(
        expected = "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal"
    )]
    fn assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal_panics_at_runtime_on_diagonal_tail_left_head_position_divergence(
    ) {
        // NEGATIVE PIN — DIAGONAL-TAIL LEFT-column head-position
        // (j == 0, arr[K + 0].0 diverges from `tail_diag[0]`) corner:
        // pins the DIAGONAL-TAIL-LEFT arm firing at the tail segment's
        // FIRST position — a regression that started the tail sweep
        // at `j = 1` would silently accept a head-of-tail LEFT-column
        // divergence.
        assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal::<3, 1, 2>(
            &[('a', 'x'), ('z', 'q'), ('r', 'r')],
            &[('a', 'x')],
            &['q', 'r'],
        );
    }

    #[test]
    #[should_panic(
        expected = "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal"
    )]
    fn assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal_panics_at_runtime_on_diagonal_tail_left_tail_position_divergence(
    ) {
        // NEGATIVE PIN — DIAGONAL-TAIL LEFT-column tail-position
        // (j == M-1, arr[N-1].0 diverges from `tail_diag[M-1]`)
        // corner: pins the outer tail-sweep bound `while j < M` — a
        // regression that walked `while j < M - 1` (dropping the last
        // tail row) would silently accept a tail-of-tail LEFT-column
        // divergence.
        assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal::<3, 1, 2>(
            &[('a', 'x'), ('q', 'q'), ('z', 'r')],
            &[('a', 'x')],
            &['q', 'r'],
        );
    }

    #[test]
    #[should_panic(
        expected = "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal"
    )]
    fn assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal_panics_at_runtime_on_diagonal_tail_right_head_position_divergence(
    ) {
        // NEGATIVE PIN — DIAGONAL-TAIL RIGHT-column head-position
        // (j == 0, arr[K + 0].1 diverges from `tail_diag[0]`) corner:
        // symmetric to the DIAGONAL-TAIL-LEFT arm at the tail-head —
        // pins the DIAGONAL-TAIL-RIGHT arm firing at the tail
        // segment's FIRST position with the LEFT arm satisfied.
        assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal::<3, 1, 2>(
            &[('a', 'x'), ('q', 'z'), ('r', 'r')],
            &[('a', 'x')],
            &['q', 'r'],
        );
    }

    #[test]
    #[should_panic(
        expected = "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal"
    )]
    fn assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal_panics_at_runtime_on_diagonal_tail_right_tail_position_divergence(
    ) {
        // NEGATIVE PIN — DIAGONAL-TAIL RIGHT-column tail-position
        // (j == M-1, arr[N-1].1 diverges from `tail_diag[M-1]`)
        // corner: symmetric to the DIAGONAL-TAIL-LEFT-tail arm —
        // pins the outer tail-sweep bound on the RIGHT arm with the
        // LEFT arm satisfied at every position.
        assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal::<3, 1, 2>(
            &[('a', 'x'), ('q', 'q'), ('r', 'z')],
            &[('a', 'x')],
            &['q', 'r'],
        );
    }

    #[test]
    #[should_panic(
        expected = "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal"
    )]
    fn assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal_panics_at_runtime_on_cardinality_mismatch(
    ) {
        // NEGATIVE PIN — CARDINALITY-MISMATCH corner: `K + M != N`
        // (here `K == 3, M == 3, N == 5` so `K + M == 6 != 5`) fires
        // the CARDINALITY-MISMATCH panic BEFORE any per-position
        // sweep begins. Pins the FIRST guard arm — a regression that
        // silently omitted the arity check would OOB-panic instead
        // OR silently truncate the tail sweep, both of which would
        // corrupt the AXIS-provenance signal downstream diagnostics
        // depend on.
        assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal::<5, 3, 3>(
            &[('a', 'x'), ('b', 'y'), ('c', 'z'), ('q', 'q'), ('r', 'r')],
            &[('a', 'x'), ('b', 'y'), ('c', 'z')],
            &['q', 'r', 's'],
        );
    }

    #[test]
    fn assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal_panic_message_names_the_helper_and_head_left_divergence_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — HEAD-SEGMENT-LEFT-DIVERGENCE
        // arm: the panic message MUST begin with the helper's own
        // name AND identify the failed AXIS as "HEAD-SEGMENT-LEFT-
        // DIVERGENCE" so downstream diagnostics route the drift back
        // to (a) the helper by string search AND (b) the axis by
        // string search on `"HEAD-SEGMENT-LEFT-DIVERGENCE"`.
        let outcome = std::panic::catch_unwind(|| {
            assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal::<
                3,
                2,
                1,
            >(
                &[('z', 'x'), ('b', 'y'), ('q', 'q')],
                &[('a', 'x'), ('b', 'y')],
                &['q'],
            );
        });
        let payload = outcome.expect_err(
            "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal \
             must panic on a HEAD-SEGMENT LEFT-column divergence",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal \
                 panic payload must be a static &str or String",
            );
        assert!(
            msg.contains(
                "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal"
            ),
            "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal \
             panic message {msg:?} must name the helper for \
             provenance-preserving failure diagnostics",
        );
        assert!(
            msg.contains("HEAD-SEGMENT-LEFT-DIVERGENCE"),
            "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal \
             panic message {msg:?} must name the failed AXIS \
             (\"HEAD-SEGMENT-LEFT-DIVERGENCE\") for axis-provenance-\
             preserving failure diagnostics",
        );
    }

    #[test]
    fn assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal_panic_message_names_the_helper_and_head_right_divergence_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — HEAD-SEGMENT-RIGHT-
        // DIVERGENCE arm: symmetric to the HEAD-LEFT arm's
        // provenance pin.
        let outcome = std::panic::catch_unwind(|| {
            assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal::<
                3,
                2,
                1,
            >(
                &[('a', 'z'), ('b', 'y'), ('q', 'q')],
                &[('a', 'x'), ('b', 'y')],
                &['q'],
            );
        });
        let payload = outcome.expect_err(
            "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal \
             must panic on a HEAD-SEGMENT RIGHT-column divergence",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal \
                 panic payload must be a static &str or String",
            );
        assert!(
            msg.contains("HEAD-SEGMENT-RIGHT-DIVERGENCE"),
            "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal \
             panic message {msg:?} must name the failed AXIS \
             (\"HEAD-SEGMENT-RIGHT-DIVERGENCE\") for axis-provenance-\
             preserving failure diagnostics",
        );
    }

    #[test]
    fn assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal_panic_message_names_the_helper_and_diagonal_tail_left_divergence_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — DIAGONAL-TAIL-SEGMENT-LEFT-
        // DIVERGENCE arm: partitions the failure vocabulary DISTINCT
        // from the HEAD-SEGMENT-LEFT-DIVERGENCE arm — a diagnostic
        // that reads the AXIS routes UNAMBIGUOUSLY to the TAIL
        // segment's LEFT column rather than the HEAD segment's.
        let outcome = std::panic::catch_unwind(|| {
            assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal::<
                3,
                1,
                2,
            >(
                &[('a', 'x'), ('z', 'q'), ('r', 'r')],
                &[('a', 'x')],
                &['q', 'r'],
            );
        });
        let payload = outcome.expect_err(
            "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal \
             must panic on a DIAGONAL-TAIL LEFT-column divergence",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal \
                 panic payload must be a static &str or String",
            );
        assert!(
            msg.contains("DIAGONAL-TAIL-SEGMENT-LEFT-DIVERGENCE"),
            "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal \
             panic message {msg:?} must name the failed AXIS \
             (\"DIAGONAL-TAIL-SEGMENT-LEFT-DIVERGENCE\") for axis-\
             provenance-preserving failure diagnostics",
        );
    }

    #[test]
    fn assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal_panic_message_names_the_helper_and_diagonal_tail_right_divergence_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — DIAGONAL-TAIL-SEGMENT-RIGHT-
        // DIVERGENCE arm: symmetric to the DIAGONAL-TAIL-LEFT arm's
        // provenance pin. The FOUR positionwise axes together
        // (HEAD-LEFT, HEAD-RIGHT, DIAGONAL-TAIL-LEFT, DIAGONAL-TAIL-
        // RIGHT) partition the helper's positionwise failure surface
        // into FOUR disjoint arms so a diagnostic reading the AXIS
        // routes UNAMBIGUOUSLY to the specific (segment, column)
        // corner that diverged.
        let outcome = std::panic::catch_unwind(|| {
            assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal::<
                3,
                1,
                2,
            >(
                &[('a', 'x'), ('q', 'z'), ('r', 'r')],
                &[('a', 'x')],
                &['q', 'r'],
            );
        });
        let payload = outcome.expect_err(
            "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal \
             must panic on a DIAGONAL-TAIL RIGHT-column divergence",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal \
                 panic payload must be a static &str or String",
            );
        assert!(
            msg.contains("DIAGONAL-TAIL-SEGMENT-RIGHT-DIVERGENCE"),
            "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal \
             panic message {msg:?} must name the failed AXIS \
             (\"DIAGONAL-TAIL-SEGMENT-RIGHT-DIVERGENCE\") for axis-\
             provenance-preserving failure diagnostics",
        );
    }

    #[test]
    fn assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal_panic_message_names_the_helper_and_cardinality_mismatch_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — CARDINALITY-MISMATCH arm:
        // fires BEFORE any per-position sweep, at a distinct axis
        // vocabulary. Pins the FIRST guard's provenance so a
        // diagnostic reading the axis distinguishes ARITY drift
        // (mistyped turbofish) from CONTENT drift (segment / column
        // divergence).
        let outcome = std::panic::catch_unwind(|| {
            assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal::<
                5,
                3,
                3,
            >(
                &[('a', 'x'), ('b', 'y'), ('c', 'z'), ('q', 'q'), ('r', 'r')],
                &[('a', 'x'), ('b', 'y'), ('c', 'z')],
                &['q', 'r', 's'],
            );
        });
        let payload = outcome.expect_err(
            "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal \
             must panic on a CARDINALITY-MISMATCH `K + M != N`",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal \
                 panic payload must be a static &str or String",
            );
        assert!(
            msg.contains("CARDINALITY-MISMATCH"),
            "assert_char_pair_array_is_concatenation_of_char_pair_array_and_char_array_diagonal \
             panic message {msg:?} must name the failed AXIS \
             (\"CARDINALITY-MISMATCH\") for axis-provenance-preserving \
             failure diagnostics",
        );
    }

    // ── `assert_char_pair_array_slice_equals_char_pair_array` — the
    // `(char, char)` product-element row's SLICE-EQUALS-ARRAY verifier
    // that binds the sub-slice `full[START..START + M) == sub[..]`
    // paired-positionwise-composition contract at compile time. Row-
    // dual peer to `assert_u8_array_slice_equals_u8_array`,
    // `assert_char_array_slice_equals_char_array`, and
    // `assert_str_array_slice_equals_str_array` on the (element-type)
    // axis of the SAME (SUB-SLICE ARRAY-image) column of the (element-
    // type × contract-shape) matrix. The runtime test surface pins
    // each of the helper's arms (accept-canonical-middle-slice,
    // accept-empty-sub-array-at-three-start-positions, accept-full-
    // array-degenerate-at-two-arities, accept-substrate-escape-table-
    // head-segment-decomposition, reject-left-column-drift, reject-
    // right-column-drift, reject-start-out-of-bounds, reject-slice-
    // length-out-of-bounds, panic-message-provenance on the LEFT-
    // COLUMN + RIGHT-COLUMN axes) so a regression that silently
    // weakened the helper on ANY arm (e.g. dropping the LEFT-column
    // check, dropping the RIGHT-column check, dropping the `START`
    // offset from the `full[START + i]` read, returning early past
    // ANY bounds gate, or dropping the `as u32` char-to-scalar bridge
    // that lets the const-eval sweep proceed byte-for-byte on each
    // column) is caught by the helper's OWN test surface rather than
    // only surfacing as a false-positive on some future paired
    // container-array sub-slice equality.

    #[test]
    fn assert_char_pair_array_slice_equals_char_pair_array_accepts_a_canonical_middle_slice() {
        // Canonical paired sub-slice `full[START..START + M) == sub[..]`
        // inside a longer paired array `full` whose ENDPOINTS carry
        // DIFFERENT pairs than the peer sub-array. Pins the outer
        // `while i < M` sweep reads `full[START + i]` at the OFFSET
        // position (not `full[i]`) on BOTH columns — a regression that
        // dropped the `START` offset would compare `full[0..M)`
        // against `sub[..]` and panic on the wrong axis. `START = 1`
        // pins the sweep skips position `[0..START)` and reads only
        // `[1..1+3) = [1..4)` on both columns of the paired sub-array.
        assert_char_pair_array_slice_equals_char_pair_array::<5, 3, 1>(
            &[('z', 'Z'), ('a', 'x'), ('b', 'y'), ('c', 'z'), ('z', 'Z')],
            &[('a', 'x'), ('b', 'y'), ('c', 'z')],
        );
    }

    #[test]
    fn assert_char_pair_array_slice_equals_char_pair_array_accepts_the_empty_sub_array() {
        // LEGAL degenerate: `M == 0` collapses the paired sub-array
        // into an empty listing `[]`. The sweep never enters the loop
        // body and the helper accepts. Cross-position coverage pins
        // the empty-sub-array acceptance at THREE distinct `START`
        // positions (`START == 0` at the left endpoint, `START == 2`
        // in the interior, `START == N` at the right endpoint — the
        // latter is the corner `START == N` combined with `M == 0`
        // that the START-OUT-OF-BOUNDS gate's inclusive upper bound
        // must accept). A regression that hard-coded `START < N` OR
        // panicked on the `M == 0` corner is caught on ALL THREE
        // arms.
        assert_char_pair_array_slice_equals_char_pair_array::<5, 0, 0>(
            &[('x', 'X'), ('x', 'X'), ('x', 'X'), ('x', 'X'), ('x', 'X')],
            &[],
        );
        assert_char_pair_array_slice_equals_char_pair_array::<5, 0, 2>(
            &[('x', 'X'), ('x', 'X'), ('x', 'X'), ('x', 'X'), ('x', 'X')],
            &[],
        );
        assert_char_pair_array_slice_equals_char_pair_array::<5, 0, 5>(
            &[('x', 'X'), ('x', 'X'), ('x', 'X'), ('x', 'X'), ('x', 'X')],
            &[],
        );
    }

    #[test]
    fn assert_char_pair_array_slice_equals_char_pair_array_accepts_the_full_array_degenerate() {
        // Full-array-covering slice `M == N, START == 0` collapses
        // to the ALL-positions-equal-peer-array shape `full == sub`
        // pointwise on BOTH columns. Pins that the sweep proceeds
        // through EVERY position of the outer paired array when
        // `START = 0` and `M = N`. Cross-arity coverage on `N ∈ {2,
        // 3}` pins the sweep's terminal-position visit across the
        // small arities the substrate's paired escape-table
        // vocabulary spans (`N = 2` for a hypothetical two-slot
        // paired table, `N = 3` for `NAMED_ESCAPE_TABLE`).
        assert_char_pair_array_slice_equals_char_pair_array::<2, 2, 0>(
            &[('a', 'x'), ('b', 'y')],
            &[('a', 'x'), ('b', 'y')],
        );
        assert_char_pair_array_slice_equals_char_pair_array::<3, 3, 0>(
            &[('n', '\n'), ('t', '\t'), ('r', '\r')],
            &[('n', '\n'), ('t', '\t'), ('r', '\r')],
        );
    }

    #[test]
    fn assert_char_pair_array_slice_equals_char_pair_array_accepts_the_substrate_escape_table_head_segment(
    ) {
        // Runtime cross-check that the substrate's (ESCAPE_TABLE,
        // NAMED_ESCAPE_TABLE) HEAD-segment positionwise-composition
        // identity `ESCAPE_TABLE[0..3] == NAMED_ESCAPE_TABLE` holds
        // pointwise on BOTH columns. Runs the SAME helper the module-
        // level `const _` witness runs at rustc time — a runtime
        // safety net enforcing the theorem at BOTH stages of the
        // toolchain (const at `cargo check`, runtime at `cargo
        // test`). A regression that renamed one of the three
        // NAMED-escape SOURCE or DECODED entries (or drifted the
        // ordering across ESCAPE_TABLE's first three initializer
        // slots) fails HERE at the substrate callsite AND at the
        // const witness above. Peer of
        // `assert_char_array_slice_equals_char_array_accepts_each_family_wide_substrate_array`
        // on the (char) row — that witness carries the FULL-ARRAY
        // per-position ORDER theorem for the EIGHT reader-boundary
        // `[char; N]` arrays; this witness carries the HEAD-segment
        // per-position ORDER theorem for the substrate's SINGLE
        // paired-composite pair on the `(char, char)` product-
        // element row.
        assert_char_pair_array_slice_equals_char_pair_array::<5, 3, 0>(
            &Atom::ESCAPE_TABLE,
            &Atom::NAMED_ESCAPE_TABLE,
        );
    }

    #[test]
    #[should_panic(expected = "CHAR-PAIR-SLICE-EQUALS-ARRAY-LEFT-COLUMN-VIOLATION")]
    fn assert_char_pair_array_slice_equals_char_pair_array_panics_at_runtime_on_left_column_drift()
    {
        // NEGATIVE PIN — CHAR-PAIR-SLICE-EQUALS-ARRAY-LEFT-COLUMN-
        // VIOLATION corner: a LEFT-column entry at some position in
        // `full[START..START + M)` that does NOT byte-equal the peer
        // sub-array `sub` at the offset-matched position MUST panic
        // at runtime with the axis-named message. Pins the helper's
        // LEFT-column reject arm — a regression that silently
        // dropped the LEFT-column check while retaining the RIGHT-
        // column check would slip through the compile-time witness's
        // LEFT-drift failure mode too. The offending LEFT-column
        // char `'!'` at outer position `3` (interior of the sub-
        // slice `[1..4)`, offset `2` inside `sub`) pins the middle-
        // of-slice LEFT-column drift mode.
        assert_char_pair_array_slice_equals_char_pair_array::<5, 3, 1>(
            &[('z', 'Z'), ('a', 'x'), ('b', 'y'), ('!', 'z'), ('z', 'Z')],
            &[('a', 'x'), ('b', 'y'), ('c', 'z')],
        );
    }

    #[test]
    #[should_panic(expected = "CHAR-PAIR-SLICE-EQUALS-ARRAY-RIGHT-COLUMN-VIOLATION")]
    fn assert_char_pair_array_slice_equals_char_pair_array_panics_at_runtime_on_right_column_drift()
    {
        // NEGATIVE PIN — CHAR-PAIR-SLICE-EQUALS-ARRAY-RIGHT-COLUMN-
        // VIOLATION corner: a RIGHT-column entry at some position in
        // `full[START..START + M)` that does NOT byte-equal the peer
        // sub-array `sub` at the offset-matched position MUST panic
        // at runtime with the axis-named message. Pins the helper's
        // RIGHT-column reject arm — a regression that silently
        // dropped the RIGHT-column check while retaining the LEFT-
        // column check would slip through the compile-time witness's
        // RIGHT-drift failure mode too. The LEFT column matches
        // exactly on every position so ONLY the RIGHT column drift
        // (`'!'` at outer position `3`, offset `2` inside `sub`)
        // fires the reject arm — routing the diagnostic to the
        // RIGHT-COLUMN-* axis rather than the sibling LEFT-COLUMN-*
        // axis.
        assert_char_pair_array_slice_equals_char_pair_array::<5, 3, 1>(
            &[('z', 'Z'), ('a', 'x'), ('b', 'y'), ('c', '!'), ('z', 'Z')],
            &[('a', 'x'), ('b', 'y'), ('c', 'z')],
        );
    }

    #[test]
    #[should_panic(expected = "START-OUT-OF-BOUNDS")]
    fn assert_char_pair_array_slice_equals_char_pair_array_panics_at_runtime_on_start_out_of_bounds(
    ) {
        // NEGATIVE PIN — START-OUT-OF-BOUNDS gate: a caller-side
        // turbofish arity slip on the `START` const-generic where
        // `START > N` MUST panic at runtime with the START-OUT-OF-
        // BOUNDS-named message BEFORE the peer SLICE-LENGTH-OUT-OF-
        // BOUNDS gate reads `N - START` (which would `usize`-
        // underflow had this gate not caught the slip first). Pins
        // the gate's placement at the TOP of the helper — a
        // regression that dropped the gate would either underflow
        // subtraction at the peer gate OR panic deeper in
        // `full[START + i]` bounds-checking with a helper-name-less
        // panic message. The offending `START = 7` against `N = 5`
        // pins the strict `START > N` reject arm; the LEGAL
        // `START == N` empty-slice-at-right-endpoint corner is
        // covered by the peer acceptance test above.
        assert_char_pair_array_slice_equals_char_pair_array::<5, 0, 7>(
            &[('x', 'X'), ('x', 'X'), ('x', 'X'), ('x', 'X'), ('x', 'X')],
            &[],
        );
    }

    #[test]
    #[should_panic(expected = "SLICE-LENGTH-OUT-OF-BOUNDS")]
    fn assert_char_pair_array_slice_equals_char_pair_array_panics_at_runtime_on_slice_length_out_of_bounds(
    ) {
        // NEGATIVE PIN — SLICE-LENGTH-OUT-OF-BOUNDS gate: a peer
        // sub-array arity `M` that exceeds the outer array's tail
        // cardinality `N - START` MUST panic at runtime with the
        // slice-length-out-of-bounds-named message. Peer gate to the
        // START-OUT-OF-BOUNDS arm above — the two gates jointly
        // enforce `START ≤ N` and `M ≤ N - START` before any content
        // sweep. The offending `M = 5` against `N - START = 5 - 3 =
        // 2` pins the strict `M > N - START` reject arm; the LEGAL
        // exact-fit corner `M == N - START` is covered by the
        // middle-slice acceptance test above.
        assert_char_pair_array_slice_equals_char_pair_array::<5, 5, 3>(
            &[('x', 'X'), ('x', 'X'), ('x', 'X'), ('x', 'X'), ('x', 'X')],
            &[('x', 'X'), ('x', 'X'), ('x', 'X'), ('x', 'X'), ('x', 'X')],
        );
    }

    #[test]
    fn assert_char_pair_array_slice_equals_char_pair_array_panic_message_names_the_helper_and_left_column_violation_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — CHAR-PAIR-SLICE-EQUALS-
        // ARRAY-LEFT-COLUMN-VIOLATION arm: the panic message MUST
        // begin with the helper's own name AND identify the failed
        // AXIS as "CHAR-PAIR-SLICE-EQUALS-ARRAY-LEFT-COLUMN-
        // VIOLATION" so downstream diagnostics route the drift back
        // to (a) the helper by string search on
        // `"assert_char_pair_array_slice_equals_char_pair_array"`
        // and (b) the failed COLUMN of the paired sweep by string
        // search on `"CHAR-PAIR-SLICE-EQUALS-ARRAY-LEFT-COLUMN-
        // VIOLATION"`. Sibling posture to the (u8) / (char) / (str)
        // row peers' provenance pins — the FOUR pins together bind
        // the (helper, failed-axis) provenance pair at ONE test per
        // corner of the (SUB-SLICE ARRAY-image) column across the
        // FOUR element-type rows of the matrix.
        let outcome = std::panic::catch_unwind(|| {
            assert_char_pair_array_slice_equals_char_pair_array::<5, 3, 1>(
                &[('z', 'Z'), ('a', 'x'), ('b', 'y'), ('!', 'z'), ('z', 'Z')],
                &[('a', 'x'), ('b', 'y'), ('c', 'z')],
            );
        });
        let payload = outcome.expect_err(
            "assert_char_pair_array_slice_equals_char_pair_array must \
             panic on a LEFT-column drift — the reject-left-column-\
             drift arm is a CONTENT failure mode of the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_pair_array_slice_equals_char_pair_array \
                 panic payload must be a static &str or String",
            );
        assert!(
            msg.contains("assert_char_pair_array_slice_equals_char_pair_array"),
            "assert_char_pair_array_slice_equals_char_pair_array panic \
             message {msg:?} must name the helper for provenance-\
             preserving failure diagnostics",
        );
        assert!(
            msg.contains("CHAR-PAIR-SLICE-EQUALS-ARRAY-LEFT-COLUMN-VIOLATION"),
            "assert_char_pair_array_slice_equals_char_pair_array panic \
             message {msg:?} must name the failed AXIS (\"CHAR-PAIR-\
             SLICE-EQUALS-ARRAY-LEFT-COLUMN-VIOLATION\") for axis-\
             provenance-preserving failure diagnostics",
        );
    }

    #[test]
    fn assert_char_pair_array_slice_equals_char_pair_array_panic_message_names_the_helper_and_right_column_violation_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — CHAR-PAIR-SLICE-EQUALS-
        // ARRAY-RIGHT-COLUMN-VIOLATION arm: the panic message MUST
        // begin with the helper's own name AND identify the failed
        // AXIS as "CHAR-PAIR-SLICE-EQUALS-ARRAY-RIGHT-COLUMN-
        // VIOLATION" so downstream diagnostics route the drift back
        // to (a) the helper by string search AND (b) the failed
        // COLUMN of the paired sweep by string search on the
        // RIGHT-COLUMN-* axis. Peer pin to the LEFT-COLUMN
        // provenance pin above — the two pins bind the (LEFT,
        // RIGHT) column-axis provenance pair at ONE test per column.
        let outcome = std::panic::catch_unwind(|| {
            assert_char_pair_array_slice_equals_char_pair_array::<5, 3, 1>(
                &[('z', 'Z'), ('a', 'x'), ('b', 'y'), ('c', '!'), ('z', 'Z')],
                &[('a', 'x'), ('b', 'y'), ('c', 'z')],
            );
        });
        let payload = outcome.expect_err(
            "assert_char_pair_array_slice_equals_char_pair_array must \
             panic on a RIGHT-column drift — the reject-right-column-\
             drift arm is a CONTENT failure mode of the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_pair_array_slice_equals_char_pair_array \
                 panic payload must be a static &str or String",
            );
        assert!(
            msg.contains("assert_char_pair_array_slice_equals_char_pair_array"),
            "assert_char_pair_array_slice_equals_char_pair_array panic \
             message {msg:?} must name the helper for provenance-\
             preserving failure diagnostics",
        );
        assert!(
            msg.contains("CHAR-PAIR-SLICE-EQUALS-ARRAY-RIGHT-COLUMN-VIOLATION"),
            "assert_char_pair_array_slice_equals_char_pair_array panic \
             message {msg:?} must name the failed AXIS (\"CHAR-PAIR-\
             SLICE-EQUALS-ARRAY-RIGHT-COLUMN-VIOLATION\") for axis-\
             provenance-preserving failure diagnostics",
        );
    }

    // ── `assert_char_array_is_concatenation_of_char_pair_array_column_
    // and_char_array` — the (char) scalar-row SEGMENTED-CONCATENATION-
    // through-PAIRED-COLUMN-PROJECTION verifier that binds `arr ==
    // col(head_table) ++ tail` at compile time on the substrate's Str-
    // payload escape-table (`ESCAPE_SOURCES`, `NAMED_ESCAPE_TABLE`,
    // `SELF_ESCAPE_TABLE`) LEFT-column-projection triple AND the
    // (`ESCAPE_DECODED`, `NAMED_ESCAPE_TABLE`, `SELF_ESCAPE_TABLE`)
    // RIGHT-column-projection triple, CROSS-ROW peer to the (char, char)
    // paired-row (`_is_concatenation_of_char_pair_array_and_char_array_
    // diagonal`) sibling on the (segmented-concatenation) column of the
    // (element-type × contract-shape) matrix. The runtime test surface
    // pins each of the helper's arms — accept the empty triple with
    // BOTH `take_right_column` values, accept a head-only + tail-only +
    // mixed small triple, accept the two family-wide substrate triples
    // for each `take_right_column` value, reject at every failure-arm
    // corner (CARDINALITY-MISMATCH, HEAD-SEGMENT-LEFT/RIGHT-COLUMN-
    // DIVERGENCE at head/tail positions, TAIL-SEGMENT-DIVERGENCE at
    // head/tail positions), pin panic-message provenance on the four
    // axes — so a regression that silently weakened the helper on ANY
    // arm is caught by the helper's OWN test surface rather than only
    // surfacing as a false-positive on some future scalar-composite
    // pin.

    #[test]
    fn assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array_accepts_the_empty_triple_left_column(
    ) {
        // Empty arrays at `N == K == M == 0` with `take_right_column ==
        // false` — vacuously composite (no position exists to test).
        // Pins the outer sweep bounds' short-circuit and the LEFT-column
        // branch's dispatch on the empty head sweep.
        assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array::<0, 0, 0>(
            &[],
            &[],
            &[],
            false,
        );
    }

    #[test]
    fn assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array_accepts_the_empty_triple_right_column(
    ) {
        // Empty arrays at `N == K == M == 0` with `take_right_column ==
        // true` — vacuously composite. Pins the RIGHT-column branch's
        // dispatch on the empty head sweep.
        assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array::<0, 0, 0>(
            &[],
            &[],
            &[],
            true,
        );
    }

    #[test]
    fn assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array_accepts_head_only_triple_left_column(
    ) {
        // Head-only triple `arr = ['a']`, `head_table = [('a','x')]`,
        // `tail = []` with `take_right_column == false` — LEFT column
        // projection at position 0. Pins the `while j < M` guard's
        // short-circuit on empty tail and the LEFT-column arm firing.
        assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array::<1, 1, 0>(
            &['a'],
            &[('a', 'x')],
            &[],
            false,
        );
    }

    #[test]
    fn assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array_accepts_head_only_triple_right_column(
    ) {
        // Head-only triple `arr = ['x']`, `head_table = [('a','x')]`,
        // `tail = []` with `take_right_column == true` — RIGHT column
        // projection at position 0. Pins the RIGHT-column arm firing on
        // the empty-tail short-circuit.
        assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array::<1, 1, 0>(
            &['x'],
            &[('a', 'x')],
            &[],
            true,
        );
    }

    #[test]
    fn assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array_accepts_tail_only_triple(
    ) {
        // Tail-only triple `arr = ['q']`, `head_table = []`, `tail =
        // ['q']` at the `K == 0` corner — the composite reduces to
        // `tail` verbatim, no head-column projection to perform. Pins
        // the outer `while i < K` guard's short-circuit on empty head
        // (identical behavior on both `take_right_column` values —
        // exercised here at `false`; the peer at `true` at the empty-
        // triple test above already covers the RIGHT branch's empty-K
        // dispatch).
        assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array::<1, 0, 1>(
            &['q'],
            &[],
            &['q'],
            false,
        );
    }

    #[test]
    fn assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array_accepts_mixed_small_triple_left_column(
    ) {
        // Mixed small triple `arr = ['a', 'q']`, `head_table =
        // [('a','x')]`, `tail = ['q']` at `K == 1, M == 1` with
        // `take_right_column == false` — the smallest non-trivial case
        // exercising BOTH the LEFT-column head-projection arm and the
        // tail-verbatim arm. Pins that BOTH sweeps advance.
        assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array::<2, 1, 1>(
            &['a', 'q'],
            &[('a', 'x')],
            &['q'],
            false,
        );
    }

    #[test]
    fn assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array_accepts_mixed_small_triple_right_column(
    ) {
        // Mixed small triple `arr = ['x', 'q']`, `head_table =
        // [('a','x')]`, `tail = ['q']` at `K == 1, M == 1` with
        // `take_right_column == true` — the smallest non-trivial case
        // exercising BOTH the RIGHT-column head-projection arm and the
        // tail-verbatim arm.
        assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array::<2, 1, 1>(
            &['x', 'q'],
            &[('a', 'x')],
            &['q'],
            true,
        );
    }

    #[test]
    fn assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array_accepts_the_family_wide_substrate_left_column_triple(
    ) {
        // Positive pin on the family-wide (`Atom::ESCAPE_SOURCES`,
        // `Atom::NAMED_ESCAPE_TABLE`, `Atom::SELF_ESCAPE_TABLE`,
        // `take_right_column: false`) LEFT-column triple this helper
        // is applied to at compile time via the module-level `const
        // _:` witness. Runtime pin as a second-stage safety net if the
        // const-eval sweep is ever silently dropped. Complementary to
        // the pre-existing (`_pairwise_distinct`, `_within_char_
        // finite_set`) witnesses on the SAME scalar array — those
        // pins bind SET-level axes (INJECTIVITY, SUBSET-EMBEDDING);
        // this pin binds the SEGMENTED-CONCATENATION structural
        // identity axis at the (char) scalar-row cross-row bond.
        assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array(
            &Atom::ESCAPE_SOURCES,
            &Atom::NAMED_ESCAPE_TABLE,
            &Atom::SELF_ESCAPE_TABLE,
            false,
        );
    }

    #[test]
    fn assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array_accepts_the_family_wide_substrate_right_column_triple(
    ) {
        // Positive pin on the family-wide (`Atom::ESCAPE_DECODED`,
        // `Atom::NAMED_ESCAPE_TABLE`, `Atom::SELF_ESCAPE_TABLE`,
        // `take_right_column: true`) RIGHT-column triple this helper is
        // applied to at compile time via the SECOND module-level
        // `const _:` witness. Runtime pin as a second-stage safety net.
        // The two family-wide RUNTIME pins (LEFT above, RIGHT here)
        // mirror the two module-level `const _:` witnesses at ONE
        // runtime posture per column.
        assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array(
            &Atom::ESCAPE_DECODED,
            &Atom::NAMED_ESCAPE_TABLE,
            &Atom::SELF_ESCAPE_TABLE,
            true,
        );
    }

    #[test]
    #[should_panic(
        expected = "assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array"
    )]
    fn assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array_panics_at_runtime_on_head_left_column_head_position_divergence(
    ) {
        // NEGATIVE PIN — HEAD-SEGMENT LEFT-COLUMN head-position
        // (i == 0) corner: `arr[0] = 'z'` diverges from `head_table[0].0
        // = 'a'` on the FIRST head-segment position with
        // `take_right_column == false`. Pins the HEAD-LEFT-COLUMN arm
        // firing at the head.
        assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array::<3, 2, 1>(
            &['z', 'b', 'q'],
            &[('a', 'x'), ('b', 'y')],
            &['q'],
            false,
        );
    }

    #[test]
    #[should_panic(
        expected = "assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array"
    )]
    fn assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array_panics_at_runtime_on_head_left_column_tail_position_divergence(
    ) {
        // NEGATIVE PIN — HEAD-SEGMENT LEFT-COLUMN tail-position
        // (i == K-1) corner: divergence at the LAST head-segment
        // position MUST also fire. Pins the outer head-sweep bound
        // `while i < K` — a regression that walked `while i < K - 1`
        // would silently accept a tail-of-head divergence.
        assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array::<3, 2, 1>(
            &['a', 'z', 'q'],
            &[('a', 'x'), ('b', 'y')],
            &['q'],
            false,
        );
    }

    #[test]
    #[should_panic(
        expected = "assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array"
    )]
    fn assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array_panics_at_runtime_on_head_right_column_head_position_divergence(
    ) {
        // NEGATIVE PIN — HEAD-SEGMENT RIGHT-COLUMN head-position
        // (i == 0) corner: symmetric to the HEAD-LEFT-COLUMN arm at
        // the head with `take_right_column == true`. Pins the HEAD-
        // RIGHT-COLUMN arm firing at position 0.
        assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array::<3, 2, 1>(
            &['z', 'y', 'q'],
            &[('a', 'x'), ('b', 'y')],
            &['q'],
            true,
        );
    }

    #[test]
    #[should_panic(
        expected = "assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array"
    )]
    fn assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array_panics_at_runtime_on_head_right_column_tail_position_divergence(
    ) {
        // NEGATIVE PIN — HEAD-SEGMENT RIGHT-COLUMN tail-position
        // (i == K-1) corner: divergence at the LAST head-segment
        // RIGHT-column position MUST also fire. Symmetric to the
        // LEFT-column tail-position arm.
        assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array::<3, 2, 1>(
            &['x', 'z', 'q'],
            &[('a', 'x'), ('b', 'y')],
            &['q'],
            true,
        );
    }

    #[test]
    #[should_panic(
        expected = "assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array"
    )]
    fn assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array_panics_at_runtime_on_tail_head_position_divergence(
    ) {
        // NEGATIVE PIN — TAIL-SEGMENT head-position (j == 0) corner:
        // divergence at `arr[K + 0] = 'z'` vs `tail[0] = 'q'` fires
        // after the head-sweep succeeds. Pins the outer tail-sweep's
        // `while j < M` guard firing at j == 0 and correctly using
        // `K + j` for `arr` indexing. INDEPENDENT of
        // `take_right_column` — the tail is scalar-verbatim, not
        // column-projected.
        assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array::<3, 1, 2>(
            &['a', 'z', 'r'],
            &[('a', 'x')],
            &['q', 'r'],
            false,
        );
    }

    #[test]
    #[should_panic(
        expected = "assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array"
    )]
    fn assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array_panics_at_runtime_on_tail_tail_position_divergence(
    ) {
        // NEGATIVE PIN — TAIL-SEGMENT tail-position (j == M-1) corner:
        // divergence at the LAST tail-segment position MUST also fire.
        // Pins the outer tail-sweep bound `while j < M` — a regression
        // that walked `while j < M - 1` (dropping the last tail entry)
        // would silently accept a tail-of-tail divergence.
        assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array::<3, 1, 2>(
            &['a', 'q', 'z'],
            &[('a', 'x')],
            &['q', 'r'],
            false,
        );
    }

    #[test]
    #[should_panic(
        expected = "assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array"
    )]
    fn assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array_panics_at_runtime_on_cardinality_mismatch(
    ) {
        // NEGATIVE PIN — CARDINALITY-MISMATCH corner: fires BEFORE any
        // per-position sweep at the FIRST guard. `K + M == 3 + 3 == 6`
        // vs `N == 5` — the caller's turbofish is inconsistent. A
        // mistyped ARITY doesn't degenerate into a silent truncation
        // of the segment sweep.
        assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array::<5, 3, 3>(
            &['a', 'b', 'c', 'q', 'r'],
            &[('a', 'x'), ('b', 'y'), ('c', 'z')],
            &['q', 'r', 's'],
            false,
        );
    }

    #[test]
    fn assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array_panic_message_names_the_helper_and_head_left_column_divergence_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — HEAD-SEGMENT-LEFT-COLUMN-
        // DIVERGENCE arm: distinct axis vocabulary distinguishing this
        // helper's LEFT-column head-divergence from the paired-row
        // diagonal-tail sibling's `HEAD-SEGMENT-LEFT-DIVERGENCE` axis
        // (this helper's `-COLUMN-` infix distinguishes them on any
        // downstream substring search) AND from the sibling
        // `_columns_equal_char_arrays`'s `LEFT-COLUMN-DIVERGENCE`
        // axis (this helper's `HEAD-SEGMENT-` prefix distinguishes
        // them).
        let outcome = std::panic::catch_unwind(|| {
            assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array::<3, 2, 1>(
                &['z', 'b', 'q'],
                &[('a', 'x'), ('b', 'y')],
                &['q'],
                false,
            );
        });
        let payload = outcome.expect_err(
            "assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array \
             must panic on a HEAD-SEGMENT LEFT-COLUMN head-position \
             divergence",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array \
                 panic payload must be a static &str or String",
            );
        assert!(
            msg.contains("HEAD-SEGMENT-LEFT-COLUMN-DIVERGENCE"),
            "assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array \
             panic message {msg:?} must name the failed AXIS \
             (\"HEAD-SEGMENT-LEFT-COLUMN-DIVERGENCE\") for axis-\
             provenance-preserving failure diagnostics",
        );
    }

    #[test]
    fn assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array_panic_message_names_the_helper_and_head_right_column_divergence_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — HEAD-SEGMENT-RIGHT-COLUMN-
        // DIVERGENCE arm: distinct axis vocabulary at the RIGHT-column
        // dual of the LEFT-column head-divergence provenance arm.
        let outcome = std::panic::catch_unwind(|| {
            assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array::<3, 2, 1>(
                &['z', 'y', 'q'],
                &[('a', 'x'), ('b', 'y')],
                &['q'],
                true,
            );
        });
        let payload = outcome.expect_err(
            "assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array \
             must panic on a HEAD-SEGMENT RIGHT-COLUMN head-position \
             divergence",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array \
                 panic payload must be a static &str or String",
            );
        assert!(
            msg.contains("HEAD-SEGMENT-RIGHT-COLUMN-DIVERGENCE"),
            "assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array \
             panic message {msg:?} must name the failed AXIS \
             (\"HEAD-SEGMENT-RIGHT-COLUMN-DIVERGENCE\") for axis-\
             provenance-preserving failure diagnostics",
        );
    }

    #[test]
    fn assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array_panic_message_names_the_helper_and_tail_segment_divergence_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — TAIL-SEGMENT-DIVERGENCE arm:
        // distinct axis vocabulary distinguishing this helper's tail-
        // arm from the paired-row diagonal-tail sibling's `DIAGONAL-
        // TAIL-SEGMENT-{LEFT,RIGHT}-DIVERGENCE` axes (this helper's
        // tail arm omits `DIAGONAL-` and `-{LEFT,RIGHT}` — the scalar
        // tail is column-invariant).
        let outcome = std::panic::catch_unwind(|| {
            assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array::<3, 1, 2>(
                &['a', 'z', 'r'],
                &[('a', 'x')],
                &['q', 'r'],
                false,
            );
        });
        let payload = outcome.expect_err(
            "assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array \
             must panic on a TAIL-SEGMENT head-position divergence",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array \
                 panic payload must be a static &str or String",
            );
        assert!(
            msg.contains("TAIL-SEGMENT-DIVERGENCE"),
            "assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array \
             panic message {msg:?} must name the failed AXIS \
             (\"TAIL-SEGMENT-DIVERGENCE\") for axis-provenance-\
             preserving failure diagnostics",
        );
    }

    #[test]
    fn assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array_panic_message_names_the_helper_and_cardinality_mismatch_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — CARDINALITY-MISMATCH arm:
        // fires BEFORE any per-position sweep at a distinct axis
        // vocabulary. Pins the FIRST guard's provenance so a
        // diagnostic reading the axis distinguishes ARITY drift from
        // CONTENT drift.
        let outcome = std::panic::catch_unwind(|| {
            assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array::<5, 3, 3>(
                &['a', 'b', 'c', 'q', 'r'],
                &[('a', 'x'), ('b', 'y'), ('c', 'z')],
                &['q', 'r', 's'],
                false,
            );
        });
        let payload = outcome.expect_err(
            "assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array \
             must panic on a CARDINALITY-MISMATCH `K + M != N`",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array \
                 panic payload must be a static &str or String",
            );
        assert!(
            msg.contains("CARDINALITY-MISMATCH"),
            "assert_char_array_is_concatenation_of_char_pair_array_column_and_char_array \
             panic message {msg:?} must name the failed AXIS \
             (\"CARDINALITY-MISMATCH\") for axis-provenance-preserving \
             failure diagnostics",
        );
    }

    // ── `assert_char_pair_array_within_char_pair_finite_set` — the
    // `(char, char)` product-element SUBSET-EMBEDDING verifier that
    // binds `arr ⊆ set` at compile time on the paired-array vocabulary
    // via CONJOINED-pair equality, peer to the (char) + (u8) +
    // (`&'static str`) scalar rows' SUBSET-EMBEDDING helpers on the
    // (element-type × contract-shape) matrix at the (subset-embedding)
    // column. The runtime test surface pins each of the helper's arms
    // (accept-empty, accept-singleton-in-set at three positions,
    // accept-arr-equals-set, accept-family-wide-substrate-subset on
    // the pinned `NAMED_ESCAPE_TABLE ⊆ ESCAPE_TABLE` pair, accept-
    // repeated-array-entries-in-set, reject-out-of-set-pair, reject-
    // terminal-out-of-set-pair, reject-cross-row-alias, panic-message-
    // provenance on the CHAR-PAIR-SUBSET-VIOLATION axis, negative pin
    // on the DELEGATED SET-side BIJECTIVITY well-formedness arm at
    // BOTH the LEFT-column and RIGHT-column collision corners) so a
    // regression that silently weakened the helper on ANY arm is
    // caught by the helper's OWN test surface rather than only
    // surfacing as a false-positive on some future subset-embedded
    // `[(char, char); N]` array's compound pin.

    #[test]
    fn assert_char_pair_array_within_char_pair_finite_set_accepts_the_empty_array_within_any_set() {
        // Empty array `arr = []` at the `[(char, char); 0]` corner —
        // vacuously a subset of every well-formed BIJECTIVE set (no
        // `i` position exists to test). Cross-arity coverage on the
        // trivial ARRAY corner of the const-N generic across three
        // witness-set widths (empty, singleton, multi-entry) to pin
        // the helper's OUTER-sweep arm across the whole (`N == 0` ×
        // `M`) axis. Turbofish binding required because there's no
        // other cue for the const parameters on the empty array
        // literal. Sibling posture to
        // `assert_char_array_within_char_finite_set_accepts_the_empty_array_within_any_set`
        // on the (char) scalar row-dual peer — the two share the
        // trivial-arity arm across the (scalar, paired) element-type
        // partition on the (subset-embedding) column.
        assert_char_pair_array_within_char_pair_finite_set::<0, 0>(&[], &[]);
        assert_char_pair_array_within_char_pair_finite_set::<0, 1>(&[], &[('a', 'x')]);
        assert_char_pair_array_within_char_pair_finite_set::<0, 3>(
            &[],
            &[('a', 'x'), ('b', 'y'), ('c', 'z')],
        );
    }

    #[test]
    fn assert_char_pair_array_within_char_pair_finite_set_accepts_singleton_array_when_pair_in_set()
    {
        // Singleton array `arr = [P]` at the `[(char, char); 1]`
        // corner MUST pass when `P ∈ set` by CONJOINED-pair equality.
        // Cross-position coverage: the pair can sit at the FIRST,
        // MIDDLE, or LAST position of the `set` — pins the INNER
        // `while j < M` sweep terminates at the first-match position
        // rather than always at position `0` OR always at position
        // `M - 1`. A regression that narrowed the inner sweep to
        // `j == 0` would silently reject singleton arrays hitting
        // non-first set positions. Sibling posture to
        // `assert_char_array_within_char_finite_set_accepts_singleton_array_when_char_in_set`
        // on the (char) scalar row-dual peer — the two share the
        // FIRST/MIDDLE/LAST sweep-position arm across the (scalar,
        // paired) element-type partition.
        assert_char_pair_array_within_char_pair_finite_set::<1, 3>(
            &[('a', 'x')],
            &[('a', 'x'), ('b', 'y'), ('c', 'z')],
        );
        assert_char_pair_array_within_char_pair_finite_set::<1, 3>(
            &[('b', 'y')],
            &[('a', 'x'), ('b', 'y'), ('c', 'z')],
        );
        assert_char_pair_array_within_char_pair_finite_set::<1, 3>(
            &[('c', 'z')],
            &[('a', 'x'), ('b', 'y'), ('c', 'z')],
        );
    }

    #[test]
    fn assert_char_pair_array_within_char_pair_finite_set_accepts_arr_equals_set() {
        // Boundary corner where `arr` and `set` cover pair-for-pair
        // identical distinct-value sets — the SUBSET relation
        // degenerates to EQUALITY. Pins that the helper does NOT
        // gratuitously require the SUBSET to be PROPER (strict):
        // equal-multisets pass the SUBSET check. Sibling posture to
        // `assert_char_array_within_char_finite_set_accepts_arr_equals_set`
        // on the (char) scalar row-dual peer.
        assert_char_pair_array_within_char_pair_finite_set(&[('a', 'x')], &[('a', 'x')]);
        assert_char_pair_array_within_char_pair_finite_set(
            &[('a', 'x'), ('b', 'y')],
            &[('a', 'x'), ('b', 'y')],
        );
    }

    #[test]
    fn assert_char_pair_array_within_char_pair_finite_set_accepts_the_family_wide_substrate_subset()
    {
        // Runtime cross-check that the ONE (subset, superset)
        // paired-array pair the substrate's module-level `const _`
        // witness pins at COMPILE time is a proper SUBSET embedding
        // at runtime too. The pair enforces the theorem at TWO stages
        // of the toolchain: the const witness fires FIRST at `cargo
        // check` (through the module-level `const _: () =
        // assert_char_pair_array_within_char_pair_finite_set::<3, 5>(...)`
        // line), this runtime pin catches the drift at `cargo test`
        // as a safety net. Sibling posture to
        // `assert_char_pair_array_bijective_accepts_every_family_wide_substrate_array`
        // which sweeps the two family-wide `[(char, char); N]` arrays
        // at the paired-array INJECTIVITY axis; this pin sweeps the
        // ONE (subset, superset) PAIR at the paired-array SUBSET-
        // EMBEDDING axis. Together the two pins bind the (paired
        // array, paired subset-embedding) 2-corner face on the
        // `(char, char)` row of the (element-type × contract-shape)
        // matrix.
        assert_char_pair_array_within_char_pair_finite_set::<3, 5>(
            &Atom::NAMED_ESCAPE_TABLE,
            &Atom::ESCAPE_TABLE,
        );
    }

    #[test]
    fn assert_char_pair_array_within_char_pair_finite_set_accepts_repeated_array_entries_in_set() {
        // Peer corner to a (future-lift) `_covers_char_pair_finite_
        // set`: this helper permits duplicates in `arr` because
        // SUBSET-membership is a DISTINCT-value predicate — the
        // pair-multiset `[('a', 'x'), ('a', 'x'), ('b', 'y')]` is a
        // subset of the bijective set `{('a', 'x'), ('b', 'y'),
        // ('c', 'z')}` even though the array is not pairwise-
        // distinct. Pins that the helper does NOT gratuitously
        // require BIJECTIVITY on `arr` (the BIJECTIVITY axis is a
        // DIFFERENT compile-time contract bound by
        // `assert_char_pair_array_bijective`; combining both binds
        // BOTH axes). Sibling posture to
        // `assert_char_array_within_char_finite_set_accepts_repeated_array_entries_in_set`
        // on the (char) scalar row-dual peer.
        assert_char_pair_array_within_char_pair_finite_set(
            &[('a', 'x'), ('a', 'x'), ('b', 'y')],
            &[('a', 'x'), ('b', 'y'), ('c', 'z')],
        );
    }

    #[test]
    #[should_panic(expected = "CHAR-PAIR-SUBSET-VIOLATION")]
    fn assert_char_pair_array_within_char_pair_finite_set_panics_at_runtime_on_out_of_set_pair() {
        // NEGATIVE PIN — CHAR-PAIR-SUBSET-VIOLATION corner: an array
        // carrying a single pair NOT in the target set MUST panic at
        // runtime with the CHAR-PAIR-SUBSET-VIOLATION-named message.
        // Pins the helper's OWN reject arm — a regression that
        // silently returned without panicking on an out-of-set pair
        // would slip through the compile-time witness's failure mode
        // too. The offending pair `('z', 'w')` is intentionally
        // chosen OUTSIDE the target set to pin the OUT-OF-SET drift
        // mode.
        assert_char_pair_array_within_char_pair_finite_set(
            &[('a', 'x'), ('z', 'w')],
            &[('a', 'x'), ('b', 'y'), ('c', 'z')],
        );
    }

    #[test]
    #[should_panic(expected = "CHAR-PAIR-SUBSET-VIOLATION")]
    fn assert_char_pair_array_within_char_pair_finite_set_panics_at_runtime_on_terminal_out_of_set_pair(
    ) {
        // NEGATIVE PIN — terminal-position drift: an out-of-set pair
        // at the LAST array position MUST panic — pins that the
        // outer `while i < N` loop reaches `i = N - 1` (else the
        // terminal drift would slip through). A regression that
        // narrowed the outer sweep to `while i < N - 1` (off-by-one
        // on the OUTER bound) would silently accept this array.
        // Sibling posture to
        // `assert_char_array_within_char_finite_set_panics_at_runtime_on_terminal_out_of_set_entry`
        // on the (char) scalar row-dual peer — both bind the outer-
        // sweep terminal bound at the ONE array-side outer loop the
        // helper carries.
        assert_char_pair_array_within_char_pair_finite_set(
            &[('a', 'x'), ('b', 'y'), ('c', 'z'), ('z', 'w')],
            &[('a', 'x'), ('b', 'y'), ('c', 'z')],
        );
    }

    #[test]
    #[should_panic(expected = "CHAR-PAIR-SUBSET-VIOLATION")]
    fn assert_char_pair_array_within_char_pair_finite_set_panics_at_runtime_on_cross_row_alias_pair(
    ) {
        // KEY LOAD-BEARING NEGATIVE PIN — CONJOINED-pair equality
        // gate corner: a pair whose LEFT column matches ONE set
        // entry's LEFT column AND whose RIGHT column matches a
        // DIFFERENT set entry's RIGHT column but the CONJOINED pair
        // itself is NOT in the set MUST panic. This is the exact
        // property that distinguishes the CONJOINED-pair SUBSET
        // helper from a per-column-membership check: a regression
        // that silently split the CONJOINED equality gate into TWO
        // separate per-column membership sweeps (one over the LEFT
        // column, one over the RIGHT column) would accept the pair
        // `('a', 'y')` here (`'a'` appears in the set's LEFT column
        // via `('a', 'x')`, `'y'` appears in the set's RIGHT column
        // via `('b', 'y')`), but the CONJOINED pair `('a', 'y')` is
        // NOT in the set. A drift from `&&` to `||` on the CONJOINED
        // gate would silently accept this cross-row aliasing pair.
        assert_char_pair_array_within_char_pair_finite_set(
            &[('a', 'y')],
            &[('a', 'x'), ('b', 'y'), ('c', 'z')],
        );
    }

    #[test]
    fn assert_char_pair_array_within_char_pair_finite_set_panic_message_names_the_helper_and_char_pair_subset_violation_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — CHAR-PAIR-SUBSET-VIOLATION
        // arm: the panic message MUST begin with the helper's own
        // name AND identify the failed AXIS as "CHAR-PAIR-SUBSET-
        // VIOLATION" so downstream diagnostics route the drift back
        // to (a) the helper by string search on
        // `"assert_char_pair_array_within_char_pair_finite_set"` and
        // (b) the axis by string search on `"CHAR-PAIR-SUBSET-
        // VIOLATION"`. Sibling posture to
        // `assert_char_array_within_char_finite_set_panic_message_names_the_helper_and_char_subset_violation_axis`
        // on the (char) scalar row-dual peer's provenance pin — the
        // two pins together bind the (helper, failed-axis)
        // provenance pair at ONE test per SUBSET helper on the
        // (element-type × contract-shape) matrix's SUBSET column.
        // The axis-provenance string `"CHAR-PAIR-SUBSET-VIOLATION"`
        // is chosen DISTINCT from EVERY sibling helper's axis
        // vocabulary (`"CHAR-SUBSET-VIOLATION"` on the (char) scalar
        // row-dual SUBSET peer; `"SUBSET-VIOLATION"` on the (u8)
        // scalar row-dual finite-set SUBSET peer; `"STR-SUBSET-
        // VIOLATION"` on the (`&'static str`) scalar row-dual
        // SUBSET peer; `"RANGE-SUBSET-VIOLATION"` on the (u8) range
        // SUBSET peer; `"CHAR-DISJOINTNESS-VIOLATION"` / `"U8-
        // DISJOINTNESS-VIOLATION"` / `"STR-DISJOINTNESS-VIOLATION"`
        // on the DISJOINTNESS-column row peers; `"LEFT column"` /
        // `"RIGHT column"` on the paired-array BIJECTIVITY sibling)
        // so a diagnostic that names the failed axis routes
        // UNAMBIGUOUSLY to (a) this specific paired-array SUBSET-
        // embedding helper, (b) the `arr` argument as the drift
        // site rather than the `set` argument specifying the target
        // paired superset.
        let outcome = std::panic::catch_unwind(|| {
            assert_char_pair_array_within_char_pair_finite_set(
                &[('a', 'x'), ('z', 'w')],
                &[('a', 'x'), ('b', 'y'), ('c', 'z')],
            );
        });
        let payload = outcome.expect_err(
            "assert_char_pair_array_within_char_pair_finite_set must \
             panic on an out-of-set pair — the reject-out-of-set arm \
             is the sole CHAR-PAIR-SUBSET-VIOLATION failure mode of \
             the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_pair_array_within_char_pair_finite_set \
                 panic payload must be a static &str or String",
            );
        assert!(
            msg.contains("assert_char_pair_array_within_char_pair_finite_set"),
            "assert_char_pair_array_within_char_pair_finite_set \
             panic message {msg:?} must name the helper for \
             provenance-preserving failure diagnostics",
        );
        assert!(
            msg.contains("CHAR-PAIR-SUBSET-VIOLATION"),
            "assert_char_pair_array_within_char_pair_finite_set \
             panic message {msg:?} must name the failed AXIS \
             (\"CHAR-PAIR-SUBSET-VIOLATION\") for axis-provenance-\
             preserving failure diagnostics",
        );
    }

    #[test]
    #[should_panic(expected = "assert_char_pair_array_bijective")]
    fn assert_char_pair_array_within_char_pair_finite_set_panics_on_malformed_target_set_left_column_collision(
    ) {
        // NEGATIVE PIN — DELEGATED SET-side BIJECTIVITY well-
        // formedness at the LEFT-column collision corner: a
        // malformed target-set spec `[('a', 'x'), ('a', 'y')]`
        // (LEFT-column duplicate `'a'`) fed into the ARRAY-side
        // within helper MUST panic on the DELEGATED bijectivity arm
        // BEFORE the CHAR-PAIR-SUBSET-VIOLATION arm fires. Pins the
        // delegation chain: a regression that dropped the
        // `assert_char_pair_array_bijective(set)` call at the top of
        // `assert_char_pair_array_within_char_pair_finite_set` would
        // silently accept a malformed set and produce a false-
        // positive verdict on any `arr` embedded in the distinct-
        // value bijective subset. The panic message here surfaces
        // from the SIBLING helper (containing the paired-array
        // BIJECTIVITY helper's `"assert_char_pair_array_bijective"`
        // panic-name prefix rather than a bespoke `"SET-NOT-
        // BIJECTIVE"` axis string) because the paired row's
        // delegation reuses the ARRAY-side BIJECTIVITY helper
        // directly per the design choice documented on the SET-side-
        // well-formedness section of the helper's docstring. Sibling
        // posture to
        // `assert_char_array_within_char_finite_set_panics_on_malformed_target_set_spec`
        // on the (char) scalar row-dual peer's delegated-SET-well-
        // formedness pin. Peer corner to the RIGHT-column companion
        // pin below.
        assert_char_pair_array_within_char_pair_finite_set::<1, 2>(
            &[('a', 'x')],
            &[('a', 'x'), ('a', 'y')],
        );
    }

    #[test]
    #[should_panic(expected = "assert_char_pair_array_bijective")]
    fn assert_char_pair_array_within_char_pair_finite_set_panics_on_malformed_target_set_right_column_collision(
    ) {
        // NEGATIVE PIN — DELEGATED SET-side BIJECTIVITY well-
        // formedness at the RIGHT-column collision corner: a
        // malformed target-set spec `[('a', 'x'), ('b', 'x')]`
        // (RIGHT-column duplicate `'x'`) fed into the ARRAY-side
        // within helper MUST panic on the DELEGATED bijectivity arm
        // BEFORE the CHAR-PAIR-SUBSET-VIOLATION arm fires. Column-
        // symmetric sibling to the LEFT-column pin above — a
        // regression that silently narrowed the delegated
        // bijectivity sweep to only the LEFT column (dropping the
        // RIGHT-column injectivity half) would slip a RIGHT-column-
        // colliding set past the delegation while still binding a
        // LEFT-column-colliding one. The two pins together bind the
        // FULL bijectivity delegation across BOTH columns of the
        // paired-array well-formedness contract.
        assert_char_pair_array_within_char_pair_finite_set::<1, 2>(
            &[('a', 'x')],
            &[('a', 'x'), ('b', 'x')],
        );
    }

    // ── `assert_char_pair_arrays_disjoint` — the CHAR-PAIR-DISJOINTNESS-
    // VIOLATION verifier that binds `a ∩ b = ∅` at compile time on the
    // paired-array vocabulary via CONJOINED-pair equality, peer to the
    // (char) + (u8) + (`&'static str`) SCALAR rows' DISJOINTNESS helpers
    // on the (element-type × contract-shape) matrix at the (disjointness)
    // column. Contract-orthogonal peer to
    // `assert_char_pair_array_within_char_pair_finite_set` on the
    // (SUBSET-EMBEDDING, DISJOINTNESS) axis of the (contract-shape)
    // column on the SAME paired-array row. The runtime test surface
    // pins each of the helper's arms (accept-empty × 3, accept-disjoint
    // singletons, accept-family-wide-substrate-pair on the pinned
    // `NAMED_ESCAPE_TABLE` disjoint from SELF-as-pairs partition,
    // accept-per-column-alias-only corner (the CONJOINED-gate load-
    // bearing NON-INSTANCE of the stricter per-column disjointness
    // contract), reject-full-pair-collision, reject-terminal-position
    // collision, argument-order symmetry, panic-message provenance on
    // the CHAR-PAIR-DISJOINTNESS-VIOLATION axis) so a regression that
    // silently weakened the helper on ANY arm is caught by the helper's
    // OWN test surface rather than only surfacing as a false-positive on
    // some future disjoint `[(char, char); N]` paired-array pair's
    // compound pin.

    #[test]
    fn assert_char_pair_arrays_disjoint_accepts_both_empty_arrays() {
        // Empty × empty at the `[(char, char); 0] × [(char, char); 0]`
        // corner — vacuously disjoint (no `(i, j)` position pair exists
        // to test). The module-level `const _: () =
        // assert_char_pair_arrays_disjoint(&[], &[])` witness would bind
        // this at compile time; this runtime pin catches the drift a
        // second time at test-run stage as a safety net. Turbofish
        // binding required because there's no other cue for the const
        // parameters on the two empty array literals. Sibling posture
        // to `assert_char_arrays_disjoint_accepts_both_empty_arrays` on
        // the (char) SCALAR row-dual peer.
        assert_char_pair_arrays_disjoint::<0, 0>(&[], &[]);
    }

    #[test]
    fn assert_char_pair_arrays_disjoint_accepts_either_side_empty() {
        // Empty × non-empty (and non-empty × empty) at the outer-loop-
        // vacuous corners — the outer `while i < N` sweep terminates
        // immediately when `N == 0`, and the outer sweep executing with
        // a non-empty `a` against an empty `b` finds no `j` to test
        // (inner sweep vacuous). Cross-position coverage on the two
        // vacuous outer arms. Sibling posture to
        // `assert_char_arrays_disjoint_accepts_either_side_empty` on the
        // (char) SCALAR row-dual peer — the two share the vacuous-arm
        // arm across the (scalar, paired) element-type partition on the
        // (disjointness) column.
        assert_char_pair_arrays_disjoint::<0, 3>(&[], &[('a', 'x'), ('b', 'y'), ('c', 'z')]);
        assert_char_pair_arrays_disjoint::<3, 0>(&[('a', 'x'), ('b', 'y'), ('c', 'z')], &[]);
    }

    #[test]
    fn assert_char_pair_arrays_disjoint_accepts_disjoint_singletons() {
        // Singleton × singleton at the `[(char, char); 1] × [(char,
        // char); 1]` corner with the two pairs distinct across BOTH
        // columns — the minimal non-vacuous accept arm. Pins the
        // CONJOINED-pair equality gate does NOT gratuitously match when
        // BOTH columns differ. Sibling posture to
        // `assert_char_arrays_disjoint_accepts_disjoint_singletons` on
        // the (char) SCALAR row-dual peer.
        assert_char_pair_arrays_disjoint(&[('a', 'x')], &[('b', 'y')]);
    }

    #[test]
    fn assert_char_pair_arrays_disjoint_accepts_the_family_wide_substrate_pair() {
        // Runtime cross-check that the ONE (a, b) paired-array pair the
        // substrate's module-level `const _` witness pins at COMPILE
        // time is a proper DISJOINT relation at runtime too. The pair
        // enforces the theorem at TWO stages of the toolchain: the
        // const witness fires FIRST at `cargo check` (through the
        // module-level `const _: () = assert_char_pair_arrays_disjoint::
        // <3, 2>(...)` line), this runtime pin catches the drift at
        // `cargo test` as a safety net. Sibling posture to
        // `assert_char_pair_array_within_char_pair_finite_set_accepts_
        // the_family_wide_substrate_subset` which sweeps the ONE (arr,
        // set) pair at the paired-array SUBSET-EMBEDDING axis; this pin
        // sweeps the ONE (a, b) pair at the paired-array DISJOINTNESS
        // axis. Together the two pins bind the (paired subset-
        // embedding, paired disjointness) 2-corner face on the
        // `(char, char)` row of the (element-type × contract-shape)
        // matrix. The `NAMED_ESCAPE_TABLE` disjoint from SELF-as-pairs
        // partition of `ESCAPE_TABLE` is the substrate-load-bearing
        // instance: a NAMED escape source `('n' / 't' / 'r')` cannot
        // simultaneously ALSO be a SELF-escape source `STR_DELIMITER /
        // STR_ESCAPE_LEAD` — the two sub-vocabularies of
        // `Atom::decode_str_escape` MUST partition disjointly to route
        // each escape byte through EXACTLY ONE arm.
        assert_char_pair_arrays_disjoint::<3, 2>(
            &Atom::NAMED_ESCAPE_TABLE,
            &[
                (Atom::SELF_ESCAPE_TABLE[0], Atom::SELF_ESCAPE_TABLE[0]),
                (Atom::SELF_ESCAPE_TABLE[1], Atom::SELF_ESCAPE_TABLE[1]),
            ],
        );
    }

    #[test]
    fn assert_char_pair_arrays_disjoint_accepts_per_column_alias_when_conjoined_pair_differs() {
        // KEY LOAD-BEARING ACCEPT PIN — CONJOINED-pair equality gate
        // NON-INSTANCE corner: two paired arrays whose LEFT columns
        // share an entry OR whose RIGHT columns share an entry but the
        // CONJOINED pairs themselves differ MUST be accepted as
        // disjoint. This is the exact property that distinguishes the
        // CONJOINED-pair DISJOINTNESS helper from a stricter per-column
        // disjointness check: a regression that split the CONJOINED
        // equality gate into TWO separate per-column membership sweeps
        // (one over the LEFT column, one over the RIGHT column) would
        // REJECT the pair `(&[('a', 'x')], &[('a', 'y')])` here as a
        // false-positive collision (`'a'` appears in BOTH arrays' LEFT
        // columns via `('a', 'x')` and `('a', 'y')` respectively), but
        // the CONJOINED pairs `('a', 'x')` and `('a', 'y')` themselves
        // differ so the paired arrays ARE disjoint. A drift from `&&`
        // to `||` on the CONJOINED gate would silently REJECT this
        // per-column-alias corner as a false-positive collision.
        // Symmetric pin on the RIGHT-column-alias-only sibling corner
        // — the two together bind the CONJOINED-gate semantics across
        // BOTH column-alias arms. Peer to
        // `assert_char_pair_array_within_char_pair_finite_set_panics_at_
        // runtime_on_cross_row_alias_pair` on the SUBSET-EMBEDDING
        // sibling's dual corner — where the SUBSET helper REJECTS the
        // cross-row alias pair as NOT-in-set, this DISJOINTNESS helper
        // ACCEPTS the analogous per-column alias as disjoint (the two
        // contract shapes flip the accept/reject arm across the
        // CONJOINED-gate corner).
        assert_char_pair_arrays_disjoint(&[('a', 'x')], &[('a', 'y')]);
        assert_char_pair_arrays_disjoint(&[('a', 'x')], &[('b', 'x')]);
    }

    #[test]
    #[should_panic(expected = "CHAR-PAIR-DISJOINTNESS-VIOLATION")]
    fn assert_char_pair_arrays_disjoint_panics_at_runtime_on_collision() {
        // NEGATIVE PIN — CHAR-PAIR-DISJOINTNESS-VIOLATION corner: two
        // paired arrays sharing a CONJOINED pair MUST panic at runtime
        // with the CHAR-PAIR-DISJOINTNESS-VIOLATION-named message.
        // Pins the helper's OWN reject arm — a regression that
        // silently returned without panicking on a shared pair would
        // slip through the compile-time witness's failure mode too.
        // The offending pair `('b', 'y')` is intentionally chosen to
        // appear in BOTH arrays at their MIDDLE positions to pin that
        // the reject arm fires from an interior-position collision (not
        // only a first-position or last-position degenerate corner).
        assert_char_pair_arrays_disjoint(
            &[('a', 'x'), ('b', 'y'), ('c', 'z')],
            &[('p', 'q'), ('b', 'y'), ('r', 's')],
        );
    }

    #[test]
    #[should_panic(expected = "CHAR-PAIR-DISJOINTNESS-VIOLATION")]
    fn assert_char_pair_arrays_disjoint_panics_at_runtime_on_terminal_position_collision() {
        // NEGATIVE PIN — terminal-position drift: a shared CONJOINED
        // pair at the LAST position of BOTH arrays MUST panic — pins
        // that BOTH the outer `while i < N` and inner `while j < M`
        // loops reach their terminal indices (else the terminal drift
        // would slip through). A regression that narrowed EITHER
        // bound to `< N - 1` / `< M - 1` (off-by-one on the OUTER or
        // INNER bound) would silently accept this array pair. Peer
        // sibling posture to
        // `assert_char_pair_array_within_char_pair_finite_set_panics_
        // at_runtime_on_terminal_out_of_set_pair` on the SUBSET-
        // EMBEDDING helper — both bind the terminal-position sweep
        // arm on the paired-array row.
        assert_char_pair_arrays_disjoint(&[('a', 'x'), ('z', 'w')], &[('p', 'q'), ('z', 'w')]);
    }

    #[test]
    fn assert_char_pair_arrays_disjoint_is_symmetric_in_argument_order() {
        // SYMMETRY PIN — the disjointness relation is symmetric in
        // `(a, b)` so swapping arguments at the call site MUST produce
        // the SAME verdict (accept remains accept, reject remains
        // reject). Pins the two-loop sweep visits every `(i, j) ∈
        // [0, N) × [0, M)` pair without gratuitous argument-order
        // preference. Sibling posture to
        // `assert_char_arrays_disjoint_is_symmetric_in_argument_order`
        // on the (char) SCALAR row-dual peer — the two share the
        // symmetric-relation arm across the (scalar, paired) element-
        // type partition on the (disjointness) column.
        assert_char_pair_arrays_disjoint(&[('a', 'x'), ('b', 'y')], &[('c', 'z'), ('d', 'w')]);
        assert_char_pair_arrays_disjoint(&[('c', 'z'), ('d', 'w')], &[('a', 'x'), ('b', 'y')]);
        let swap_left_rejects = std::panic::catch_unwind(|| {
            assert_char_pair_arrays_disjoint(&[('a', 'x')], &[('a', 'x')]);
        })
        .is_err();
        let swap_right_rejects = std::panic::catch_unwind(|| {
            assert_char_pair_arrays_disjoint(&[('a', 'x')], &[('a', 'x')]);
        })
        .is_err();
        assert!(
            swap_left_rejects && swap_right_rejects,
            "assert_char_pair_arrays_disjoint must reject a shared \
             CONJOINED pair regardless of which argument carries the \
             `a` role vs. the `b` role — the disjointness relation \
             is symmetric in argument order",
        );
    }

    #[test]
    fn assert_char_pair_arrays_disjoint_panic_message_names_the_helper_and_char_pair_disjointness_violation_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — CHAR-PAIR-DISJOINTNESS-
        // VIOLATION arm: the panic message MUST begin with the
        // helper's own name AND identify the failed AXIS as "CHAR-
        // PAIR-DISJOINTNESS-VIOLATION" so downstream diagnostics
        // route the drift back to (a) the helper by string search on
        // `"assert_char_pair_arrays_disjoint"` and (b) the axis by
        // string search on `"CHAR-PAIR-DISJOINTNESS-VIOLATION"`.
        // Sibling posture to
        // `assert_char_arrays_disjoint_panic_message_names_the_helper_
        // and_char_disjointness_violation_axis` +
        // `assert_str_arrays_disjoint_panic_message_names_the_helper_
        // and_str_disjointness_violation_axis` +
        // `assert_u8_arrays_disjoint_panic_message_names_the_helper_
        // and_u8_disjointness_violation_axis` on the SCALAR row-dual
        // provenance pins. The axis-provenance string `"CHAR-PAIR-
        // DISJOINTNESS-VIOLATION"` is chosen DISTINCT from EVERY
        // sibling helper's axis vocabulary (`"CHAR-DISJOINTNESS-
        // VIOLATION"` on the (char) SCALAR row-dual DISJOINTNESS
        // peer; `"U8-DISJOINTNESS-VIOLATION"` on the (u8) SCALAR row-
        // dual peer; `"STR-DISJOINTNESS-VIOLATION"` on the
        // (`&'static str`) SCALAR row-dual peer; `"CHAR-PAIR-SUBSET-
        // VIOLATION"` on the paired-array SUBSET-embedding sibling;
        // `"LEFT column"` / `"RIGHT column"` on the paired-array
        // BIJECTIVITY sibling) so a diagnostic that names the failed
        // axis routes UNAMBIGUOUSLY to (a) this specific paired-array
        // DISJOINTNESS helper, (b) the failed axis-shape by the
        // `"DISJOINTNESS-VIOLATION"` suffix stem shared with the
        // three SCALAR row-dual siblings.
        let outcome = std::panic::catch_unwind(|| {
            assert_char_pair_arrays_disjoint(&[('a', 'x')], &[('a', 'x')]);
        });
        let payload = outcome.expect_err(
            "assert_char_pair_arrays_disjoint must panic on a shared \
             CONJOINED pair — the reject-on-collision arm is the sole \
             CHAR-PAIR-DISJOINTNESS-VIOLATION failure mode of the \
             helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_char_pair_arrays_disjoint panic payload must \
                 be a static &str or String",
            );
        assert!(
            msg.contains("assert_char_pair_arrays_disjoint"),
            "assert_char_pair_arrays_disjoint panic message {msg:?} \
             must name the helper for provenance-preserving failure \
             diagnostics",
        );
        assert!(
            msg.contains("CHAR-PAIR-DISJOINTNESS-VIOLATION"),
            "assert_char_pair_arrays_disjoint panic message {msg:?} \
             must name the failed AXIS (\"CHAR-PAIR-DISJOINTNESS-\
             VIOLATION\") for axis-provenance-preserving failure \
             diagnostics",
        );
    }

    // ── `assert_u8_array_covers_inclusive_range` — the SURJECTIVITY-
    // onto-a-range peer of `assert_u8_array_pairwise_distinct`'s
    // INJECTIVITY axis on the SAME `u8` cache-key element type. Where
    // the four sibling distinctness/bijectivity helpers close the
    // pairwise-DISTINCTNESS axis of the substrate's typed-array
    // vocabulary, this range-coverage helper opens the SURJECTIVITY-
    // onto-a-range axis at four family-wide `[u8; N]` arrays whose
    // distinct-value sets are intentionally-closed inclusive ranges
    // (`AtomKind::HASH_DISCRIMINATORS` covers `{0..=5}`, `QuoteForm::
    // HASH_DISCRIMINATORS` covers `{3..=6}`, `UnquoteForm::HASH_
    // DISCRIMINATORS` covers `{5..=6}`, `SexpShape::HASH_DISCRIMINATORS`
    // covers `{0..=6}` with a load-bearing six-fold collapse at `1u8`).
    // The runtime test surface matches the sibling-helpers' shape
    // (accept-singleton, accept-with-duplicates, accept-every-family-
    // wide-substrate-array, reject-above-HI, reject-below-LO, reject-
    // missing-range-byte, panic-message-provenance on the RANGE-BOUND
    // axis, panic-message-provenance on the FULL-COVERAGE axis) split
    // across BOTH axes so a regression that silently weakens the
    // helper on EITHER axis (e.g. dropping the `arr[i] < LO || arr[i]
    // > HI` guard, or dropping the `while cur <= HI` full-coverage
    // sweep) is caught by the helper's OWN test surface rather than
    // only surfacing as a false-positive on some future range-
    // covering `[u8; N]` array's coverage pin.

    #[test]
    fn assert_u8_array_covers_inclusive_range_accepts_the_singleton_range() {
        // Singleton range `{K..=K}` at the `[u8; 1]` corner —
        // vacuously covering (the one entry MUST equal the one range
        // byte). Cross-arity coverage on the trivial-range corner of
        // the const-N generic; simultaneously pins BOTH axes (RANGE-
        // BOUND: `K in [K, K]`; FULL-COVERAGE: `K` appears in the
        // singleton array) at the smallest witness.
        assert_u8_array_covers_inclusive_range::<1, 7, 7>(&[7u8]);
        assert_u8_array_covers_inclusive_range::<1, 0, 0>(&[0u8]);
        assert_u8_array_covers_inclusive_range::<1, 255, 255>(&[255u8]);
    }

    #[test]
    fn assert_u8_array_covers_inclusive_range_accepts_arrays_with_duplicates() {
        // KEY LOAD-BEARING PIN: duplicates in the entries are ACCEPTED
        // — the range-coverage contract is non-injective on the
        // ENTRIES axis, only requires each RANGE byte to appear. This
        // is the exact property that distinguishes this helper from
        // its `assert_u8_array_pairwise_distinct` sibling and lets
        // `SexpShape::HASH_DISCRIMINATORS`'s six-fold collapse at
        // `1u8` bind a compile-time coverage witness despite failing
        // distinctness. A regression that added a pairwise-distinct
        // guard on the entries axis (accidentally merging the two
        // sibling helpers' contracts) would fail-loudly here.
        assert_u8_array_covers_inclusive_range::<4, 0, 2>(&[0u8, 1u8, 1u8, 2u8]);
        assert_u8_array_covers_inclusive_range::<7, 0, 2>(&[0u8, 1u8, 1u8, 1u8, 1u8, 1u8, 2u8]);
    }

    #[test]
    fn assert_u8_array_covers_inclusive_range_accepts_every_family_wide_substrate_array() {
        // Runtime cross-check that the SAME four range-covering arrays
        // the module-level `const _: () = ...` witnesses cover at
        // COMPILE time are range-covering. 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 drift at
        // `cargo test`. The pair enforces the theorem at TWO stages of
        // the toolchain. Sibling posture to
        // `assert_char_pair_array_bijective_accepts_every_family_wide_
        // substrate_array` at the paired-array vocabulary.
        assert_u8_array_covers_inclusive_range::<12, 0, 6>(
            &crate::error::SexpShape::HASH_DISCRIMINATORS,
        );
        assert_u8_array_covers_inclusive_range::<6, 0, 5>(&AtomKind::HASH_DISCRIMINATORS);
        assert_u8_array_covers_inclusive_range::<4, 3, 6>(&QuoteForm::HASH_DISCRIMINATORS);
        assert_u8_array_covers_inclusive_range::<2, 5, 6>(
            &crate::error::UnquoteForm::HASH_DISCRIMINATORS,
        );
    }

    #[test]
    #[should_panic(expected = "OUT-OF-RANGE")]
    fn assert_u8_array_covers_inclusive_range_panics_at_runtime_on_entry_above_hi() {
        // NEGATIVE PIN — RANGE-BOUND above-HI corner: an entry
        // `HI + 1` MUST panic at runtime with the RANGE-BOUND-named
        // message. Pins the helper's OWN reject-above-HI arm — a
        // regression that silently returned without panicking on an
        // out-of-range entry above the upper bound would slip through
        // the compile-time witnesses' failure mode too.
        assert_u8_array_covers_inclusive_range::<3, 0, 2>(&[0u8, 1u8, 3u8]);
    }

    #[test]
    #[should_panic(expected = "OUT-OF-RANGE")]
    fn assert_u8_array_covers_inclusive_range_panics_at_runtime_on_entry_below_lo() {
        // NEGATIVE PIN — RANGE-BOUND below-LO corner: an entry
        // `LO - 1` MUST panic at runtime with the RANGE-BOUND-named
        // message. Symmetric sibling to the above-HI pin — a
        // regression that dropped the `arr[i] < LO` half of the
        // OR-disjunction guard (leaving only the `arr[i] > HI` half)
        // would silently accept below-LO entries.
        assert_u8_array_covers_inclusive_range::<3, 1, 3>(&[0u8, 1u8, 2u8]);
    }

    #[test]
    #[should_panic(expected = "MISSING")]
    fn assert_u8_array_covers_inclusive_range_panics_at_runtime_on_missing_range_byte() {
        // NEGATIVE PIN — FULL-COVERAGE corner: a range byte NOT
        // reached by any entry MUST panic at runtime with the FULL-
        // COVERAGE-named message. Pins the helper's OWN reject-
        // incomplete-coverage arm — a regression that silently
        // returned without panicking on an incomplete-coverage array
        // (e.g. dropping the `while cur <= HI` sweep entirely, or
        // narrowing it to `while cur < HI`) would slip through the
        // compile-time witnesses' failure mode too. The three entries
        // stay within `[0, 3]` (satisfying RANGE-BOUND) but skip the
        // middle byte `2u8` — the panic MUST fire specifically on
        // the FULL-COVERAGE axis, not on the RANGE-BOUND axis.
        assert_u8_array_covers_inclusive_range::<3, 0, 3>(&[0u8, 1u8, 3u8]);
    }

    #[test]
    fn assert_u8_array_covers_inclusive_range_panic_message_names_the_helper_and_range_bound_axis()
    {
        // PANIC-MESSAGE PROVENANCE PIN — RANGE-BOUND arm: the panic
        // message MUST begin with the helper's own name AND identify
        // the failed AXIS as "OUT-OF-RANGE" so downstream diagnostics
        // route the drift back to (a) the helper by string search on
        // `"assert_u8_array_covers_inclusive_range"` and (b) the axis
        // by string search on `"OUT-OF-RANGE"`. Sibling posture to
        // `assert_char_pair_array_bijective_panic_message_names_the_
        // helper_and_left_column` on the paired-array bijectivity
        // helper's LEFT-column arm — both bind the (helper, failed-
        // axis) provenance pair at ONE test per axis.
        let outcome = std::panic::catch_unwind(|| {
            assert_u8_array_covers_inclusive_range::<3, 0, 2>(&[0u8, 1u8, 3u8]);
        });
        let payload = outcome.expect_err(
            "assert_u8_array_covers_inclusive_range must panic on an \
             out-of-range entry — the reject-out-of-range arm is one \
             of the two failure modes of the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_u8_array_covers_inclusive_range panic payload \
                 must be a static &str or String",
            );
        assert!(
            msg.contains("assert_u8_array_covers_inclusive_range"),
            "assert_u8_array_covers_inclusive_range RANGE-BOUND panic \
             message {msg:?} must name the helper for provenance-\
             preserving failure diagnostics",
        );
        assert!(
            msg.contains("OUT-OF-RANGE"),
            "assert_u8_array_covers_inclusive_range RANGE-BOUND panic \
             message {msg:?} must name the failed AXIS (\"OUT-OF-\
             RANGE\") for axis-provenance-preserving failure \
             diagnostics",
        );
    }

    #[test]
    fn assert_u8_array_covers_inclusive_range_panic_message_names_the_helper_and_full_coverage_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — FULL-COVERAGE arm: the panic
        // message MUST begin with the helper's own name AND identify
        // the failed AXIS as "MISSING" so downstream diagnostics route
        // the drift back to (a) the helper by string search and (b)
        // the axis by string search on `"MISSING"`. Axis-symmetric
        // sibling of the RANGE-BOUND panic-message provenance pin
        // above — a regression that silently unified the two panic
        // sites into ONE axis-anonymous message would collapse EITHER
        // this pin's `"MISSING"` substring assertion OR the sibling
        // pin's `"OUT-OF-RANGE"` substring assertion.
        let outcome = std::panic::catch_unwind(|| {
            assert_u8_array_covers_inclusive_range::<3, 0, 3>(&[0u8, 1u8, 3u8]);
        });
        let payload = outcome.expect_err(
            "assert_u8_array_covers_inclusive_range must panic on a \
             missing range byte — the reject-incomplete-coverage arm \
             is one of the two failure modes of the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_u8_array_covers_inclusive_range panic payload \
                 must be a static &str or String",
            );
        assert!(
            msg.contains("assert_u8_array_covers_inclusive_range"),
            "assert_u8_array_covers_inclusive_range FULL-COVERAGE panic \
             message {msg:?} must name the helper for provenance-\
             preserving failure diagnostics",
        );
        assert!(
            msg.contains("MISSING"),
            "assert_u8_array_covers_inclusive_range FULL-COVERAGE panic \
             message {msg:?} must name the failed AXIS (\"MISSING\") \
             for axis-provenance-preserving failure diagnostics",
        );
    }

    // ── `assert_u8_array_covers_finite_set` — the non-contiguous-
    // finite-set peer of `assert_u8_array_covers_inclusive_range` on
    // the (contiguity) axis of the substrate's SURJECTIVITY-axis
    // coverage helpers. Where the sibling range-coverage helper closes
    // the contiguous corner of the target-partition axis at four
    // range-covering `[u8; N]` HASH_DISCRIMINATORS arrays, this helper
    // closes the non-contiguous corner at
    // `StructuralKind::HASH_DISCRIMINATORS` (`[u8; 2]` covering
    // `{0, 2}` with a load-bearing gap at `1u8` where the atomic-
    // carve outer marker lives). The runtime test surface matches
    // the sibling-helpers' shape (accept-singleton, accept-with-
    // duplicates, accept-every-family-wide-substrate-array, reject-
    // out-of-set, reject-set-byte-missing, panic-message-provenance
    // on the OUT-OF-SET axis, panic-message-provenance on the SET-
    // BYTE-MISSING axis) split across BOTH axes so a regression that
    // silently weakens the helper on EITHER axis (e.g. dropping the
    // `found` guard on the set-membership sweep, or dropping the
    // outer `while j < M` set-coverage sweep entirely) is caught by
    // the helper's OWN test surface rather than only surfacing as a
    // false-positive on some future finite-set-covering `[u8; N]`
    // array's coverage pin.

    #[test]
    fn assert_u8_array_covers_finite_set_accepts_the_singleton_set() {
        // Singleton set `{K}` at the `[u8; 1]` × `[u8; 1]` corner —
        // vacuously covering (the one entry MUST equal the one set
        // byte). Cross-arity coverage on the trivial-set corner of
        // the const-M generic; simultaneously pins BOTH axes (OUT-OF-
        // SET: `K in {K}`; SET-BYTE-MISSING: `K` appears in the
        // singleton array) at the smallest witness.
        assert_u8_array_covers_finite_set::<1, 1>(&[7u8], &[7u8]);
        assert_u8_array_covers_finite_set::<1, 1>(&[0u8], &[0u8]);
        assert_u8_array_covers_finite_set::<1, 1>(&[255u8], &[255u8]);
    }

    #[test]
    fn assert_u8_array_covers_finite_set_accepts_arrays_with_duplicates() {
        // KEY LOAD-BEARING PIN: duplicates in the entries are ACCEPTED
        // — the finite-set-coverage contract is non-injective on the
        // ENTRIES axis, only requires each SET byte to appear. This
        // is the exact property that distinguishes this helper from
        // its `assert_u8_array_pairwise_distinct` sibling and lets
        // any future array with a load-bearing collapse bind a
        // compile-time coverage witness despite failing distinctness.
        // A regression that added a pairwise-distinct guard on the
        // entries axis (accidentally merging the two sibling
        // helpers' contracts) would fail-loudly here.
        assert_u8_array_covers_finite_set::<4, 3>(&[0u8, 1u8, 1u8, 2u8], &[0u8, 1u8, 2u8]);
        assert_u8_array_covers_finite_set::<7, 3>(
            &[0u8, 1u8, 1u8, 1u8, 1u8, 1u8, 2u8],
            &[0u8, 1u8, 2u8],
        );
    }

    #[test]
    fn assert_u8_array_covers_finite_set_accepts_the_non_contiguous_partition() {
        // KEY LOAD-BEARING PIN: a non-contiguous target set `{0, 2}`
        // (with a gap at `1u8`) is ACCEPTED — a two-element array
        // hitting exactly those two bytes binds the finite-set-
        // coverage contract even though NO contiguous `[LO..=HI]`
        // range describes the target partition. This is the exact
        // property that distinguishes this helper from its
        // `assert_u8_array_covers_inclusive_range` sibling on the
        // (contiguity) axis and lets
        // `StructuralKind::HASH_DISCRIMINATORS`'s `{0, 2}` gap-
        // partition bind a compile-time coverage witness where the
        // range sibling cannot. A regression that narrowed the
        // helper's target-set semantics to contiguous ranges only
        // (e.g. re-derived the `while cur <= HI` sweep instead of
        // the per-set-byte membership sweep) would fail-loudly here.
        assert_u8_array_covers_finite_set::<2, 2>(&[0u8, 2u8], &[0u8, 2u8]);
        assert_u8_array_covers_finite_set::<3, 3>(&[0u8, 2u8, 5u8], &[0u8, 2u8, 5u8]);
    }

    #[test]
    fn assert_u8_array_covers_finite_set_accepts_every_family_wide_substrate_array() {
        // Runtime cross-check that the SAME array the module-level
        // `const _: () = ...` witness covers at COMPILE time is
        // finite-set-covering. A regression that removes the
        // `const _` witness would still leave THIS runtime pin as a
        // safety net; the const witness fires FIRST at `cargo check`,
        // this runtime pin catches the drift at `cargo test`. The
        // pair enforces the theorem at TWO stages of the toolchain.
        // Sibling posture to
        // `assert_u8_array_covers_inclusive_range_accepts_every_
        // family_wide_substrate_array` at the contiguous-range peer.
        assert_u8_array_covers_finite_set::<2, 2>(
            &crate::error::StructuralKind::HASH_DISCRIMINATORS,
            &[0u8, 2u8],
        );
    }

    #[test]
    #[should_panic(expected = "OUT-OF-SET")]
    fn assert_u8_array_covers_finite_set_panics_at_runtime_on_out_of_set_entry() {
        // NEGATIVE PIN — SET-MEMBERSHIP corner: an entry NOT in the
        // target set MUST panic at runtime with the OUT-OF-SET-named
        // message. Pins the helper's OWN reject-out-of-set arm — a
        // regression that silently returned without panicking on an
        // entry outside the target set would slip through the
        // compile-time witnesses' failure mode too. The two set
        // bytes `{0, 2}` witness that the FULL-COVERAGE axis is
        // INTACT — the panic MUST fire specifically on the SET-
        // MEMBERSHIP disjointness failure at the drift entry `3u8`.
        assert_u8_array_covers_finite_set::<3, 2>(&[0u8, 2u8, 3u8], &[0u8, 2u8]);
    }

    #[test]
    #[should_panic(expected = "OUT-OF-SET")]
    fn assert_u8_array_covers_finite_set_panics_on_gap_byte_drift() {
        // NEGATIVE PIN — GAP-BYTE corner: an entry that drifts INTO
        // the intentional gap of a non-contiguous target set MUST
        // panic — this is the exact regression the archetype
        // `StructuralKind::HASH_DISCRIMINATORS` witness catches. A
        // regression that lifted a fresh `1u8` entry into the
        // `{0, 2}`-partitioned array would silently collide with
        // `AtomKind::OUTER_HASH_DISCRIMINATOR = 1u8` on the outer-
        // `Sexp` cache-key partition; this pin binds that failure
        // mode as an OUT-OF-SET rejection at the const-eval site.
        assert_u8_array_covers_finite_set::<3, 2>(&[0u8, 1u8, 2u8], &[0u8, 2u8]);
    }

    #[test]
    #[should_panic(expected = "SET-BYTE-MISSING")]
    fn assert_u8_array_covers_finite_set_panics_at_runtime_on_missing_set_byte() {
        // NEGATIVE PIN — FULL-COVERAGE corner: a set byte NOT
        // reached by any entry MUST panic at runtime with the SET-
        // BYTE-MISSING-named message. Pins the helper's OWN reject-
        // incomplete-coverage arm — a regression that silently
        // returned without panicking on an incomplete-coverage array
        // (e.g. dropping the outer `while j < M` sweep entirely, or
        // narrowing it to `while j < M - 1`) would slip through the
        // compile-time witnesses' failure mode too. The two entries
        // stay within `{0, 2, 5}` (satisfying OUT-OF-SET) but skip
        // the middle byte `2u8` — the panic MUST fire specifically
        // on the FULL-COVERAGE axis, not on the SET-MEMBERSHIP axis.
        assert_u8_array_covers_finite_set::<2, 3>(&[0u8, 5u8], &[0u8, 2u8, 5u8]);
    }

    #[test]
    fn assert_u8_array_covers_finite_set_panic_message_names_the_helper_and_out_of_set_axis() {
        // PANIC-MESSAGE PROVENANCE PIN — OUT-OF-SET arm: the panic
        // message MUST begin with the helper's own name AND identify
        // the failed AXIS as "OUT-OF-SET" so downstream diagnostics
        // route the drift back to (a) the helper by string search on
        // `"assert_u8_array_covers_finite_set"` and (b) the axis by
        // string search on `"OUT-OF-SET"`. Sibling posture to
        // `assert_u8_array_covers_inclusive_range_panic_message_
        // names_the_helper_and_range_bound_axis` on the contiguous-
        // range peer's RANGE-BOUND arm — both bind the (helper,
        // failed-axis) provenance pair at ONE test per axis. The
        // axis-provenance strings ("OUT-OF-SET" here vs. "OUT-OF-
        // RANGE" on the range sibling) are chosen DISTINCT so a
        // diagnostic that names the failed axis routes UNAMBIGUOUSLY
        // to the failed HELPER too — a regression that unified the
        // two helpers' axis-provenance strings would collapse either
        // this substring assertion or the sibling helper's.
        let outcome = std::panic::catch_unwind(|| {
            assert_u8_array_covers_finite_set::<3, 2>(&[0u8, 2u8, 3u8], &[0u8, 2u8]);
        });
        let payload = outcome.expect_err(
            "assert_u8_array_covers_finite_set must panic on an out-\
             of-set entry — the reject-out-of-set arm is one of the \
             two failure modes of the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_u8_array_covers_finite_set panic payload must \
                 be a static &str or String",
            );
        assert!(
            msg.contains("assert_u8_array_covers_finite_set"),
            "assert_u8_array_covers_finite_set OUT-OF-SET panic \
             message {msg:?} must name the helper for provenance-\
             preserving failure diagnostics",
        );
        assert!(
            msg.contains("OUT-OF-SET"),
            "assert_u8_array_covers_finite_set OUT-OF-SET panic \
             message {msg:?} must name the failed AXIS (\"OUT-OF-\
             SET\") for axis-provenance-preserving failure \
             diagnostics",
        );
    }

    #[test]
    fn assert_u8_array_covers_finite_set_panic_message_names_the_helper_and_missing_set_byte_axis()
    {
        // PANIC-MESSAGE PROVENANCE PIN — SET-BYTE-MISSING arm: the
        // panic message MUST begin with the helper's own name AND
        // identify the failed AXIS as "SET-BYTE-MISSING" so
        // downstream diagnostics route the drift back to (a) the
        // helper by string search and (b) the axis by string search
        // on `"SET-BYTE-MISSING"`. Axis-symmetric sibling of the
        // OUT-OF-SET panic-message provenance pin above — a
        // regression that silently unified the two panic sites into
        // ONE axis-anonymous message would collapse EITHER this
        // pin's `"SET-BYTE-MISSING"` substring assertion OR the
        // sibling pin's `"OUT-OF-SET"` substring assertion. The
        // axis-provenance string ("SET-BYTE-MISSING" here vs.
        // "MISSING" on the range sibling) is chosen DISTINCT so a
        // diagnostic that names the failed axis routes UNAMBIGUOUSLY
        // to the failed HELPER too.
        let outcome = std::panic::catch_unwind(|| {
            assert_u8_array_covers_finite_set::<2, 3>(&[0u8, 5u8], &[0u8, 2u8, 5u8]);
        });
        let payload = outcome.expect_err(
            "assert_u8_array_covers_finite_set must panic on a \
             missing set byte — the reject-incomplete-coverage arm \
             is one of the two failure modes of the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_u8_array_covers_finite_set panic payload must \
                 be a static &str or String",
            );
        assert!(
            msg.contains("assert_u8_array_covers_finite_set"),
            "assert_u8_array_covers_finite_set SET-BYTE-MISSING panic \
             message {msg:?} must name the helper for provenance-\
             preserving failure diagnostics",
        );
        assert!(
            msg.contains("SET-BYTE-MISSING"),
            "assert_u8_array_covers_finite_set SET-BYTE-MISSING panic \
             message {msg:?} must name the failed AXIS (\"SET-BYTE-\
             MISSING\") for axis-provenance-preserving failure \
             diagnostics",
        );
    }

    // ── `assert_u8_finite_set_pairwise_distinct` — the caller-side
    // SET-WELL-FORMEDNESS verifier that closes the pre-lift docstring-
    // level "assuming `set` is itself pairwise-distinct" caveat on
    // both `assert_u8_array_covers_finite_set` and
    // `assert_u8_array_permutes_finite_set` into a compile-time
    // theorem the substrate carries per call site. The runtime test
    // surface pins each of the helper's arms (accept-empty, accept-
    // singleton, accept-every-family-wide-substrate-target-set,
    // reject-binary-collision, reject-non-adjacent-collision, reject-
    // terminal-collision, panic-message-provenance on the SET-NOT-
    // PAIRWISE-DISTINCT axis, negative pins on BOTH downstream
    // covers/permutes helpers exercising the SET-side delegation
    // chain) so a regression that silently weakened the helper on
    // ANY arm is caught by the helper's OWN test surface rather than
    // only surfacing as a false-positive on some future finite-set-
    // covering `[u8; N]` array's compound pin.

    #[test]
    fn assert_u8_finite_set_pairwise_distinct_accepts_the_empty_set() {
        // Empty set `{}` at the `[u8; 0]` corner — vacuously pairwise-
        // distinct (no `(i, j)` pair with `i < j` exists to test).
        // Cross-arity coverage on the trivial corner of the const-M
        // generic; a regression that fired on an empty set (e.g. by
        // computing `M - 1` and wrapping to `usize::MAX`) would
        // fail-loudly here. Turbofish binding required because there's
        // no other cue for the `M` const parameter on the empty array
        // literal.
        assert_u8_finite_set_pairwise_distinct::<0>(&[]);
    }

    #[test]
    fn assert_u8_finite_set_pairwise_distinct_accepts_singleton_sets() {
        // Singleton set `{K}` at the `[u8; 1]` corner — vacuously
        // pairwise-distinct (no `(i, j)` pair with `i < j` exists).
        // Cross-value coverage on the singleton corner at THREE byte
        // widths (`0u8`, `7u8`, `255u8`) to pin the helper's SINGLETON
        // arm across the whole `u8` domain.
        assert_u8_finite_set_pairwise_distinct(&[0u8]);
        assert_u8_finite_set_pairwise_distinct(&[7u8]);
        assert_u8_finite_set_pairwise_distinct(&[255u8]);
    }

    #[test]
    fn assert_u8_finite_set_pairwise_distinct_accepts_every_family_wide_target_set() {
        // Runtime cross-check that the ONE target-SET spec the
        // substrate's `const _` witness (at
        // `assert_u8_array_permutes_finite_set::<2, 2>(
        // &StructuralKind::HASH_DISCRIMINATORS, &[0u8, 2u8])`)
        // passes through this helper's SET-side delegation at
        // compile time is ALSO well-formed at runtime. The pair
        // enforces the theorem at TWO stages of the toolchain: the
        // const witness fires FIRST at `cargo check` (through the
        // delegated call chain), this runtime pin catches the drift
        // at `cargo test` as a safety net. Sibling posture to
        // `assert_u8_array_covers_finite_set_accepts_every_family_
        // wide_substrate_array` — the two pins together verify the
        // (ARRAY, SET) pair at BOTH sides of the finite-set-coverage
        // compound contract.
        assert_u8_finite_set_pairwise_distinct(&[0u8, 2u8]);
    }

    #[test]
    fn assert_u8_finite_set_pairwise_distinct_accepts_the_structural_kind_hash_discriminators() {
        // Runtime cross-check that
        // `StructuralKind::HASH_DISCRIMINATORS` itself is pairwise-
        // distinct WHEN VIEWED AS A TARGET-SET SPEC (i.e. this
        // helper accepts arrays that would themselves be valid
        // target-set specs). While the SUBSTRATE'S primary call
        // site passes the caller-provided `&[0u8, 2u8]` literal as
        // the target-set spec (with `StructuralKind::HASH_
        // DISCRIMINATORS` as the ARRAY under verification), the two
        // arrays HAPPEN to have byte-equal contents by design (the
        // ARRAY is a permutation of the target SET); a regression
        // that silently unified two `StructuralKind` arms' cache-
        // key bytes would fail-loudly here on the ARRAY-as-SET
        // interpretation TOO, providing a redundant safety net past
        // the primary compound witness at the module level.
        assert_u8_finite_set_pairwise_distinct(&crate::error::StructuralKind::HASH_DISCRIMINATORS);
    }

    #[test]
    #[should_panic(expected = "SET-NOT-PAIRWISE-DISTINCT")]
    fn assert_u8_finite_set_pairwise_distinct_panics_at_runtime_on_binary_collision() {
        // NEGATIVE PIN — binary-collision corner: the smallest
        // duplicate-carrying set `[K, K]` MUST panic at runtime with
        // the SET-NOT-PAIRWISE-DISTINCT-named message. Pins the
        // helper's OWN reject arm — a regression that silently
        // returned without panicking on an adjacent duplicate would
        // slip through the compile-time witnesses' failure mode too.
        assert_u8_finite_set_pairwise_distinct(&[42u8, 42u8]);
    }

    #[test]
    #[should_panic(expected = "SET-NOT-PAIRWISE-DISTINCT")]
    fn assert_u8_finite_set_pairwise_distinct_panics_at_runtime_on_non_adjacent_collision() {
        // NEGATIVE PIN — non-adjacent-collision corner: a duplicate
        // separated by ONE intervening element MUST panic — pins
        // that the `(i, j)` pair-walk sweeps the FULL upper-triangle
        // rather than only adjacent pairs. A regression that
        // narrowed the inner `while j < M` loop to `j == i + 1`
        // would silently accept this set. Positions `(0, 2)` witness
        // a non-adjacent collision through the middle `2u8`
        // separator.
        assert_u8_finite_set_pairwise_distinct(&[1u8, 2u8, 1u8]);
    }

    #[test]
    #[should_panic(expected = "SET-NOT-PAIRWISE-DISTINCT")]
    fn assert_u8_finite_set_pairwise_distinct_panics_at_runtime_on_terminal_collision() {
        // NEGATIVE PIN — terminal-collision corner: a duplicate at
        // the LAST two positions MUST panic — pins that the outer
        // `while i < M` loop reaches `i = M - 2` (else the terminal
        // duplicate at positions `(M - 2, M - 1)` would slip
        // through). A regression that narrowed the outer sweep to
        // `while i < M - 1` (off-by-one on the OUTER bound) would
        // silently accept this set.
        assert_u8_finite_set_pairwise_distinct(&[0u8, 1u8, 2u8, 3u8, 3u8]);
    }

    #[test]
    fn assert_u8_finite_set_pairwise_distinct_panic_message_names_the_helper_and_set_axis() {
        // PANIC-MESSAGE PROVENANCE PIN — SET-NOT-PAIRWISE-DISTINCT
        // arm: the panic message MUST begin with the helper's own
        // name AND identify the failed AXIS as "SET-NOT-PAIRWISE-
        // DISTINCT" so downstream diagnostics route the drift back
        // to (a) the helper by string search on `"assert_u8_finite_
        // set_pairwise_distinct"` and (b) the axis by string search
        // on `"SET-NOT-PAIRWISE-DISTINCT"`. Sibling posture to
        // `assert_u8_array_covers_finite_set_panic_message_names_
        // the_helper_and_out_of_set_axis` on the ARRAY-side covers
        // helper's OUT-OF-SET arm — both bind the (helper, failed-
        // axis) provenance pair at ONE test per axis. The axis-
        // provenance string "SET-NOT-PAIRWISE-DISTINCT" is chosen
        // DISTINCT from EVERY sibling helper's axis vocabulary
        // (`"duplicate"` on the ARRAY-side pairwise-distinct
        // sibling; `"OUT-OF-SET"` / `"SET-BYTE-MISSING"` on the
        // covers-finite-set sibling; `"OUT-OF-RANGE"` / `"MISSING"`
        // on the covers-inclusive-range sibling; `"ARITY-MISMATCH"`
        // on both `_permutes_*` compound helpers) so a diagnostic
        // that names the failed axis routes UNAMBIGUOUSLY to (a)
        // this specific SET-side helper, (b) the CALLER'S TARGET-
        // SET SPEC as the drift site rather than the downstream
        // `arr` under verification.
        let outcome = std::panic::catch_unwind(|| {
            assert_u8_finite_set_pairwise_distinct(&[42u8, 42u8]);
        });
        let payload = outcome.expect_err(
            "assert_u8_finite_set_pairwise_distinct must panic on a \
             malformed target-set spec — the reject-duplicate arm \
             is the sole failure mode of the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_u8_finite_set_pairwise_distinct panic payload \
                 must be a static &str or String",
            );
        assert!(
            msg.contains("assert_u8_finite_set_pairwise_distinct"),
            "assert_u8_finite_set_pairwise_distinct panic message \
             {msg:?} must name the helper for provenance-preserving \
             failure diagnostics",
        );
        assert!(
            msg.contains("SET-NOT-PAIRWISE-DISTINCT"),
            "assert_u8_finite_set_pairwise_distinct panic message \
             {msg:?} must name the failed AXIS (\"SET-NOT-PAIRWISE-\
             DISTINCT\") for axis-provenance-preserving failure \
             diagnostics",
        );
    }

    #[test]
    #[should_panic(expected = "SET-NOT-PAIRWISE-DISTINCT")]
    fn assert_u8_array_covers_finite_set_panics_on_malformed_target_set_spec() {
        // NEGATIVE PIN — DELEGATED SET-side well-formedness: a
        // malformed target-set spec `[0, 2, 2]` fed into the
        // ARRAY-side covers-finite-set helper MUST panic on the
        // DELEGATED SET-NOT-PAIRWISE-DISTINCT arm BEFORE the OUT-
        // OF-SET / SET-BYTE-MISSING arms fire. Pins the
        // delegation chain: a regression that dropped the
        // `assert_u8_finite_set_pairwise_distinct(set)` call at
        // the top of `assert_u8_array_covers_finite_set` would
        // silently accept a malformed set and produce a false-
        // positive verdict on any `arr` covering the DISTINCT-
        // value subset (`arr = [0, 2, 2]` here matches BOTH the
        // OUT-OF-SET and SET-BYTE-MISSING sweeps because every
        // entry appears in `set` and every set byte appears in
        // `arr`, so without the SET-well-formedness delegation
        // the intended cardinality-3 contract would silently
        // verify against a really-cardinality-2 set). The
        // `SET-NOT-PAIRWISE-DISTINCT` axis-provenance string
        // routes the operator to the CALLER'S SPEC.
        assert_u8_array_covers_finite_set::<3, 3>(&[0u8, 2u8, 2u8], &[0u8, 2u8, 2u8]);
    }

    #[test]
    #[should_panic(expected = "SET-NOT-PAIRWISE-DISTINCT")]
    fn assert_u8_array_permutes_finite_set_panics_on_malformed_target_set_spec() {
        // NEGATIVE PIN — DELEGATED SET-side well-formedness on
        // the COMPOUND helper: a malformed target-set spec `[0, 2,
        // 2]` fed into `assert_u8_array_permutes_finite_set` MUST
        // panic on the DELEGATED SET-NOT-PAIRWISE-DISTINCT arm
        // BEFORE the ARITY-MISMATCH / pairwise-distinct-on-arr /
        // covers-finite-set arms fire. Pins the delegation chain at
        // the compound helper's ENTRY point: a regression that
        // dropped the `assert_u8_finite_set_pairwise_distinct(set)`
        // call at the top of the compound helper would silently
        // route a malformed set through the ARITY check (`N == M`
        // holds on the substrate's cardinality-3 pair, since BOTH
        // the array and the phantom-3 set have cardinality `3` at
        // the type level even though the SET really has DISTINCT-
        // cardinality `2`) and produce a false-positive permutation
        // verdict. The `SET-NOT-PAIRWISE-DISTINCT` panic here MUST
        // fire BEFORE the sibling `ARITY-MISMATCH` panic on the
        // same input (both arms would fire independently but
        // ordering routes the operator to the CALLER'S SPEC first,
        // not to a downstream arithmetic symptom).
        assert_u8_array_permutes_finite_set::<3, 3>(&[0u8, 2u8, 5u8], &[0u8, 2u8, 2u8]);
    }

    // ── `assert_u8_array_within_u8_finite_set` — the SET-MEMBERSHIP-
    // ONLY subset-embedding verifier that binds `arr ⊆ set` at compile
    // time (WITHOUT the additional `set ⊆ arr's entries` full-coverage
    // clause the sibling `_covers_finite_set` binds). The runtime test
    // surface pins each of the helper's arms (accept-empty, accept-
    // singleton-in-set, accept-arr-equals-set, accept-the-family-wide
    // substitution-subset substrate embedding, reject-single-out-of-
    // set-entry, reject-terminal-out-of-set-entry, panic-message-
    // provenance on the SUBSET-VIOLATION axis, negative pin on the
    // DELEGATED SET-side well-formedness arm) so a regression that
    // silently weakened the helper on ANY arm is caught by the
    // helper's OWN test surface rather than only surfacing as a
    // false-positive on some future subset-embedded `[u8; N]` array's
    // compound pin.

    #[test]
    fn assert_u8_array_within_u8_finite_set_accepts_the_empty_array_within_any_set() {
        // Empty array `arr = []` at the `[u8; 0]` corner — vacuously
        // a subset of every set (no `i` position exists to test). Cross-
        // arity coverage on the trivial ARRAY corner of the const-N
        // generic across three witness-set widths (empty, singleton,
        // multi-element) to pin the helper's OUTER-sweep arm across
        // the whole (`N == 0` × `M`) axis. Turbofish binding required
        // because there's no other cue for the const parameters on
        // the empty array literal.
        assert_u8_array_within_u8_finite_set::<0, 0>(&[], &[]);
        assert_u8_array_within_u8_finite_set::<0, 1>(&[], &[42u8]);
        assert_u8_array_within_u8_finite_set::<0, 4>(&[], &[3u8, 4u8, 5u8, 6u8]);
    }

    #[test]
    fn assert_u8_array_within_u8_finite_set_accepts_singleton_array_when_byte_in_set() {
        // Singleton array `arr = [K]` at the `[u8; 1]` corner MUST
        // pass when `K ∈ set`. Cross-position coverage: the byte can
        // sit at the FIRST, MIDDLE, or LAST position of the `set` —
        // pins the INNER `while j < M` sweep terminates at the
        // first-match position rather than always at position `0`
        // OR always at position `M - 1`. A regression that narrowed
        // the inner sweep to `j == 0` would silently reject singleton
        // arrays hitting non-first set positions.
        assert_u8_array_within_u8_finite_set::<1, 4>(&[3u8], &[3u8, 4u8, 5u8, 6u8]);
        assert_u8_array_within_u8_finite_set::<1, 4>(&[5u8], &[3u8, 4u8, 5u8, 6u8]);
        assert_u8_array_within_u8_finite_set::<1, 4>(&[6u8], &[3u8, 4u8, 5u8, 6u8]);
    }

    #[test]
    fn assert_u8_array_within_u8_finite_set_accepts_arr_equals_set() {
        // Boundary corner where `arr` and `set` cover byte-for-byte
        // identical distinct-value sets — the SUBSET relation degenerates
        // to EQUALITY. Pins that the helper does NOT gratuitously
        // require the SUBSET to be PROPER (strict): equal-multisets
        // pass the SUBSET check. Sibling posture to the covers-finite-
        // set peer whose SET-BYTE-MISSING arm would ALSO accept this
        // input — the two helpers agree on the EQUAL-SETS corner
        // while disagreeing on the PROPER-SUBSET corner (only this
        // helper accepts proper subsets; the covers helper rejects
        // them at the SET-BYTE-MISSING arm).
        assert_u8_array_within_u8_finite_set(&[3u8, 4u8, 5u8, 6u8], &[3u8, 4u8, 5u8, 6u8]);
        assert_u8_array_within_u8_finite_set(&[0u8, 2u8], &[0u8, 2u8]);
    }

    #[test]
    fn assert_u8_array_within_u8_finite_set_accepts_the_substitution_subset_embedding() {
        // Runtime cross-check that the ONE (subset, superset) pair
        // the substrate's module-level `const _` witness pins at
        // COMPILE time is a PROPER SUBSET embedding at runtime too.
        // The pair enforces the theorem at TWO stages of the
        // toolchain: the const witness fires FIRST at `cargo check`
        // (through the module-level `const _: () = assert_u8_array_
        // within_u8_finite_set::<2, 4>(...)` line), this runtime pin
        // catches the drift at `cargo test` as a safety net. Sibling
        // posture to
        // `assert_u8_finite_set_pairwise_distinct_accepts_every_family_wide_target_set`
        // (which runtime-checks the SAME `QuoteForm::HASH_DISCRIMINATORS`
        // superset viewed as a SET-side well-formedness input) — the
        // two pins together verify the (UnquoteForm subset, QuoteForm
        // superset) pair at BOTH sides of the subset-embedding
        // contract.
        assert_u8_array_within_u8_finite_set::<2, 4>(
            &crate::error::UnquoteForm::HASH_DISCRIMINATORS,
            &QuoteForm::HASH_DISCRIMINATORS,
        );
    }

    #[test]
    fn assert_u8_array_within_u8_finite_set_accepts_repeated_array_entries_in_set() {
        // Peer corner to `_covers_finite_set`: this helper permits
        // duplicates in `arr` because SUBSET-membership is a
        // DISTINCT-value predicate — `[3, 3, 5]` is a subset of
        // `{3, 4, 5, 6}` even though the array is not pairwise-
        // distinct. Pins that the helper does NOT gratuitously
        // require INJECTIVITY on `arr` (the injectivity axis is a
        // DIFFERENT compile-time contract bound by
        // `assert_u8_array_pairwise_distinct`; combining both binds
        // BOTH axes). Sibling posture to
        // `assert_u8_array_covers_inclusive_range` which ALSO
        // permits array duplicates on its RANGE-BOUND arm.
        assert_u8_array_within_u8_finite_set(&[3u8, 3u8, 5u8], &[3u8, 4u8, 5u8, 6u8]);
    }

    #[test]
    #[should_panic(expected = "SUBSET-VIOLATION")]
    fn assert_u8_array_within_u8_finite_set_panics_at_runtime_on_out_of_set_entry() {
        // NEGATIVE PIN — SUBSET-VIOLATION corner: an array carrying
        // a single entry NOT in the target set MUST panic at runtime
        // with the SUBSET-VIOLATION-named message. Pins the helper's
        // OWN reject arm — a regression that silently returned
        // without panicking on an out-of-set entry would slip through
        // the compile-time witness's failure mode too. The offending
        // byte `7u8` is intentionally chosen ONE PAST the superset's
        // maximum (`QuoteForm::HASH_DISCRIMINATORS`'s upper endpoint
        // is `6u8`) to pin the OVERSHOOT drift mode.
        assert_u8_array_within_u8_finite_set(&[5u8, 7u8], &[3u8, 4u8, 5u8, 6u8]);
    }

    #[test]
    #[should_panic(expected = "SUBSET-VIOLATION")]
    fn assert_u8_array_within_u8_finite_set_panics_at_runtime_on_terminal_out_of_set_entry() {
        // NEGATIVE PIN — terminal-position drift: an out-of-set entry
        // at the LAST array position MUST panic — pins that the outer
        // `while i < N` loop reaches `i = N - 1` (else the terminal
        // drift would slip through). A regression that narrowed the
        // outer sweep to `while i < N - 1` (off-by-one on the OUTER
        // bound) would silently accept this array.
        assert_u8_array_within_u8_finite_set(&[3u8, 4u8, 5u8, 6u8, 7u8], &[3u8, 4u8, 5u8, 6u8]);
    }

    #[test]
    #[should_panic(expected = "SUBSET-VIOLATION")]
    fn assert_u8_array_within_u8_finite_set_panics_at_runtime_on_undershoot_out_of_set_entry() {
        // NEGATIVE PIN — undershoot drift mode complementary to the
        // OVERSHOOT drift mode `_panics_at_runtime_on_out_of_set_entry`
        // above: an offending byte BELOW the superset's minimum
        // (`QuoteForm::HASH_DISCRIMINATORS`'s lower endpoint is `3u8`;
        // this array carries a `0u8` entry NOT in the set) MUST panic.
        // Pins that the helper's SET-MEMBERSHIP sweep does NOT
        // silently accept bytes UNDER the target set's minimum on
        // some misapplied range-min assumption — the helper binds a
        // FINITE-SET subset relation, not a RANGE subset relation.
        assert_u8_array_within_u8_finite_set(&[0u8, 5u8], &[3u8, 4u8, 5u8, 6u8]);
    }

    #[test]
    fn assert_u8_array_within_u8_finite_set_panic_message_names_the_helper_and_subset_violation_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — SUBSET-VIOLATION arm: the
        // panic message MUST begin with the helper's own name AND
        // identify the failed AXIS as "SUBSET-VIOLATION" so
        // downstream diagnostics route the drift back to (a) the
        // helper by string search on
        // `"assert_u8_array_within_u8_finite_set"` and (b) the axis
        // by string search on `"SUBSET-VIOLATION"`. Sibling posture
        // to
        // `assert_u8_finite_set_pairwise_distinct_panic_message_names_the_helper_and_set_axis`
        // on the SET-side well-formedness sibling and
        // `assert_u8_array_covers_finite_set_panic_message_names_the_helper_and_out_of_set_axis`
        // on the ARRAY-side covers helper — all three bind the
        // (helper, failed-axis) provenance pair at ONE test per
        // helper. The axis-provenance string "SUBSET-VIOLATION" is
        // chosen DISTINCT from EVERY sibling helper's axis
        // vocabulary (`"duplicate"` on the ARRAY-side pairwise-
        // distinct sibling; `"OUT-OF-SET"` / `"SET-BYTE-MISSING"`
        // on the covers-finite-set sibling; `"OUT-OF-RANGE"` /
        // `"MISSING"` on the covers-inclusive-range sibling;
        // `"ARITY-MISMATCH"` on both `_permutes_*` compound helpers;
        // `"SET-NOT-PAIRWISE-DISTINCT"` on the SET-side well-
        // formedness sibling) so a diagnostic that names the failed
        // axis routes UNAMBIGUOUSLY to (a) this specific SUBSET-
        // embedding helper, (b) the `arr` argument as the drift
        // site rather than the `set` argument specifying the target
        // superset.
        let outcome = std::panic::catch_unwind(|| {
            assert_u8_array_within_u8_finite_set(&[5u8, 7u8], &[3u8, 4u8, 5u8, 6u8]);
        });
        let payload = outcome.expect_err(
            "assert_u8_array_within_u8_finite_set must panic on an \
             out-of-set entry — the reject-out-of-set arm is the \
             sole SUBSET-VIOLATION failure mode of the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_u8_array_within_u8_finite_set panic payload \
                 must be a static &str or String",
            );
        assert!(
            msg.contains("assert_u8_array_within_u8_finite_set"),
            "assert_u8_array_within_u8_finite_set panic message \
             {msg:?} must name the helper for provenance-preserving \
             failure diagnostics",
        );
        assert!(
            msg.contains("SUBSET-VIOLATION"),
            "assert_u8_array_within_u8_finite_set panic message \
             {msg:?} must name the failed AXIS (\"SUBSET-VIOLATION\") \
             for axis-provenance-preserving failure diagnostics",
        );
    }

    #[test]
    #[should_panic(expected = "SET-NOT-PAIRWISE-DISTINCT")]
    fn assert_u8_array_within_u8_finite_set_panics_on_malformed_target_set_spec() {
        // NEGATIVE PIN — DELEGATED SET-side well-formedness: a
        // malformed target-set spec `[3, 4, 4]` fed into the ARRAY-
        // side within helper MUST panic on the DELEGATED SET-NOT-
        // PAIRWISE-DISTINCT arm BEFORE the SUBSET-VIOLATION arm
        // fires. Pins the delegation chain: a regression that
        // dropped the `assert_u8_finite_set_pairwise_distinct(set)`
        // call at the top of `assert_u8_array_within_u8_finite_set`
        // would silently accept a malformed set and produce a
        // false-positive verdict on any `arr` embedded in the
        // DISTINCT-value subset. Sibling posture to
        // `assert_u8_array_covers_finite_set_panics_on_malformed_target_set_spec`
        // and
        // `assert_u8_array_permutes_finite_set_panics_on_malformed_target_set_spec`
        // — the three DELEGATED tests pin the SET-side well-
        // formedness arm at the top of ALL THREE finite-set-family
        // ARRAY-side helpers.
        assert_u8_array_within_u8_finite_set::<2, 3>(&[3u8, 4u8], &[3u8, 4u8, 4u8]);
    }

    // ── `assert_u8_array_within_inclusive_range` — the RANGE-MEMBERSHIP-
    // ONLY subset-embedding verifier that binds `arr ⊆ [LO..=HI]` at
    // compile time (WITHOUT the additional `[LO..=HI] ⊆ arr's entries`
    // full-coverage clause the sibling `_covers_inclusive_range` binds).
    // Contiguity-axis peer to `_within_u8_finite_set` on the (contiguity)
    // axis of the substrate's SUBSET-only verifiers. The runtime test
    // surface pins each of the helper's arms (accept-empty, accept-
    // singleton-in-range, accept-arr-equals-range-endpoints, accept-the-
    // family-wide structural-residual substrate embedding, accept-with-
    // duplicates, reject-above-HI-entry, reject-below-LO-entry, reject-
    // terminal-out-of-range-entry, panic-message-provenance on the
    // RANGE-SUBSET-VIOLATION axis) so a regression that silently weakens
    // the helper on ANY arm is caught by the helper's OWN test surface
    // rather than only surfacing as a false-positive on some future
    // range-subset-embedded `[u8; N]` array's compound pin.

    #[test]
    fn assert_u8_array_within_inclusive_range_accepts_the_empty_array_within_any_range() {
        // Empty array `arr = []` at the `[u8; 0]` corner — vacuously a
        // subset of every inclusive range (no `i` position exists to
        // test). Cross-range coverage on the trivial ARRAY corner of
        // the const-N generic across three witness-range widths
        // (singleton, small, whole-`u8`-space) to pin the helper's
        // OUTER-sweep arm across the whole (`N == 0` × `[LO..=HI]`)
        // axis. Turbofish binding required because there's no other
        // cue for the const parameters on the empty array literal.
        assert_u8_array_within_inclusive_range::<0, 0, 0>(&[]);
        assert_u8_array_within_inclusive_range::<0, 0, 6>(&[]);
        assert_u8_array_within_inclusive_range::<0, 0, 255>(&[]);
    }

    #[test]
    fn assert_u8_array_within_inclusive_range_accepts_singleton_array_when_byte_in_range() {
        // Singleton array `arr = [K]` at the `[u8; 1]` corner MUST pass
        // when `K in [LO..=HI]`. Cross-position coverage: the byte can
        // sit at the LO endpoint, an INTERIOR position, or the HI
        // endpoint — pins the OUTER-sweep's OR-disjunction guard
        // handles all three cases without gratuitously narrowing to
        // strict-inequality on either endpoint. A regression that
        // narrowed the guard to `arr[i] <= LO || arr[i] >= HI` (strict
        // endpoint exclusion) would silently reject singleton arrays
        // hitting the endpoints — this test catches BOTH endpoint
        // regressions in ONE forward sweep.
        assert_u8_array_within_inclusive_range::<1, 0, 6>(&[0u8]);
        assert_u8_array_within_inclusive_range::<1, 0, 6>(&[3u8]);
        assert_u8_array_within_inclusive_range::<1, 0, 6>(&[6u8]);
    }

    #[test]
    fn assert_u8_array_within_inclusive_range_accepts_singleton_range_when_byte_equals_endpoint() {
        // Degenerate singleton-range corner `[K..=K]` where LO == HI —
        // the ONLY accepting arrays are those whose every entry equals
        // `K`. Pins the helper does NOT gratuitously reject the LO ==
        // HI degenerate case (a regression that narrowed `LO <= HI` to
        // `LO < HI` at some downstream bounds check would surface here
        // if this helper ever grew such a check; today it does not,
        // and this test locks it out).
        assert_u8_array_within_inclusive_range::<1, 42, 42>(&[42u8]);
        assert_u8_array_within_inclusive_range::<3, 42, 42>(&[42u8, 42u8, 42u8]);
        assert_u8_array_within_inclusive_range::<1, 0, 0>(&[0u8]);
        assert_u8_array_within_inclusive_range::<1, 255, 255>(&[255u8]);
    }

    #[test]
    fn assert_u8_array_within_inclusive_range_accepts_arrays_with_duplicates() {
        // Peer corner to `_covers_inclusive_range`: this helper permits
        // duplicates in `arr` because RANGE-membership is a DISTINCT-
        // value predicate — `[3, 3, 5]` embeds in `[0..=6]` even
        // though the array is not pairwise-distinct. Pins that the
        // helper does NOT gratuitously require INJECTIVITY on `arr`
        // (the injectivity axis is a DIFFERENT compile-time contract
        // bound by `assert_u8_array_pairwise_distinct`; combining both
        // binds BOTH axes). Sibling posture to
        // `assert_u8_array_within_u8_finite_set_accepts_repeated_array_entries_in_set`
        // on the finite-set peer.
        assert_u8_array_within_inclusive_range::<3, 0, 6>(&[3u8, 3u8, 5u8]);
        assert_u8_array_within_inclusive_range::<4, 0, 6>(&[0u8, 0u8, 6u8, 6u8]);
    }

    #[test]
    fn assert_u8_array_within_inclusive_range_accepts_the_structural_residual_subset_embedding() {
        // Runtime cross-check that the ONE (array, range) pair the
        // substrate's module-level `const _` witness pins at COMPILE
        // time is a PROPER SUBSET embedding at runtime too. The pair
        // enforces the theorem at TWO stages of the toolchain: the
        // const witness fires FIRST at `cargo check` (through the
        // module-level `const _: () = assert_u8_array_within_inclusive_
        // range::<2, 0, 6>(&StructuralKind::HASH_DISCRIMINATORS)`
        // line), this runtime pin catches the drift at `cargo test`
        // as a safety net. Sibling posture to
        // `assert_u8_array_within_u8_finite_set_accepts_the_substitution_subset_embedding`
        // on the finite-set-subset peer's substrate cross-check —
        // both pin the substrate's ONE-witness embedding at BOTH
        // stages of the toolchain.
        assert_u8_array_within_inclusive_range::<2, 0, 6>(
            &crate::error::StructuralKind::HASH_DISCRIMINATORS,
        );
    }

    #[test]
    #[should_panic(expected = "RANGE-SUBSET-VIOLATION")]
    fn assert_u8_array_within_inclusive_range_panics_at_runtime_on_entry_above_hi() {
        // NEGATIVE PIN — above-HI overshoot corner: an array carrying
        // a single entry `HI + 1` MUST panic at runtime with the
        // RANGE-SUBSET-VIOLATION-named message. Pins the helper's OWN
        // reject-above-HI arm — a regression that silently returned
        // without panicking on an out-of-range entry above the upper
        // bound would slip through the compile-time witness's failure
        // mode too. The offending byte `7u8` is intentionally chosen
        // ONE PAST the outer-`Sexp` partition's upper endpoint (`6u8`)
        // to pin the OVERSHOOT drift mode against the substrate's
        // load-bearing partition.
        assert_u8_array_within_inclusive_range::<2, 0, 6>(&[0u8, 7u8]);
    }

    #[test]
    #[should_panic(expected = "RANGE-SUBSET-VIOLATION")]
    fn assert_u8_array_within_inclusive_range_panics_at_runtime_on_entry_below_lo() {
        // NEGATIVE PIN — below-LO undershoot corner symmetric to the
        // OVERSHOOT drift mode above: an offending byte BELOW the
        // range's minimum (`LO = 3u8`; this array carries a `0u8`
        // entry NOT in the range) MUST panic. Pins that the helper's
        // OR-disjunction guard does NOT drop the `arr[i] < LO` half
        // (leaving only the `arr[i] > HI` half) — a regression that
        // silently accepted below-LO entries would surface here.
        assert_u8_array_within_inclusive_range::<2, 3, 6>(&[0u8, 5u8]);
    }

    #[test]
    #[should_panic(expected = "RANGE-SUBSET-VIOLATION")]
    fn assert_u8_array_within_inclusive_range_panics_at_runtime_on_terminal_out_of_range_entry() {
        // NEGATIVE PIN — terminal-position drift: an out-of-range
        // entry at the LAST array position MUST panic — pins that the
        // outer `while i < N` loop reaches `i = N - 1` (else the
        // terminal drift would slip through). A regression that
        // narrowed the outer sweep to `while i < N - 1` (off-by-one on
        // the OUTER bound) would silently accept this array. Sibling
        // posture to
        // `assert_u8_array_within_u8_finite_set_panics_at_runtime_on_terminal_out_of_set_entry`
        // on the finite-set-subset peer's terminal-position pin —
        // both bind the outer-sweep terminal bound at the ONE array-
        // side outer loop the helper carries.
        assert_u8_array_within_inclusive_range::<4, 0, 6>(&[0u8, 3u8, 6u8, 7u8]);
    }

    #[test]
    fn assert_u8_array_within_inclusive_range_panic_message_names_the_helper_and_range_subset_violation_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — RANGE-SUBSET-VIOLATION arm:
        // the panic message MUST begin with the helper's own name AND
        // identify the failed AXIS as "RANGE-SUBSET-VIOLATION" so
        // downstream diagnostics route the drift back to (a) the
        // helper by string search on
        // `"assert_u8_array_within_inclusive_range"` and (b) the axis
        // by string search on `"RANGE-SUBSET-VIOLATION"`. Sibling
        // posture to
        // `assert_u8_array_within_u8_finite_set_panic_message_names_the_helper_and_subset_violation_axis`
        // on the finite-set-subset peer's provenance pin — the two
        // pins together bind the (helper, failed-axis) provenance
        // pair at ONE test per SUBSET helper on the (contiguity)
        // 2×2 face. The axis-provenance string
        // `"RANGE-SUBSET-VIOLATION"` is chosen DISTINCT from EVERY
        // sibling helper's axis vocabulary (`"duplicate"` on the
        // ARRAY-side pairwise-distinct sibling; `"OUT-OF-SET"` /
        // `"SET-BYTE-MISSING"` on the covers-finite-set sibling;
        // `"OUT-OF-RANGE"` / `"MISSING"` on the covers-inclusive-
        // range sibling; `"SUBSET-VIOLATION"` on the finite-set
        // SUBSET-only sibling; `"ARITY-MISMATCH"` on both
        // `_permutes_*` compound helpers; `"SET-NOT-PAIRWISE-
        // DISTINCT"` on the SET-side well-formedness sibling) so a
        // diagnostic that names the failed axis routes UNAMBIGUOUSLY
        // to (a) this specific range SUBSET-embedding helper, (b)
        // the `arr` argument as the drift site rather than the
        // `LO`/`HI` const parameters specifying the target range.
        let outcome = std::panic::catch_unwind(|| {
            assert_u8_array_within_inclusive_range::<2, 0, 6>(&[0u8, 7u8]);
        });
        let payload = outcome.expect_err(
            "assert_u8_array_within_inclusive_range must panic on an \
             out-of-range entry — the reject-out-of-range arm is the \
             sole RANGE-SUBSET-VIOLATION failure mode of the helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_u8_array_within_inclusive_range panic payload \
                 must be a static &str or String",
            );
        assert!(
            msg.contains("assert_u8_array_within_inclusive_range"),
            "assert_u8_array_within_inclusive_range panic message \
             {msg:?} must name the helper for provenance-preserving \
             failure diagnostics",
        );
        assert!(
            msg.contains("RANGE-SUBSET-VIOLATION"),
            "assert_u8_array_within_inclusive_range panic message \
             {msg:?} must name the failed AXIS (\"RANGE-SUBSET-\
             VIOLATION\") for axis-provenance-preserving failure \
             diagnostics",
        );
    }

    // ── `assert_u8_array_permutes_inclusive_range` — the compound
    // (INJECTIVITY ∧ SURJECTIVITY ∧ ARITY) permutation-of-range
    // verifier that collapses the pre-existing weak-witness pair
    // (`assert_u8_array_pairwise_distinct` +
    // `assert_u8_array_covers_inclusive_range`) into ONE `const _`
    // line per array on the three permutation-shaped
    // HASH_DISCRIMINATORS arrays (`AtomKind`, `QuoteForm`,
    // `UnquoteForm`). The runtime test surface matches the sibling-
    // helpers' shape (accept-singleton, accept-every-family-wide-
    // substrate-array, reject-arity-below-cardinality, reject-
    // arity-above-cardinality, reject-duplicate, reject-out-of-range,
    // panic-message-provenance on the ARITY-MISMATCH axis, panic-
    // message-provenance on the DELEGATED range-coverage axis,
    // panic-message-provenance on the DELEGATED pairwise-distinct
    // axis) split across the THREE failure arms so a regression that
    // silently weakens the helper on ANY arm (e.g. dropping the arity
    // check, dropping the range-coverage delegation, or dropping the
    // pairwise-distinct delegation) is caught by the helper's OWN
    // test surface rather than only surfacing as a false-positive on
    // some future permutation-shaped `[u8; N]` array's compound pin.

    #[test]
    fn assert_u8_array_permutes_inclusive_range_accepts_the_singleton_range() {
        // Singleton range `{K..=K}` at the `[u8; 1]` corner — a
        // singleton array `[K]` is vacuously a permutation of `{K}`.
        // Cross-arity coverage on the trivial-range corner of the
        // const-N generic; simultaneously pins ALL THREE arms
        // (ARITY: `1 == 1`; RANGE-MEMBERSHIP: `K in [K, K]`;
        // PAIRWISE-DISTINCT: vacuously true on a singleton) at the
        // smallest witness. Sibling posture to
        // `assert_u8_array_covers_inclusive_range_accepts_the_
        // singleton_range` on the delegated range-coverage helper.
        assert_u8_array_permutes_inclusive_range::<1, 7, 7>(&[7u8]);
        assert_u8_array_permutes_inclusive_range::<1, 0, 0>(&[0u8]);
        assert_u8_array_permutes_inclusive_range::<1, 255, 255>(&[255u8]);
    }

    #[test]
    fn assert_u8_array_permutes_inclusive_range_accepts_every_family_wide_permutation_array() {
        // Runtime cross-check that the SAME three permutation-shaped
        // HASH_DISCRIMINATORS arrays the module-level `const _: () =
        // ...` witnesses cover at COMPILE time are permutations of
        // their target ranges. 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 drift at `cargo test`.
        // The pair enforces the theorem at TWO stages of the
        // toolchain. Sibling posture to
        // `assert_u8_array_covers_inclusive_range_accepts_every_
        // family_wide_substrate_array` on the delegated range-
        // coverage helper; where that pin sweeps FOUR arrays
        // (`SexpShape` + `AtomKind` + `QuoteForm` + `UnquoteForm`)
        // on the single-axis SURJECTIVITY corner, this pin sweeps
        // the THREE permutation-shaped arrays on the compound
        // (INJECTIVITY ∧ SURJECTIVITY ∧ ARITY) corner —
        // `SexpShape::HASH_DISCRIMINATORS` is intentionally OMITTED
        // per the twelve-shape → seven-byte collapse rule
        // (DISTINCTNESS does not hold; it binds SURJECTIVITY-only
        // on the sibling helper).
        assert_u8_array_permutes_inclusive_range::<6, 0, 5>(&AtomKind::HASH_DISCRIMINATORS);
        assert_u8_array_permutes_inclusive_range::<4, 3, 6>(&QuoteForm::HASH_DISCRIMINATORS);
        assert_u8_array_permutes_inclusive_range::<2, 5, 6>(
            &crate::error::UnquoteForm::HASH_DISCRIMINATORS,
        );
    }

    #[test]
    #[should_panic(expected = "ARITY-MISMATCH")]
    fn assert_u8_array_permutes_inclusive_range_panics_at_runtime_on_arity_below_cardinality() {
        // NEGATIVE PIN — ARITY-MISMATCH below-cardinality corner: an
        // array of arity `N < HI - LO + 1` MUST panic at runtime with
        // the ARITY-MISMATCH-named message. Pins the compound
        // helper's OWN reject-below-cardinality arm — a regression
        // that silently dropped the arity-check gate would let this
        // array reach the delegated `assert_u8_array_covers_
        // inclusive_range` call, which would then panic with the
        // sibling helper's `"MISSING"` message on the range byte
        // absent from the too-short array — masking the ARITY-
        // provenance behind the coverage-provenance downstream.
        assert_u8_array_permutes_inclusive_range::<2, 0, 2>(&[0u8, 2u8]);
    }

    #[test]
    #[should_panic(expected = "ARITY-MISMATCH")]
    fn assert_u8_array_permutes_inclusive_range_panics_at_runtime_on_arity_above_cardinality() {
        // NEGATIVE PIN — ARITY-MISMATCH above-cardinality corner: an
        // array of arity `N > HI - LO + 1` MUST panic at runtime with
        // the ARITY-MISMATCH-named message. Symmetric sibling to the
        // below-cardinality pin — a regression that dropped the
        // arity-check gate would let this array reach the delegated
        // `assert_u8_array_pairwise_distinct` call, which would then
        // panic with the sibling helper's generic-duplicate message
        // on the pigeonhole-forced collision, masking the ARITY-
        // provenance behind the pairwise-distinct-provenance
        // downstream. The three entries stay within `[0, 1]` and are
        // pairwise-distinct on the first two positions, so the arity
        // check is the ONLY axis that can distinguish this from a
        // valid permutation.
        assert_u8_array_permutes_inclusive_range::<3, 0, 1>(&[0u8, 1u8, 0u8]);
    }

    #[test]
    #[should_panic(expected = "duplicate")]
    fn assert_u8_array_permutes_inclusive_range_panics_at_runtime_on_duplicate() {
        // NEGATIVE PIN — PAIRWISE-DISTINCT arm: an array whose arity
        // matches the range cardinality but which contains a
        // duplicate entry (necessarily missing a range byte by
        // pigeonhole) MUST panic at runtime. Pins the delegated
        // `assert_u8_array_pairwise_distinct` arm — a regression
        // that silently dropped the delegation would leave the
        // duplicate uncaught. Note: the panic message here surfaces
        // from the SIBLING helper (containing `"duplicate"`) rather
        // than a compound-helper-namespaced string, per the
        // delegation-based body design; the compound helper's OWN
        // name still appears in the const-eval panic trace for a
        // caller debugging a `cargo check` failure.
        assert_u8_array_permutes_inclusive_range::<3, 0, 2>(&[0u8, 1u8, 1u8]);
    }

    #[test]
    #[should_panic(expected = "OUT-OF-RANGE")]
    fn assert_u8_array_permutes_inclusive_range_panics_at_runtime_on_out_of_range() {
        // NEGATIVE PIN — RANGE-MEMBERSHIP arm: an array whose arity
        // matches the range cardinality but which contains an
        // out-of-range entry MUST panic at runtime with the
        // delegated `assert_u8_array_covers_inclusive_range`'s
        // `"OUT-OF-RANGE"` axis-provenance message. Pins the
        // delegated range-membership arm — a regression that
        // silently dropped the delegation would leave the
        // out-of-range entry uncaught. The three entries `[0, 1, 3]`
        // exhaust the arity of `[0..=2]` (3 entries for a 3-byte
        // range) but include `3u8` outside the target range;
        // pairwise-distinct is satisfied so this array can ONLY be
        // rejected on the range-membership axis.
        assert_u8_array_permutes_inclusive_range::<3, 0, 2>(&[0u8, 1u8, 3u8]);
    }

    #[test]
    fn assert_u8_array_permutes_inclusive_range_panic_message_names_the_helper_and_arity_mismatch_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — ARITY-MISMATCH arm: the
        // panic message MUST begin with the compound helper's own
        // name AND identify the failed AXIS as "ARITY-MISMATCH" so
        // downstream diagnostics route the drift back to (a) THIS
        // compound helper by string search on
        // `"assert_u8_array_permutes_inclusive_range"` and (b) the
        // ARITY axis by string search on `"ARITY-MISMATCH"`. This
        // string is chosen DISTINCT from every sibling helper's axis
        // strings ("OUT-OF-RANGE" / "MISSING" on the range-coverage
        // helper; "OUT-OF-SET" / "SET-BYTE-MISSING" on the finite-
        // set-coverage helper) so a drift's axis-provenance routes
        // UNAMBIGUOUSLY to (helper, axis) even in the presence of
        // the multiple sibling helpers. Sibling posture to
        // `assert_u8_array_covers_inclusive_range_panic_message_
        // names_the_helper_and_range_bound_axis` on the range-
        // coverage helper — both bind the (helper, failed-axis)
        // provenance pair at ONE test per axis.
        let outcome = std::panic::catch_unwind(|| {
            assert_u8_array_permutes_inclusive_range::<2, 0, 2>(&[0u8, 2u8]);
        });
        let payload = outcome.expect_err(
            "assert_u8_array_permutes_inclusive_range must panic on \
             an arity-cardinality mismatch — the reject-arity-\
             mismatch arm is one of the three failure modes of the \
             compound helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_u8_array_permutes_inclusive_range panic \
                 payload must be a static &str or String",
            );
        assert!(
            msg.contains("assert_u8_array_permutes_inclusive_range"),
            "assert_u8_array_permutes_inclusive_range ARITY-MISMATCH \
             panic message {msg:?} must name the helper for \
             provenance-preserving failure diagnostics",
        );
        assert!(
            msg.contains("ARITY-MISMATCH"),
            "assert_u8_array_permutes_inclusive_range ARITY-MISMATCH \
             panic message {msg:?} must name the failed AXIS \
             (\"ARITY-MISMATCH\") for axis-provenance-preserving \
             failure diagnostics — the string is chosen DISTINCT \
             from every sibling helper's axis strings so downstream \
             diagnostics route UNAMBIGUOUSLY to this compound \
             helper's arity arm",
        );
    }

    // ── `assert_u8_array_permutes_finite_set` — the compound
    // (INJECTIVITY ∧ SURJECTIVITY ∧ ARITY) permutation-of-finite-set
    // verifier on the NON-CONTIGUOUS-FINITE-SET corner of the
    // (contiguity) axis peer to the pre-existing
    // `assert_u8_array_permutes_inclusive_range` (contiguous-
    // inclusive-range corner) sibling. Ships `StructuralKind::HASH_
    // DISCRIMINATORS` from the pre-lift weak-witness pair
    // (`assert_u8_array_pairwise_distinct` + `assert_u8_array_covers_
    // finite_set`) into the compound tier at ONE `const _` line while
    // adding the arity-cardinality-equality contract that neither
    // weak sibling carries alone. The runtime test surface mirrors
    // the sibling `assert_u8_array_permutes_inclusive_range` compound
    // helper's shape (accept-singleton-set, accept-every-family-wide-
    // substrate-array, reject-arity-below-cardinality, reject-arity-
    // above-cardinality, reject-duplicate, reject-out-of-set, panic-
    // message-provenance on the ARITY-MISMATCH axis) split across the
    // three failure arms so a regression that silently weakens the
    // helper on ANY arm (e.g. dropping the arity check, dropping the
    // covers-finite-set delegation, or dropping the pairwise-distinct
    // delegation) is caught by the helper's OWN test surface rather
    // than only surfacing as a false-positive on some future
    // permutation-of-finite-set-shaped `[u8; N]` array's compound pin.

    #[test]
    fn assert_u8_array_permutes_finite_set_accepts_the_singleton_set() {
        // Singleton set `{K}` at the `[u8; 1]` corner — a singleton
        // array `[K]` is vacuously a permutation of `{K}`. Cross-arity
        // coverage on the trivial-set corner of the const-N generic;
        // simultaneously pins ALL THREE arms (ARITY: `1 == 1`; SET-
        // MEMBERSHIP: `K in {K}`; PAIRWISE-DISTINCT: vacuously true on
        // a singleton) at the smallest witness. Sibling posture to
        // `assert_u8_array_permutes_inclusive_range_accepts_the_
        // singleton_range` on the contiguous-range corner peer.
        assert_u8_array_permutes_finite_set::<1, 1>(&[7u8], &[7u8]);
        assert_u8_array_permutes_finite_set::<1, 1>(&[0u8], &[0u8]);
        assert_u8_array_permutes_finite_set::<1, 1>(&[255u8], &[255u8]);
    }

    #[test]
    fn assert_u8_array_permutes_finite_set_accepts_every_family_wide_permutation_of_finite_set_array(
    ) {
        // Runtime cross-check that the SAME
        // `StructuralKind::HASH_DISCRIMINATORS` array the module-level
        // `const _: () = ...` witness covers at COMPILE time is a
        // permutation of the non-contiguous target set `{0, 2}`. A
        // regression that removes the `const _` witness would still
        // leave THIS runtime pin as a safety net; the const witness
        // fires FIRST at `cargo check`, this runtime pin catches the
        // drift at `cargo test`. The pair enforces the theorem at TWO
        // stages of the toolchain. Sibling posture to
        // `assert_u8_array_permutes_inclusive_range_accepts_every_
        // family_wide_permutation_array` on the contiguous-range
        // corner: where that pin sweeps THREE range-covering arrays
        // (`AtomKind` + `QuoteForm` + `UnquoteForm`), this pin binds
        // the ONE non-contiguous-covering permutation-shaped array
        // (`StructuralKind`). Together the two runtime pins close the
        // whole compound tier of the substrate's `[u8; N]`
        // HASH_DISCRIMINATORS vocabulary at runtime symmetrically to
        // the compile-time compound witnesses.
        assert_u8_array_permutes_finite_set::<2, 2>(
            &crate::error::StructuralKind::HASH_DISCRIMINATORS,
            &[0u8, 2u8],
        );
    }

    #[test]
    fn assert_u8_array_permutes_finite_set_accepts_a_synthetic_non_contiguous_partition() {
        // POSITIVE — a synthetic `[u8; 3]` permutation of the non-
        // contiguous partition `{0, 2, 5}` (two gaps: at `{1}` and at
        // `{3, 4}`). Isolates the helper's INJECTIVITY-∧-SURJECTIVITY-
        // ∧-ARITY verdict from the substrate constants: a green here
        // plus a red on any of the negative pins below constrains the
        // helper's behavior structurally on the non-contiguous corner,
        // independent of the substrate's specific byte layout. Sibling
        // posture to `assert_u8_array_covers_finite_set_accepts_the_
        // non_contiguous_partition` on the single-axis SURJECTIVITY
        // sibling — where that pin binds the (SET-MEMBERSHIP + FULL-
        // COVERAGE) axes on a non-contiguous set, THIS pin binds the
        // compound (INJECTIVITY ∧ SURJECTIVITY ∧ ARITY) contract on
        // the same shape.
        assert_u8_array_permutes_finite_set::<3, 3>(&[0u8, 2u8, 5u8], &[0u8, 2u8, 5u8]);
        assert_u8_array_permutes_finite_set::<3, 3>(&[5u8, 0u8, 2u8], &[0u8, 2u8, 5u8]);
    }

    #[test]
    #[should_panic(expected = "ARITY-MISMATCH")]
    fn assert_u8_array_permutes_finite_set_panics_at_runtime_on_arity_below_cardinality() {
        // NEGATIVE PIN — ARITY-MISMATCH below-cardinality corner: an
        // array of arity `N < M` MUST panic at runtime with the ARITY-
        // MISMATCH-named message. Pins the compound helper's OWN
        // reject-below-cardinality arm — a regression that silently
        // dropped the arity-check gate would let this array reach the
        // delegated `assert_u8_array_covers_finite_set` call, which
        // would then panic with the sibling helper's `"SET-BYTE-
        // MISSING"` message on the set byte absent from the too-short
        // array — masking the ARITY-provenance behind the coverage-
        // provenance downstream. The array `[0]` covers set byte `0`
        // but is missing set byte `2`. Sibling posture to
        // `assert_u8_array_permutes_inclusive_range_panics_at_runtime_
        // on_arity_below_cardinality` on the contiguous-range corner.
        assert_u8_array_permutes_finite_set::<1, 2>(&[0u8], &[0u8, 2u8]);
    }

    #[test]
    #[should_panic(expected = "ARITY-MISMATCH")]
    fn assert_u8_array_permutes_finite_set_panics_at_runtime_on_arity_above_cardinality() {
        // NEGATIVE PIN — ARITY-MISMATCH above-cardinality corner: an
        // array of arity `N > M` MUST panic at runtime with the
        // ARITY-MISMATCH-named message. Symmetric sibling to the
        // below-cardinality pin — a regression that dropped the arity-
        // check gate would let this array reach the delegated
        // `assert_u8_array_pairwise_distinct` call, which would then
        // panic with the sibling helper's generic-duplicate message on
        // the pigeonhole-forced collision, masking the ARITY-
        // provenance behind the pairwise-distinct-provenance
        // downstream. The three entries `[0, 2, 0]` stay within
        // `{0, 2}` (satisfying SET-MEMBERSHIP) but WOULD fail
        // pairwise-distinct downstream on the duplicate `0u8` —
        // however, the ARITY-check FIRES FIRST so the panic message
        // routes to the ARITY axis with the compound helper's own
        // name.
        assert_u8_array_permutes_finite_set::<3, 2>(&[0u8, 2u8, 0u8], &[0u8, 2u8]);
    }

    #[test]
    #[should_panic(expected = "duplicate")]
    fn assert_u8_array_permutes_finite_set_panics_at_runtime_on_duplicate() {
        // NEGATIVE PIN — PAIRWISE-DISTINCT arm: an array whose arity
        // matches the set cardinality but which contains a duplicate
        // entry (necessarily missing a set byte by pigeonhole) MUST
        // panic at runtime. Pins the delegated
        // `assert_u8_array_pairwise_distinct` arm — a regression that
        // silently dropped the delegation would leave the duplicate
        // uncaught. Note: the panic message here surfaces from the
        // SIBLING helper (containing `"duplicate"`) rather than a
        // compound-helper-namespaced string, per the delegation-based
        // body design; the compound helper's OWN name still appears
        // in the const-eval panic trace for a caller debugging a
        // `cargo check` failure. Sibling posture to
        // `assert_u8_array_permutes_inclusive_range_panics_at_runtime_
        // on_duplicate` on the contiguous-range corner.
        assert_u8_array_permutes_finite_set::<3, 3>(&[0u8, 2u8, 2u8], &[0u8, 2u8, 5u8]);
    }

    #[test]
    #[should_panic(expected = "OUT-OF-SET")]
    fn assert_u8_array_permutes_finite_set_panics_at_runtime_on_out_of_set() {
        // NEGATIVE PIN — SET-MEMBERSHIP arm: an array whose arity
        // matches the set cardinality but which contains an entry
        // outside the target set MUST panic at runtime with the
        // delegated `assert_u8_array_covers_finite_set`'s `"OUT-OF-
        // SET"` axis-provenance message. Pins the delegated set-
        // membership arm — a regression that silently dropped the
        // delegation would leave the out-of-set entry uncaught. The
        // three entries `[0, 2, 3]` exhaust the arity of `{0, 2, 5}`
        // (3 entries for a 3-byte set) but include `3u8` outside the
        // target set; pairwise-distinct is satisfied so this array
        // can ONLY be rejected on the set-membership axis. Sibling
        // posture to `assert_u8_array_permutes_inclusive_range_panics_
        // at_runtime_on_out_of_range` on the contiguous-range corner
        // (`"OUT-OF-SET"` here vs. `"OUT-OF-RANGE"` there — chosen
        // DISTINCT so downstream diagnostics route UNAMBIGUOUSLY to
        // the failed contiguity corner).
        assert_u8_array_permutes_finite_set::<3, 3>(&[0u8, 2u8, 3u8], &[0u8, 2u8, 5u8]);
    }

    #[test]
    #[should_panic(expected = "OUT-OF-SET")]
    fn assert_u8_array_permutes_finite_set_panics_on_gap_byte_drift() {
        // NEGATIVE PIN — ARCHETYPE GAP-BYTE corner: an entry that
        // drifts INTO the intentional gap of a non-contiguous target
        // set MUST panic — this is the exact regression the archetype
        // `StructuralKind::HASH_DISCRIMINATORS` witness catches. A
        // regression that lifted a fresh `1u8` entry into the
        // `{0, 2}`-partitioned array would silently collide with
        // `AtomKind::OUTER_HASH_DISCRIMINATOR = 1u8` on the outer-
        // `Sexp` cache-key partition; this pin binds that failure mode
        // as an OUT-OF-SET rejection at the delegated covers-finite-
        // set arm's panic site. Sibling posture to `assert_u8_array_
        // covers_finite_set_panics_on_gap_byte_drift` at the single-
        // axis SURJECTIVITY sibling — where that pin binds the gap-
        // byte-drift failure at the (SET-MEMBERSHIP) axis alone, THIS
        // pin binds the SAME drift on the compound (INJECTIVITY ∧
        // SURJECTIVITY ∧ ARITY) contract. The four-entry witness
        // `[0, 1, 2, 5]` stays pairwise-distinct and matches the set
        // cardinality of `{0, 2, 1, 5}` but the middle `1u8` — if the
        // set were `{0, 2, 5}` and `[0, 1, 2]` were the array — would
        // fire the OUT-OF-SET arm; here the arity is aligned to test
        // the middle-gap drift with `1u8` in `arr` but NOT in `set`.
        assert_u8_array_permutes_finite_set::<3, 3>(&[0u8, 1u8, 2u8], &[0u8, 2u8, 5u8]);
    }

    #[test]
    fn assert_u8_array_permutes_finite_set_panic_message_names_the_helper_and_arity_mismatch_axis()
    {
        // PANIC-MESSAGE PROVENANCE PIN — ARITY-MISMATCH arm: the panic
        // message MUST begin with the compound helper's own name AND
        // identify the failed AXIS as "ARITY-MISMATCH" so downstream
        // diagnostics route the drift back to (a) THIS compound helper
        // by string search on
        // `"assert_u8_array_permutes_finite_set"` and (b) the ARITY
        // axis by string search on `"ARITY-MISMATCH"`. The
        // "ARITY-MISMATCH" axis-name is SHARED with the contiguous-
        // range sibling `assert_u8_array_permutes_inclusive_range`
        // (both compound permutation helpers share the arity axis),
        // but the HELPER-name distinguishes the two: string search on
        // (`"assert_u8_array_permutes_finite_set"`, `"ARITY-MISMATCH"`)
        // routes UNAMBIGUOUSLY to the (non-contiguous corner, arity
        // arm) pair. Sibling posture to
        // `assert_u8_array_permutes_inclusive_range_panic_message_
        // names_the_helper_and_arity_mismatch_axis` on the contiguous-
        // range corner — both bind the (helper, failed-axis)
        // provenance pair at ONE test per axis.
        let outcome = std::panic::catch_unwind(|| {
            assert_u8_array_permutes_finite_set::<1, 2>(&[0u8], &[0u8, 2u8]);
        });
        let payload = outcome.expect_err(
            "assert_u8_array_permutes_finite_set must panic on an \
             arity-cardinality mismatch — the reject-arity-mismatch \
             arm is one of the three failure modes of the compound \
             helper",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_u8_array_permutes_finite_set panic payload \
                 must be a static &str or String",
            );
        assert!(
            msg.contains("assert_u8_array_permutes_finite_set"),
            "assert_u8_array_permutes_finite_set ARITY-MISMATCH panic \
             message {msg:?} must name the helper for provenance-\
             preserving failure diagnostics — the HELPER-name is the \
             axis-name-tie-breaker between this helper and the \
             contiguous-range sibling which SHARES the \
             \"ARITY-MISMATCH\" axis-provenance string",
        );
        assert!(
            msg.contains("ARITY-MISMATCH"),
            "assert_u8_array_permutes_finite_set ARITY-MISMATCH panic \
             message {msg:?} must name the failed AXIS \
             (\"ARITY-MISMATCH\") for axis-provenance-preserving \
             failure diagnostics",
        );
    }

    // ── `assert_scalar_plus_two_u8_arrays_permute_inclusive_range` —
    // the compound JOINT (INJECTIVITY ∧ SURJECTIVITY ∧ ARITY)
    // permutation-of-range verifier on the (scalar-plus-two-arrays)
    // corner of the (carving-shape) axis peer to the pre-existing
    // (single-array) corner. The runtime test surface matches the
    // sibling `assert_u8_array_permutes_inclusive_range` compound
    // helper's shape (accept-canonical-outer-Sexp-partition, accept-
    // synthetic-valid-partition, reject-arity-below-cardinality,
    // reject-arity-above-cardinality, reject-scalar-out-of-range,
    // reject-first-array-out-of-range, reject-second-array-out-of-
    // range, reject-cross-carving-duplicate, reject-intra-carving-
    // duplicate, panic-message-provenance on the JOINT ARITY-
    // MISMATCH axis, panic-message-provenance on the JOINT SCALAR-
    // OUT-OF-RANGE axis) split across the six failure arms so a
    // regression that silently weakens the helper on ANY arm is
    // caught by the helper's OWN test surface rather than only
    // surfacing as a false-positive on some future permutation-
    // shaped joint carving's compound pin.

    #[test]
    fn assert_scalar_plus_two_u8_arrays_permute_inclusive_range_accepts_canonical_outer_sexp_partition(
    ) {
        // Runtime cross-check that the SAME joint carving the
        // module-level `const _: () = ...` witness covers at COMPILE
        // time is a permutation of the outer-`Sexp` cache-key
        // discriminator range `{0..=6}`. A regression that removes
        // the `const _` witness would still leave THIS runtime pin as
        // a safety net; the const witness fires FIRST at `cargo
        // check`, this runtime pin catches the drift at `cargo test`.
        // The pair enforces the joint theorem at TWO stages of the
        // toolchain. Sibling posture to
        // `assert_u8_array_permutes_inclusive_range_accepts_every_
        // family_wide_permutation_array` on the (single-array)
        // corner — where that pin sweeps THREE arrays on the
        // single-array corner, THIS pin binds the ONE joint carving
        // on the (scalar-plus-two-arrays) corner.
        assert_scalar_plus_two_u8_arrays_permute_inclusive_range::<2, 4, 0, 6>(
            AtomKind::OUTER_HASH_DISCRIMINATOR,
            &crate::error::StructuralKind::HASH_DISCRIMINATORS,
            &QuoteForm::HASH_DISCRIMINATORS,
        );
    }

    #[test]
    fn assert_scalar_plus_two_u8_arrays_permute_inclusive_range_accepts_synthetic_valid_partition()
    {
        // POSITIVE — a valid `(scalar, [u8; 2], [u8; 4])` permutation
        // of `{0..=6}` byte-identical in shape to the outer-`Sexp`
        // partition but with the scalar at `1u8` remapped through
        // literals rather than the substrate constant. Isolates the
        // helper's INJECTIVITY-∧-SURJECTIVITY-∧-ARITY verdict from
        // the substrate constants: a green here plus a red on any
        // of the negative pins below constrains the helper's
        // behavior structurally, independent of the substrate's
        // specific byte layout.
        assert_scalar_plus_two_u8_arrays_permute_inclusive_range::<2, 4, 0, 6>(
            1u8,
            &[0u8, 2u8],
            &[3u8, 4u8, 5u8, 6u8],
        );
    }

    #[test]
    #[should_panic(expected = "ARITY-MISMATCH")]
    fn assert_scalar_plus_two_u8_arrays_permute_inclusive_range_panics_at_runtime_on_arity_below_cardinality(
    ) {
        // NEGATIVE PIN — ARITY-MISMATCH below-cardinality corner: a
        // joint carving of arity `1 + M + N < HI - LO + 1` MUST
        // panic at runtime with the ARITY-MISMATCH-named message.
        // Pins the helper's OWN reject-below-cardinality arm — a
        // regression that silently dropped the arity-check gate
        // would let this triple reach the sweep-and-count loop,
        // which would then panic with `"MISSING"` on the range byte
        // absent from the too-short joint carving — masking the
        // JOINT ARITY-provenance behind the JOINT SURJECTIVITY-
        // provenance downstream. Sibling posture to
        // `assert_u8_array_permutes_inclusive_range_panics_at_
        // runtime_on_arity_below_cardinality` on the (single-array)
        // corner.
        assert_scalar_plus_two_u8_arrays_permute_inclusive_range::<2, 3, 0, 6>(
            1u8,
            &[0u8, 2u8],
            &[3u8, 4u8, 5u8],
        );
    }

    #[test]
    #[should_panic(expected = "ARITY-MISMATCH")]
    fn assert_scalar_plus_two_u8_arrays_permute_inclusive_range_panics_at_runtime_on_arity_above_cardinality(
    ) {
        // NEGATIVE PIN — ARITY-MISMATCH above-cardinality corner:
        // symmetric sibling to the below-cardinality pin. `1 + 2 + 3
        // = 6` slots for a `{0..=2}` range of cardinality 3 — the
        // arity check fires FIRST before the sweep-and-count would
        // catch the joint duplicates on `0`/`1`/`2`. Pins that the
        // ARITY-provenance surfaces even when downstream axes would
        // ALSO reject.
        assert_scalar_plus_two_u8_arrays_permute_inclusive_range::<2, 3, 0, 2>(
            0u8,
            &[1u8, 2u8],
            &[0u8, 1u8, 2u8],
        );
    }

    #[test]
    #[should_panic(expected = "OUT-OF-RANGE")]
    fn assert_scalar_plus_two_u8_arrays_permute_inclusive_range_panics_at_runtime_on_scalar_out_of_range(
    ) {
        // NEGATIVE PIN — SCALAR OUT-OF-RANGE arm: a joint carving
        // whose arity matches the range cardinality but whose SCALAR
        // lies outside `[LO, HI]` MUST panic at runtime. Pins the
        // helper's scalar-carving arm distinct from the array
        // carvings' out-of-range arms — a regression that skipped
        // the scalar check but kept the array checks would leave
        // this drift uncaught.
        assert_scalar_plus_two_u8_arrays_permute_inclusive_range::<2, 4, 0, 6>(
            7u8,
            &[0u8, 2u8],
            &[3u8, 4u8, 5u8, 6u8],
        );
    }

    #[test]
    #[should_panic(expected = "OUT-OF-RANGE")]
    fn assert_scalar_plus_two_u8_arrays_permute_inclusive_range_panics_at_runtime_on_first_array_out_of_range(
    ) {
        // NEGATIVE PIN — FIRST-ARRAY OUT-OF-RANGE arm: a joint
        // carving whose arity + scalar are valid but whose FIRST
        // ARRAY carries an out-of-range entry MUST panic at runtime.
        // The `1u8` slot the scalar occupies is left absent from
        // the first array; the entry `7u8` lies outside `[0, 6]`.
        assert_scalar_plus_two_u8_arrays_permute_inclusive_range::<2, 4, 0, 6>(
            1u8,
            &[0u8, 7u8],
            &[3u8, 4u8, 5u8, 6u8],
        );
    }

    #[test]
    #[should_panic(expected = "OUT-OF-RANGE")]
    fn assert_scalar_plus_two_u8_arrays_permute_inclusive_range_panics_at_runtime_on_second_array_out_of_range(
    ) {
        // NEGATIVE PIN — SECOND-ARRAY OUT-OF-RANGE arm: symmetric
        // sibling to the first-array pin. The entry `9u8` in the
        // second array lies outside `[0, 6]`; all other arms are
        // green.
        assert_scalar_plus_two_u8_arrays_permute_inclusive_range::<2, 4, 0, 6>(
            1u8,
            &[0u8, 2u8],
            &[3u8, 4u8, 5u8, 9u8],
        );
    }

    #[test]
    #[should_panic(expected = "duplicate")]
    fn assert_scalar_plus_two_u8_arrays_permute_inclusive_range_panics_at_runtime_on_cross_carving_duplicate(
    ) {
        // NEGATIVE PIN — JOINT-duplicate arm (cross-carving): the
        // byte `1u8` appears in BOTH the scalar carving AND the
        // first array. Arity matches, all bytes are in-range, but
        // JOINT INJECTIVITY fails — the duplicate byte occurs at
        // `count == 2` in the sweep-and-count loop, masking the
        // pigeonhole-forced JOINT-MISSING at byte `2u8` behind the
        // duplicate arm's message. Pins the cross-carving collision
        // detection between the scalar arm and a downstream array
        // arm.
        assert_scalar_plus_two_u8_arrays_permute_inclusive_range::<2, 4, 0, 6>(
            1u8,
            &[0u8, 1u8],
            &[3u8, 4u8, 5u8, 6u8],
        );
    }

    #[test]
    #[should_panic(expected = "duplicate")]
    fn assert_scalar_plus_two_u8_arrays_permute_inclusive_range_panics_at_runtime_on_intra_carving_duplicate(
    ) {
        // NEGATIVE PIN — JOINT-duplicate arm (intra-carving): the
        // byte `0u8` appears TWICE inside the first array. Arity
        // matches, all bytes are in-range, but JOINT INJECTIVITY
        // fails — the sweep-and-count discipline treats intra- and
        // cross-carving collisions with the SAME mechanism, so this
        // failure mode surfaces on the same `"duplicate"` axis-
        // provenance message as the cross-carving pin.
        assert_scalar_plus_two_u8_arrays_permute_inclusive_range::<2, 4, 0, 6>(
            1u8,
            &[0u8, 0u8],
            &[3u8, 4u8, 5u8, 6u8],
        );
    }

    #[test]
    fn assert_scalar_plus_two_u8_arrays_permute_inclusive_range_panic_message_names_the_helper_and_arity_mismatch_axis(
    ) {
        // PANIC-MESSAGE PROVENANCE PIN — ARITY-MISMATCH arm: the
        // panic message MUST begin with the compound helper's own
        // name AND identify the failed AXIS as "ARITY-MISMATCH".
        // Sibling posture to `assert_u8_array_permutes_inclusive_
        // range_panic_message_names_the_helper_and_arity_mismatch_
        // axis` on the (single-array) corner — both bind the
        // (helper, failed-axis) provenance pair.
        let outcome = std::panic::catch_unwind(|| {
            assert_scalar_plus_two_u8_arrays_permute_inclusive_range::<2, 3, 0, 6>(
                1u8,
                &[0u8, 2u8],
                &[3u8, 4u8, 5u8],
            );
        });
        let payload = outcome.expect_err(
            "assert_scalar_plus_two_u8_arrays_permute_inclusive_range \
             must panic on an arity-cardinality mismatch",
        );
        let msg = payload
            .downcast_ref::<&'static str>()
            .map(|s| (*s).to_owned())
            .or_else(|| payload.downcast_ref::<String>().cloned())
            .expect(
                "assert_scalar_plus_two_u8_arrays_permute_inclusive_range \
                 panic payload must be a static &str or String",
            );
        assert!(
            msg.contains("assert_scalar_plus_two_u8_arrays_permute_inclusive_range"),
            "assert_scalar_plus_two_u8_arrays_permute_inclusive_range \
             ARITY-MISMATCH panic message {msg:?} must name the helper \
             for provenance-preserving failure diagnostics",
        );
        assert!(
            msg.contains("ARITY-MISMATCH"),
            "assert_scalar_plus_two_u8_arrays_permute_inclusive_range \
             ARITY-MISMATCH panic message {msg:?} must name the failed \
             AXIS (\"ARITY-MISMATCH\") for axis-provenance-preserving \
             failure diagnostics",
        );
    }

    // ── node_count: structural size on the outer Sexp algebra ──────────

    #[test]
    fn node_count_nil_is_one() {
        // The residual-axis unit-payload arm contributes exactly one
        // node — the outer arm itself. Base case of the recursion.
        assert_eq!(Sexp::Nil.node_count(), 1);
    }

    #[test]
    fn node_count_atom_is_one_for_every_atom_kind() {
        // Every atomic arm — Symbol, Keyword, Str, Int, Float, Bool —
        // is a leaf on the AST algebra. The payload's own length
        // (a string with 100 chars, an integer with a large value)
        // does not contribute; the projection counts NODES on the
        // typed algebra, not bytes on the payload.
        assert_eq!(Sexp::symbol("foo").node_count(), 1);
        assert_eq!(Sexp::keyword("k").node_count(), 1);
        assert_eq!(Sexp::string("hello world").node_count(), 1);
        assert_eq!(Sexp::int(42).node_count(), 1);
        assert_eq!(Sexp::float(1.5).node_count(), 1);
        assert_eq!(Sexp::boolean(true).node_count(), 1);
        assert_eq!(
            Sexp::symbol("a-symbol-with-a-very-long-name").node_count(),
            1
        );
    }

    #[test]
    fn node_count_empty_list_is_one() {
        // The residual-axis payload-bearing arm with an empty payload
        // contributes exactly one node — the outer arm itself, no
        // children to sum over. Sits at the boundary between the
        // `Sexp::Nil` unit arm (also one node) and every non-empty
        // list.
        assert_eq!(Sexp::List(vec![]).node_count(), 1);
    }

    #[test]
    fn node_count_flat_list_is_one_plus_child_count() {
        // `(a b c)` — one outer List arm plus three Atom children,
        // each contributing one node. Load-bearing arithmetic
        // identity: `list(items).node_count() == 1 +
        // sum(item.node_count())` with atom children.
        let form = Sexp::list([Sexp::symbol("a"), Sexp::symbol("b"), Sexp::symbol("c")]);
        assert_eq!(form.node_count(), 4);
    }

    #[test]
    fn node_count_nested_list_sums_recursively() {
        // `(a (b c) d)` — one outer, plus a=1, plus inner (b c)=3,
        // plus d=1. Total 6. Pins the recursive sum over the tree.
        let form = Sexp::list([
            Sexp::symbol("a"),
            Sexp::list([Sexp::symbol("b"), Sexp::symbol("c")]),
            Sexp::symbol("d"),
        ]);
        assert_eq!(form.node_count(), 6);
    }

    #[test]
    fn node_count_each_quote_family_wrapper_adds_one_plus_inner() {
        // The four homoiconic wrappers each contribute one node for
        // the wrapper arm plus the node count of the wrapped inner.
        // `'x` = 2 (Quote wrapper + Atom x).
        // `` `x `` = 2. `,x` = 2. `,@x` = 2.
        let x = Sexp::symbol("x");
        assert_eq!(Sexp::Quote(Box::new(x.clone())).node_count(), 2);
        assert_eq!(Sexp::Quasiquote(Box::new(x.clone())).node_count(), 2);
        assert_eq!(Sexp::Unquote(Box::new(x.clone())).node_count(), 2);
        assert_eq!(Sexp::UnquoteSplice(Box::new(x.clone())).node_count(), 2);
        // Nested inner: `'(a b)` = Quote wrapper (1) + inner (a b)
        // list (3) = 4. Pins the recursion through wrappers.
        let inner = Sexp::list([Sexp::symbol("a"), Sexp::symbol("b")]);
        assert_eq!(Sexp::Quote(Box::new(inner)).node_count(), 4);
    }

    #[test]
    fn node_count_is_monotone_under_list_growth() {
        // Adding a strictly-larger subtree to a list strictly grows
        // the node count. LOAD-BEARING monotonicity pin — a resource
        // ceiling keyed on `node_count` relies on this identity so
        // that a strictly-larger expansion is bounded by a strictly-
        // larger count. A regression that ever ignored a child's
        // contribution (a bug that hardcoded arm-only counting)
        // fails this pin because the added subtree's own children
        // would silently drop out.
        let small = Sexp::list([Sexp::symbol("a")]);
        let large = Sexp::list([
            Sexp::symbol("a"),
            Sexp::list([Sexp::symbol("b"), Sexp::symbol("c")]),
        ]);
        assert!(large.node_count() > small.node_count());
        assert_eq!(small.node_count(), 2);
        assert_eq!(large.node_count(), 5);
    }
}