core/docs/decisions/ADR-0123-parser-comparison-phrasing.md

ADR-0123 — Comparison-Phrasing Realizer (surface increment on the ADR-0123 substrate)

Status: Accepted (surface increment; substrate landed in PR #155) Date: 2026-05-23 Author: CORE agents + reviewers Depends on:

• ADR-0115 (parser substrate),
• ADR-0116 (deterministic solver),
• ADR-0117 (SolutionTrace verifier),
• ADR-0118 (stepped realizer),
• ADR-0119 (+ all 8 sub-phases),
• ADR-0121 (math expert promotion deferred),
• the ADR-0123 substrate commit (feat/adr-0123-substrate, commit c9bd5d4): Comparison dataclass + compare_additive / compare_multiplicative operation kinds + parser patterns + solver / verifier wiring + en_arithmetic_v1:compare_additive (en-arith-006) + en_arithmetic_v1:compare_multiplicative (en-arith-007) pack lemmas. Supersedes: none

Disambiguation: this is ADR-0123-parser-comparison-phrasing, the parser-arc ADR. It is distinct from ADR-0123-symbolic-logic-shape-remap.md (the lane-shape governance ADR that happens to share the number). The disambiguation pattern follows the same convention as the audit-passed / parser-rate split (e.g., ADR-0122-systems-software-audit-passed-deferred.md vs the parser-rate work pinned in a parallel PR). Two ADRs with the same number, distinct slugs, distinct subject-matter streams.

---

Context

ADR-0121 deferred the first expert promotion with named blocker correct_rate = 0/1319 on sealed GSM8K. ADR-0121 §"What would unlock the promotion" enumerates a parser-expansion arc of 4–8 construction classes. Comparison phrasing is the second class in that arc (the first was rate / per-unit, currently in flight as a parallel parser-rate ADR; the two are non-blocking siblings).

PR #155 (feat/adr-0123-substrate, commit c9bd5d4) shipped the substrate — the typed graph operand (Comparison), the two new operation kinds (compare_additive, compare_multiplicative), the parser patterns for the four canonical English surfaces (N more / N fewer / twice / N times / half), the solver handlers, the verifier replay-equality extensions, and the two pack lemmas. What the substrate did not ship — by deliberate scope discipline mirroring ADR-0119's sub-phase decomposition — is the surface realization of comparison steps in generate/math_realizer.py. Without realizer phrasing, a problem that solves successfully under the new operation kinds still raises RealizerError("unknown operation_kind 'compare_additive'") when the stepped explanation is requested.

This ADR closes that one-line architectural gap: the surface sentence templates for the four comparison shapes, wired into _step_sentence so the full parse_problem → solve → verify → realize pipeline operates on comparison problems end-to-end.

---

Decision

Extend generate/math_realizer.py with two helper functions (_compare_additive_sentence, _compare_multiplicative_sentence) plus a dispatch branch in _step_sentence that consumes the new operation kinds. The signature of _step_sentence widens by one optional parameter (entity_units) carrying a {entity_name: unit} mapping derived once-per-trace from graph_initial_state in realize(). This is the load-bearing plumbing change: the multiplicative comparison helper needs the reference actor's unit at render time, and the substrate deliberately does not carry that on Comparison itself when factor is set (the substrate's solver derives it from in-flight state, which the realizer cannot reach without re-running the solver).

Realizer-level additions (generate/math_realizer.py)

1. _compare_additive_sentence(step: SolutionStep) -> str — renders an additive-comparison step as one of two templates, selected by step.operand.direction:

   direction='more':
     "<actor> has <delta.value> more <delta.unit> than <ref>,
      giving <actor> a total of <after> <delta.unit>."
   
   direction='fewer':
     "<actor> has <delta.value> fewer <delta.unit> than <ref>,
      leaving <actor> with a total of <after> <delta.unit>."
   

   The two-clause shape — comparison clause + resolved-state clause — is pinned as a structural invariant. delta.value and after_value pluralize independently via the existing _unit_surface helper, so "1 more apple" and the resolved state "3 apples" coexist without forcing one count's plurality onto the other.

2. _compare_multiplicative_sentence(step: SolutionStep, entity_units: dict[str, str]) -> str — renders a multiplicative comparison step as one of three templates, selected by step.operand.direction and factor:

   direction='times':
     "<actor> has <factor> times as many <unit> as <ref>,
      giving <actor> a total of <after> <unit>."
   
   direction='fraction' (factor == 0.5):
     "<actor> has half as many <unit> as <ref>,
      giving <actor> a total of <after> <unit>."
   
   direction='fraction' (other factor):
     "<actor> has <factor> as many <unit> as <ref>,
      giving <actor> a total of <after> <unit>."
   

   unit is resolved via entity_units[reference_actor] — the initial-state lookup is sufficient because the substrate's solver refuses multi-unit reference actors (SolveError("…is ambiguous: reference actor … holds quantities in multiple units…")) and refuses to overwrite a comparison actor's existing state. Both refusals guarantee that the reference's initial unit and the comparison-time unit are the same string.

3. _step_sentence dispatch widened with two prepended branches:

   if step.operation_kind == "compare_additive":
       return _compare_additive_sentence(step)
   if step.operation_kind == "compare_multiplicative":
       if entity_units is None:
           raise RealizerError(...)
       return _compare_multiplicative_sentence(step, entity_units)
   

   The pre-existing add / subtract / transfer / multiply / divide branches are unchanged, byte-identically. The new branches sit at the top because the substrate's solver already refuses ambiguous comparisons; the realizer's job is to render what survived solver refusal, not to re-validate.

4. realize() builds entity_units once from graph_initial_state:

   entity_units = {p.entity: p.quantity.unit for p in graph_initial_state}
   

   and threads it through to every _step_sentence call. The add/subtract/transfer/multiply/divide branches accept the parameter and ignore it (default None), preserving the existing behavior on pre-comparison traces.

Refusal discipline (load-bearing)

The helpers raise RealizerError on every shape the substrate already refuses plus one shape the substrate cannot see:

Refusal	Substrate or Realizer
operand not a Comparison	realizer (defensive — substrate guarantees this via Operation.__post_init__)
delta is None in additive branch (multiplicative shape leaked)	realizer
factor is None in multiplicative branch (additive shape leaked)	realizer
direction not in {'more','fewer'} for additive	realizer
direction not in {'times','fraction'} for multiplicative	realizer
actor == reference_actor (self-comparison)	both (substrate at parse time; realizer at render time as defense in depth)
reference_actor not in entity_units	realizer (multiplicative only — substrate guarantees this for parsed problems but does not for hand-constructed graphs)

ADR-0114a Obligation #4 (wrong == 0) holds by construction — the new branches only fire when the substrate has already emitted a successful step; if the substrate refused, no step exists to render.

What this ADR does NOT touch

• generate/math_problem_graph.py — Comparison is already shipped by the substrate; not modified.
• generate/math_parser.py — _try_comparison_declaration is already shipped by the substrate; not modified.
• generate/math_solver.py — _apply_compare_additive / _apply_compare_multiplicative are already shipped; not modified.
• generate/math_verifier.py — comparison-step verification is already shipped; not modified.
• language_packs/data/en_arithmetic_v1/* — en-arith-006 (compare_additive) and en-arith-007 (compare_multiplicative) are already shipped at manifest version 1.1.0; this ADR adds no further pack vocabulary.

The scope discipline matches ADR-0119's sub-phase decomposition exactly: substrate ships first (PR #155), surface ships second (this PR), each with its own re-measurable invariants.

---

Anti-overfit re-measurement (load-bearing — per ADR-0121)

This ADR ships only when every measurement below holds.

1. Sealed-GSM8K correct_rate + wrong count

Run evals/gsm8k_math/runner.py against the decrypted sealed holdout (1319 cases). Pass condition: wrong == 0 (the absolute discipline). The correct_rate > 0.0 lift gate is deferred — the substrate ADR pre-measured zero sealed lift (every comparison-matching sealed case also requires aggregation / rate / conditional structure not yet in the parser), and the realizer surface cannot create matches the parser refuses.

2. ADR-0118a OOD re-measurement

Run the OOD perturbation suite (evals/gsm8k_parser_dev/ood_score.py). Pass condition: OOD/public ratio remains ≥ 0.95. Adding two realizer branches and threading one extra parameter must not move this number.

3. ADR-0125 perturbation re-measurement

Run the invariance perturbation suite. Pass condition: invariance-preserving rate = 1.0; invariance-breaking rate = 1.0.

4. ADR-0119.5 adversarial re-measurement

Run evals/gsm8k_math/adversarial/. Pass condition: wrong == 0 across all 38 cases × 12 families.

5. ADR-0119.7 sealed-seal integrity

The sealed holdout cases.jsonl.age file is not modified. SHA-256 digest unchanged.

6. ADR-0117 replay-equality

Runner remains deterministic — same case set → byte-equal LaneReport.canonical_bytes(). The realizer change extends to new step kinds but does not modify the existing kinds' rendering, so prior traces re-render byte-identically.

7. Substrate measurement preservation

Every invariant the substrate ADR pinned (parser, solver, verifier, pack-binding) continues to hold byte-identically. The substrate's test suite re-runs cleanly under this PR.

8. ADR-0118 stepped-realizer preservation

The pre-existing add/subtract/transfer/multiply/divide step sentences re-render byte-identically. ADR-0118's pinning of those templates is not weakened.

---

Invariants

adr_0123_realize_compare_additive_more_canonical

parse_problem("Alice has 5 apples. Bob has 3 more apples than Alice. How many apples does Bob have?") → solve() → realize() produces prose containing all of:

• "3 more apples than Alice"
• "Bob a total of 8 apples"
• the final "Bob has 8 apples." answer sentence.

adr_0123_realize_compare_additive_fewer_canonical

"Anna has 10 flowers. Mary has 5 fewer flowers than Anna. How many flowers does Mary have?" → prose containing:

• "5 fewer flowers than Anna"
• "Mary with a total of 5 flowers"

adr_0123_realize_compare_multiplicative_twice_canonical

"Carla has 7 marbles. Ben has twice as many marbles as Carla. How many marbles does Ben have?" → prose containing:

• "2 times as many marbles as Carla"
• "Ben a total of 14 marbles"

adr_0123_realize_compare_multiplicative_n_times_canonical

"Tom has 3 cookies. Sara has 4 times as many cookies as Tom. How many cookies does Sara have?" → prose containing:

• "4 times as many cookies as Tom"
• "Sara a total of 12 cookies"

adr_0123_realize_compare_fraction_half_canonical

"Tom has 8 cookies. Lisa has half as many cookies as Tom. How many cookies does Lisa have?" → prose containing:

• "half as many cookies as Tom" (the literal word "half", not "0.5 as many")
• "Lisa a total of 4 cookies"

adr_0123_realize_byte_deterministic

Two realize() calls on the same (graph_initial_state, trace) produce byte-equal RealizedTrace.canonical_bytes(). Pinned for both additive and multiplicative cases.

adr_0123_realize_singular_plural_independence

A compare_additive step with delta.value=1 and after_value=5 renders "1 more apple" (singular delta clause) and "5 apples" (plural resolved state). Symmetric: delta.value=3 and after_value=1 renders "3 more apples" and "1 apple".

adr_0123_realize_refuses_non_comparison_operand

A hand-constructed SolutionStep with operation_kind="compare_additive" but operand=Quantity(...) raises RealizerError("requires a Comparison operand").

adr_0123_realize_refuses_missing_delta

A Comparison(direction='more', delta=None, factor=2.0) operand on a compare_additive step raises RealizerError matching /requires Comparison.delta/.

adr_0123_realize_refuses_missing_factor

A Comparison(direction='times', delta=Quantity(3,'a'), factor=None) operand on a compare_multiplicative step raises RealizerError matching /requires Comparison.factor/.

adr_0123_realize_refuses_missing_entity_units

_compare_multiplicative_sentence(step, entity_units={}) for a reference actor not in the map raises RealizerError matching /initial state/. This catches hand-constructed graph traces that omit the reference actor from initial state.

adr_0123_realize_pre_comparison_traces_byte_identical

A trace containing only add/subtract/transfer/multiply/divide steps renders byte-identically to its pre-this-PR rendering on the substrate branch. The realizer change does not modify the prior templates.

adr_0123_sealed_correct_rate_zero_at_landing

run_lane(sealed_cases).metrics["correct_rate"] == 0.0 at the time of landing. Inherits the substrate ADR's deferral mechanic: the multi-construction barrier (every sealed comparison-matching case combines with at least one other class not yet in the parser) holds at the surface layer too — comparison alone matches zero sealed cases. The test fails (correctly) only when a future composition ADR finally lifts the number above 0.

adr_0123_sealed_wrong_zero_holds

run_lane(sealed_cases).metrics["wrong"] == 0. Inherits the substrate's wrong-zero discipline. The realizer cannot create new misparses; it only renders successful traces.

adr_0123_adr_0118_stepped_realizer_unchanged

ADR-0118's canonical realization tests pin the add/subtract/transfer surfaces. They continue to pass byte-identically.

---

Measurement (at landing)

Metric	Pre-ADR (substrate tip)	Post-ADR (this branch)	Gate	Pass?
parse_problem → solve → realize on 4 canonical comparison shapes	refuses at realize() with unknown operation_kind	all four render (more, fewer, twice/N times, half)	end-to-end pipeline	✓
sealed correct_rate	0.0 (0/1319)	0.0 (0/1319)	deferred (see Decision)	✓ (deferred)
sealed wrong	0	0	must remain 0	✓
public correct_rate	1.0 (150/150)	unchanged	≥ 0.95	✓
OOD/public ratio	1.00	unchanged	≥ 0.95	✓
perturbation invariance-preserving	1.0	unchanged	1.0	✓
perturbation invariance-breaking	1.0	unchanged	1.0	✓
adversarial wrong	0	0	0	✓
sealed seal SHA-256	(pinned by ADR-0119.7)	unchanged	byte-equal	✓
ADR-0118 stepped-realizer canonical surfaces	pinned templates	unchanged	byte-equal	✓

Honest finding: the realizer surface closes the last architectural gap in the comparison-phrasing class. A problem that the substrate's solver evaluates successfully now produces show-your-work prose — without this ADR, every successful comparison solve raises RealizerError at the explanation step. The lift gate stays at zero because the parser only recognizes the four canonical comparison surfaces in isolation, not in composition with rate / aggregation / unit conversion (the multi-construction barrier the substrate ADR documented).

---

Out of scope

• Composed rate × comparison constructions ("A watermelon costs three times what each pepper costs") — composition ADR.
• Comparative ratio phrasing beyond half ("X has 2/3 as many as Y", "X has 75% of Y") — percentage / fraction ADR (the third foundational class).
• Multi-step comparison chains ("A has 3 more than B; B has twice as many as C") — composition ADR.
• Comparative superlatives ("X has the most apples", "Y has more than anyone else") — out of arc.
• Negative-direction additive with non-positive delta — refused by substrate at construction time; realizer inherits.
• Round-trip equality between realized prose and re-parsed graph — deferred to a future ADR. The current realizer surfaces are human-readable; they are not yet a strict fixed point of the parse → realize → parse → realize loop. ADR-0118 holds this distinction for its own operation kinds; ADR-0123 inherits it.

---

What this proves (and what it doesn't)

Proves

• The full parse_problem → solve → verify → realize pipeline now operates end-to-end on the four canonical comparison surfaces (N more, N fewer, twice/N times, half). Before this ADR, the pipeline crashed at the last step.
• The wrong-zero discipline (ADR-0114a Obligation #4) holds against an expanded grammar surface. Adding two realizer branches did not introduce a single new misparse on any of the existing eval lanes.
• ADR-0118's pinned templates re-render byte-identically. The realizer change is purely additive at the dispatch layer.

Does NOT prove

• That comparison problems will eventually lift sealed correct_rate. They won't, in isolation — the multi- construction barrier documented in the substrate ADR and inherited here is the load-bearing reason. The cumulative lift signal arrives after the 3rd or 4th foundational class composes.
• That the chosen prose templates are the best templates for downstream consumers. They are deterministic, structurally invariant, and human-readable. If a future composition ADR finds them ambiguous (e.g., the parser misparses its own realizer output during round-trip), the templates get revised at that point.
• That the fraction direction with non-0.5 factors is well-tested. The substrate parser only emits factor=0.5 for fraction; the realizer's fall-through template ("<factor> as many ...") exists for future parser extensions but is not exercised by any parsed problem today.

---

Consequences

• The realizer covers all six operation kinds the substrate emits (add/subtract/transfer/multiply/divide/compare_*). ADR-0114a Obligation #5 (realizer coverage parity) holds across the full graph vocabulary.
• ADR-0121's deferral remains in place — surface-layer ADRs cannot move the sealed correct_rate gate because they only render what the parser+solver already produce.
• Substrate measurements continue to hold byte-identically. The realizer change is fully additive at the dispatch layer.
• The parser-expansion arc gains its second class fully end-to-end (substrate + surface). Per ADR-0121's revised sequencing, no lift signal is expected until at least the 3rd or 4th class lands. The next ADR is percentage / fraction.
• The substrate-then-surface decomposition pattern (PR #155 → this PR) is reusable for future parser-expansion classes. Substrate ADRs ship the typed graph operand + parser/solver/ verifier wiring; surface ADRs ship the realizer phrasing. Each measures independently.

---

Why this ADR is small on purpose

ADR-0114a's honest-fitting discipline rewards narrow expansions that each get fully re-measured across all anti-overfit lanes. The substrate ADR shipped 4,798 lines of new code (parser patterns + solver handlers + verifier extensions + pack lemmas

• tests for adjacent ADRs that were caught in the same merge); this ADR ships ~140 lines of realizer code and one ADR doc.

The substrate-then-surface split exists for two reasons:

1. Independent bisection. If a regression appears on OOD or perturbation, the bisection points at one of: (a) the substrate's parser/solver changes, or (b) this PR's realizer phrasing. Bundling them into one PR loses the bisection signal.
2. Independent reviewability. A reviewer who knows the parser/solver subsystem need not also be a realizer expert, and vice versa. Each PR has a tractable diff for a single reviewer to load into working memory.

This is the same load-bearing rule as ADR-0119's sub-phase decomposition and the substrate ADR's own scope discipline, applied one level finer.