core/docs/decisions/ADR-0024-inner-loop-admissibility.md

# ADR-0024 — Inner-Loop Per-Rotor Admissibility

| Field        | Value          |
|--------------|----------------|
| Status       | **Accepted**   |
| Date         | 2026-05-17     |
| Supersedes   | —              |
| Extends      | ADR-0022, ADR-0023 |
| Decision lead| Shay (with CORE assistant) |

---

## Context

ADR-0022 introduced `AdmissibilityRegion` and routed it through
`generate()` as a **boundary prefilter**: the region's
`allowed_indices` array is intersected with the language / salience
candidate set before `_nearest_next` runs, and an empty intersection
raises `ValueError` (honest refusal).  ADR-0023 then added
per-transition trace evidence: each step records `candidates_before /
candidates_after / selected_index / verdict`, hashed into the
deterministic trace.

That is enough to make the *token-set* side of admissibility
load-bearing.  It does not yet make the *blade-direction* side
load-bearing: `check_transition` is evaluated after selection and
recorded into the verdict, but the verdict does not influence which
candidate is chosen.  Today, a candidate that survives the index
prefilter is *always* selected even if its versor's CGA inner product
against `relation_blade` is negative — the trace says "rejected" and
the walk emits it anyway.

ADR-0023 §Decision explicitly deferred this:

> ADR-0024 will separately scope inner-loop admissibility (per-rotor
> admissibility checks after candidate prefilter) because that *is* a
> semantic change and interacts with the `versor_condition`
> invariant.

This ADR scopes that change.

## Decision

We add **inner-loop per-rotor admissibility** to `generate()`,
flag-gated and off by default.

When `inner_loop_admissibility=True` and a non-unconstrained region
is supplied:

1. `_nearest_next` selects a destination from the index-filtered
   candidate set, exactly as today.
2. `check_transition(region, candidate_index, candidate_versor,
   threshold=admissibility_threshold)` evaluates the candidate.
3. If `verdict.admitted` is `False`, the candidate is appended to a
   step-local `rejected_attempts` list, its index is added to a
   per-step exclude set, and `_nearest_next` re-runs with that
   exclusion.  The retry budget is bounded by
   `len(candidate_indices)`.
4. If every admissible candidate is rejected (selector returns an
   already-excluded index, or the retry budget is exhausted), the
   walk raises `ValueError(f"AdmissibilityRegion[{label}] inner-loop
   rejected all candidates at step {step_index}.")` — the same
   honest-refusal shape ADR-0022 §2 already commits to for empty
   admissible sets.
5. The selected (admitted) candidate proceeds through the existing
   rotor application: `V = word_transition_rotor(A, B)` and
   `propagate_step(current, V)`.  No new normalization site is
   introduced; the runtime versor invariant
   `versor_condition(F) < 1e-6` is still asserted after propagation
   exactly as before.

The rejected candidates are recorded in the trace via a new
`AdmissibilityTraceStep.rejected_attempts: tuple[tuple[int, str,
float], ...]` field.  The canonical form folds this field into the
trace hash only when non-empty, so any ADR-0023 turn (boundary-only
walk, or inner-loop on but no rejections) hashes to the same bytes it
hashed to before this ADR shipped.

Default is `False`.  Legacy call sites (`chat/runtime.py`,
`generate/proposition.py`, the ADR-0023 ablation lane) keep their
boundary-only semantics until they opt in.

## Why flag-gated

This is a real semantics change to the walk: it can divert selection
from the geometric nearest to a non-nearest admitted candidate.  That
is exactly what ADR-0022 promised the admissibility region would do
for the *direction* side of admissibility, but it changes the
distribution of emitted tokens for every constrained turn that hits
a rejection.  Flag-gating means:

* every commit before this ADR's eval lanes light up
  `inner_loop_admissibility=True` continues to produce byte-identical
  trace hashes;
* the change can be ramped per-call-site rather than as a global
  semantics flip;
* failures attributable to the inner loop are isolated by toggling
  the flag, not by reverting code.

## Invariants preserved

* **Versor condition.**  The rotor `V` is constructed from
  `vocab.get_versor_at(word_idx)` for the *admitted* candidate; the
  rejected candidates never reach `word_transition_rotor`.  The
  `versor_condition < 1e-6` assertion at `propagate_step` is
  unaffected.  CLAUDE.md §Non-Negotiable Field Invariant: not
  weakened.
* **No new normalization site.**  The inner loop is a selection-side
  retry; it never rebalances `F`, projects grades, or unitizes
  rotors.  CLAUDE.md §Normalization Rules: respected (no addition to
  the forbidden list).
* **Exact CGA recall.**  Vault recall and `cga_inner` are unchanged.
  CLAUDE.md §Core Primitives: not touched.
* **Honest refusal.**  Exhaustion raises `ValueError` with the region
  label in the message, the same surface ADR-0022 already commits to
  for empty admissible sets.

## Trust boundary

No new I/O.  No new dynamic imports.  No new filesystem reads.  The
`rejected_attempts` tuple is built from already-grounded vocabulary
indices and scores produced by `cga_inner`, both of which the existing
trust-boundary review (ADR-0022 §Trust Boundary) covers.  No
user-controlled text enters the trace path.

## Acceptance evidence

* **Backward-compat trace hash.**  `compute_trace_hash` over an
  ADR-0023 turn (no rejected attempts) produces the same bytes
  before and after this ADR.  Covered by
  `tests/test_admissibility_trace.py::TestComputeTraceHashBackwardCompat`
  and by a new `tests/test_inner_loop_admissibility.py` case asserting
  that an empty `rejected_attempts` list canonicalizes without the
  key.
* **Re-selection on rejection.**  A new test constructs a small
  vocabulary where the geometric-nearest candidate would be rejected
  by a region whose blade points away from it; with
  `inner_loop_admissibility=True` and a positive threshold, the walk
  emits a *different* admitted token and the step's
  `rejected_attempts` records the rejected one.
* **Exhaustion → honest refusal.**  A region whose blade rejects
  every admissible candidate raises `ValueError` with the region label
  embedded in the message.
* **Default off preserves behavior.**  With the flag off, every
  existing pipeline / runtime / eval lane test continues to pass byte-
  for-byte; no test in `tests/` had to be updated to absorb this
  change.

## Out of scope

* **Pipeline / runtime wiring.**  This ADR only adds the parameter on
  `generate()`.  Wiring the flag through `RuntimeConfig`,
  `CognitiveTurnPipeline`, and `chat/runtime.py` is left to a follow-
  up so the eval lane can demonstrate causal isolation against the
  inner loop without touching production defaults.
* **Frame-versor admissibility.**  ADR-0022's `frame_versor` /
  `rotor_constraint` side of the region remains observed but unused
  for selection.  That belongs in a future ADR after this one's trace
  evidence shows whether blade-direction admissibility alone closes
  the remaining causality gap.
* **Adaptive thresholds.**  The threshold is a static parameter.
  Adaptive thresholds (learned, frame-derived, or annealed) are a
  separate semantic change.

## Risks

* **Selection drift.**  A non-zero `admissibility_threshold` will
  divert tokens.  Mitigation: default `0.0` matches the ADR-0023
  verdict computation; lanes ramp the threshold independently per
  case.
* **Cost.**  Up to `len(candidate_indices)` extra `check_transition`
  calls per step in the worst case.  In practice the admissible set
  is small (chain length) and rejections terminate after the first
  admitted candidate.
* **Test brittleness.**  Tests that asserted exact tokens on
  constrained walks could shift if they enable the flag.  Mitigation:
  flag stays off everywhere by default; opt-in is explicit per call
  site.

## Rollback

Set `inner_loop_admissibility=False` (the default) at every call
site.  The trace hash remains byte-identical to ADR-0023, so
deterministic replay over the existing corpus is unaffected.