core/docs/adr/ADR-0249-reader-hamiltonian-compiler-composition-frontier.md

ADR-0249: Reader→Hamiltonian Compiler — the Composition Frontier

Status: Proposed Date: 2026-07-18 Authors: Joshua Shay + multi-model R&D (implemented Fable 5) Depends on: ADR-0243 (cognitive lifecycle — relax_to_ground, ProblemHamiltonian), ADR-0244/0245 (content-addressing, f64 relaxation, _cached_eigh), ADR-0217 (R2 finite-integer constraint compiler — front-end precedent), ADR-0175/0191–0193 (calibrated-learning / composition-wall doctrine) Design record: docs/research/reader-hamiltonian-compiler-spike-2026-07-18.md Acceptance evidence: docs/handoff/ADR-0249-Acceptance-Evidence.md

---

1. What this ADR is — and the thesis

The generalized-lift instrument (ADR-0246 seam S4) recorded a single blocking scope limitation: no reader→Hamiltonian compiler existed beyond ≤5-atom propositional problems and quadratic wells, so real problems (GSM8K arithmetic, NL deduction) could not be ingested by the corridor at all. This ADR builds that compiler and nothing more — it does not touch serving, does not activate any gate, and does not claim the corridor now beats symbolic solvers.

Thesis — composition = certified turn sequences. The corridor's native space is 32-dimensional (the Cl(4,1) blade basis; _MAX_ATOMS = 5 is exactly 2⁵ = 32, structural not incidental). A problem is therefore not compiled into one large Hamiltonian. It is compiled into a turn program — an ordered sequence of small relation-wells, each solved in one certified relaxation turn, with the working state flowing turn-to-turn on the field. Composition depth lives in the certified chain, not in matrix size. This is the "wall is COMPOSITION" lesson (ADR-0193) finally getting its mechanism.

2. Components (five phases, each merged under its own PR)

Phase	Module	What it does
P1	core/physics/quantity_kernel.py	Quantities as null points on the Cl(4,1) conformal line; add/scale by constants as translator/dilator versor sandwiches; projective scale-invariant decode.
P2	core/physics/relation_compiler.py	output = scale·input + offset → quadratic-well ProblemHamiltonian via versor transport (reuses compile_quadratic_well).
P3	evals/logic_cnf_compiler.py	Structural formula→CNF (reuses logic_canonical parser; eliminate iff/implies → NNF → distribute) → PropositionalProblem + query Clause.
P4	evals/turn_program.py	MathProblemGraph → ordered turn program; chained-relaxation executor; content-addressed tamper-evident turn ledger.
P5	evals/generalized_lift_instrument.py	arithmetic-chain domain: corridor vs symbolic fold on the real GSM8K dev holdout; honest coverage recorded.

3. Anti-hollow discipline (load-bearing)

The compiler must never evaluate the arithmetic or logic it encodes — else the corridor confirms a precomputed answer rather than solving, and the instrument is hollow. Enforcement:

• The relation/turn compilers apply the problem's structure as versor operators (dilator for scale, translator for offset); the substrate's geometric product performs the arithmetic. No Python scale·input+offset.
• Compiled wells are bare projectors — metadata {curvature, target_digest} only; they carry no answer and no coefficients.
• In a turn chain the accumulator flows as a field state and is decoded exactly once, at the end; intermediate values are never decoded to drive the next turn.
• Ablation pins confirm the answer is produced by relaxation (the start state decodes to the input, only the relaxed state to the answer, with byte-identical Hamiltonians).

4. The Ring-2 correction (verified in-tree)

The design spike proposed "chain turns through the Ring-2 residual protocol." Grounding against the code corrected this: run_residual_protocol (core/ports/residual_protocol.py:222) is zero-bound / non-mutating — its stage-5 recertification re-witnesses the subject and raises recertification_witness_changed if it moved. Arithmetic turns mutate. The protocol therefore certifies a fixed state's admissibility, not a state transition, and cannot be the vehicle for the mutating turn.

Resolution (no hollow integration): the per-turn certificate is the relaxation's own RelaxationCertificate; the tamper-evident sequence is recorded with the Ring-2 chain-integrity pattern — a content-addressed TurnRecord, GENESIS_DIGEST-linked, with verify_turn_chain mirroring verify_replay_chain.

5. Reproducibility — three tiers, honestly bounded (spike §4.6)

• Tier 1 (content address): solved. SHA-256 over explicit <f8 LE bytes.
• Tier 2 (matrix construction): enforced. geometric_product is a fixed-order scatter-add (no BLAS/reduction) ⇒ IEEE-754 hardware-deterministic; it silently truncates to f32 unless handed f64, so every construction is explicit f64 and pinned with golden-bytes canaries.
• Tier 3 (eigensolve): bounded, not overclaimed. The affine well H = c(Id − ψψᵀ) has a 31-fold-degenerate excited eigenspace whose LAPACK basis is build-dependent; propagator bytes are not cross-hardware identical. Mitigation: the ground state is analytic (the target is constructed), so the basis-invariant phase_correlation/2 agreement is pinned, never the bytes.

6. Tier-1 scope + recorded frontier

Tier-1 is the affine single-accumulator envelope: add / subtract / multiply / divide with constant Quantity operands and positive scale; propositional deduction over ≤5 atoms. Everything else — multi-entity, transfer, rate, comparison, fraction, partition, non-positive scale, >5-atom deduction, unknown× unknown — is refused with a typed error and recorded, never silently dropped (no-silent-caps). >5-atom deduction via ROBDD-partitioned turn programs is the next arc, not this one (a sequencing choice, not an impossibility).

7. Honest measurement (the done-when)

On the sealed real GSM8K dev holdout (50 cases): 26 are Tier-1 ingestible and solved wrong=0; the corridor matches the symbolic fold on every one (PARITY, delta = 0 — the field matches arithmetic, it does not beat it); the 24 refused are all multi-entity, the recorded Tier-2 frontier. This is the honest-NULL protocol working as designed: the deliverable is a decidable measurement and recorded real-data coverage, not an inflated lift claim. The recognition domain's genuine +9 lift stands separately; arithmetic is honestly PARITY.

8. Governance

Off-serving (A-04): every module lives in core/physics/ or evals/ and is never imported by chat/runtime.py. No gate is activated; no manifold is mutated (I-03). Reuses ratified contracts (compile_quadratic_well, HamiltonianCompileError, logic_canonical, the Ring-2 chain pattern) rather than forking them. Local-first CI: smoke green in-worktree at every phase.

9. What this ADR does NOT claim (honest register)

• Not a serving change; the symbolic generate/ path remains the serve path.
• Not a lift over symbolic solvers on arithmetic (PARITY is the honest result).
• Not full GSM8K coverage — 52% of the dev holdout is Tier-1; the rest is the recorded frontier.
• Not an activation of any admission gate (ADR-0246 §3.7 stays uncalibrated).

10. Ruling record (§8 — Shay)

Awaiting ratification. The four design rulings (affine-only Tier-1; >5-atom deduction deferred; single ADR; field wedge independent) are recorded RESOLVED in the spike; acceptance of this ADR is Shay's alone (no self-Accept).