core/docs/decisions/ADR-0131.G.3.1-numerics-extensions.md

ADR-0131.G.3.1 — Numerics extensions (fractions + multi-currency + multi-token cardinals + word-num-adjective)

Status: Proposed Date: 2026-05-23 Author: CORE main agent (Sonnet 4.6) Depends on: ADR-0131.G.3 (parent, PR #183), ADR-0127 (units pack), ADR-0128 (numerics pack) Parent: ADR-0131 (composite math-expert promotion gate) Foundation for: ADR-0131.G.3.2 (£ / pound sterling follow-up)

---

Context

ADR-0131.G.3 (PR #183) shipped the first literal-recognition axis: money symbols ($N / $N.NN), money word forms (N dollars / N cents), and hyphenated multi-word cardinals (twenty-five). The four shapes explicitly deferred in G.3's "Out-of-scope" section form this iteration's closed-set scope:

1. Fractions end-to-end — N/M of a <unit> initial possession.
2. Multi-currency — ¢ € ¥ ₱ symbols (£ deferred; see below).
3. Multi-token space-separated cardinals — one hundred, two thousand five hundred.
4. Word-number-adjective compositions — five full boxes per ADR-0127 substance-qualifier precedent.

All canonical-unit architectural decisions from G.3 are preserved unchanged: cent is the canonical unit for money (US dollar path), pack-driven not regex-spam, refusal-first.

---

Decision

Axis 1 — Fractions end-to-end

_resolve_value in math_candidate_parser.py already handles N/M (returns _ResolvedValue(num / den, None)). The pipeline-level gap was in _INITIAL_HAS_RE's substance-qualifier handling: Bob has 3/4 of a cup. would match the main regex with unit=None (the of a cup phrase was consumed by the discardable substance qualifier), causing the candidate to not emit because no unit could be determined.

Fix: new dedicated regex _INITIAL_FRACTION_OF_RE with shape <Entity> has <N/M> of [a/an] <unit> [of <substance>]?. This explicitly extracts the unit from the of phrase when the value is a slash fraction, emitting a CandidateInitial with value=N/M and unit=<canonicalized>. The main _INITIAL_HAS_RE is unchanged; the new extractor fires in extract_initial_candidates after the primary extractor.

Closed-set: digit/digit literal with M > 0. Division-by-zero refused at _resolve_value time (already the case since G.3).

Axis 2 — Multi-currency

All five pack-recognized foreign currency symbols are in en_units_v1: ¢ (cent), € (euro), £ (pound sterling), ¥ (yen), ₱ (peso).

Wired in this iteration: ¢, €, ¥, ₱.

Deferred to G.3.2: £ / pound sterling. The en_units_v1 pack correctly models pound sterling as a two-word unit ("plural": "pounds sterling"). However, the question extractor (_Q_ENTITY_RE, _Q_TOTAL_RE) uses (?P<unit>\w+) which only captures a single word token. A question like How many pounds sterling does Alice have? fails to parse the unit slot (sterling is a second word, not consumed by the single-token capture group). Widening the question extractor's unit slot to support multi-word units is a distinct architectural change that belongs in a dedicated PR (G.3.2) to keep the diff bounded and attributable.

The _resolve_value and _currency_symbols table includes £ → pounds sterling (so symbol parsing is complete); the question-extractor gap is the only blocker.

Normalization:

• ¢N → N cents (1:1; ¢ face value IS the canonical unit).
• €N / €N.NN → N / N.NN euros (factor=1; no sub-unit in pack).
• ¥N → N yen (integer-only; yen has no sub-unit in the pack or in common usage — decimal ¥ form refused).
• ₱N / ₱N.NN → N / N.NN pesos (factor=1).

3+ decimal places are refused for all currency symbols (closed-set boundary; same rule as $N.NNN).

_MONEY_SYMBOL regex widened to alternation over all six symbols.

_unit_grounds in math_roundtrip.py widened: each currency symbol grounds its respective canonical unit when the symbol appears in the raw source span (mirrors the existing $ / dollar grounding logic).

_money_unit_normalization extended: word-form entries for euro, euros, yen, peso, pesos pass through with factor=1.

Axis 3 — Multi-token space-separated cardinals

parse_compound_cardinal in language_packs/numerics_loader.py already handles "one hundred", "two thousand five hundred" etc. — it normalises hyphens to spaces then tokenises. The parser couldn't emit these in the value slot because _VALUE alternation uses a single-token pattern; a greedy multi-word sequence would span the unit-slot boundary.

Approach (a) chosen (separate extractor) over (b) (_VALUE widening):

• Widening _VALUE to greedily match cardinal-word sequences would require look-ahead to distinguish the last cardinal word from the first unit word (e.g. in one hundred boxes, "one hundred" is the value and "boxes" is the unit; greedy matching consumes all three). This unwinding requires either atomic groups (Python 3.11+) or a two-pass approach, both of which add complexity across every pattern that uses _VALUE.
• A dedicated extractor (_MULTI_WORD_CARDINAL_RE) handles the <Entity> has <WORD_CARDINAL+> [<adjective>?] <unit> shape precisely, leaves _VALUE unchanged for all other paths, and is auditable in isolation.

_MULTI_WORD_CARDINAL_RE is built from the WORD_NUMBERS table keys (same source as _WORD_NUM_OPTIONS in _VALUE), requiring at least two consecutive cardinal words before the unit slot. The value group is passed to parse_compound_cardinal for resolution. Provenance: the first cardinal word of the sequence is the matched_value_token (it grounds because it is literally in the source span).

Axis 4 — Word-number-adjective

five full boxes per ADR-0127 substance-qualifier precedent. The adjective (full, loose, empty, whole, broken, new, old, small, large, fresh, raw, flat) is inserted between the cardinal value and the unit head noun. It is treated as part of the unit phrase: discarded at parse time, not surfaced to the solver.

Implementation: an optional non-capturing group (?:\s+(?:full|loose|…))? is inserted between the (?P<value>…) slot and the (?P<unit>\w+)? slot in _INITIAL_HAS_RE. The same adjective list is also added to _MULTI_WORD_CARDINAL_RE's optional-adjective slot (axis 3 and axis 4 compose naturally).

The adjective list is a closed set identical to the one in _CONJ_OBJECT_RE (already ratified by G.4), keeping both shapes consistent.

Pre-existing G.4 type bugs fixed

ADR-0131.G.4's multi-clause extractors (_conj_subject_each_candidates, _conj_object_candidates, _embedded_quantifier_candidates, _build_conj_embedded_sum, _compare_multiplicative_candidates, _compare_nested_candidates) called _resolve_value(...) directly as a numeric operand (e.g. float(_resolve_value(x)), _resolve_value(n) * _resolve_value(m), Quantity(value=_resolve_value(x), ...)). Since _resolve_value returns _ResolvedValue | None (not a raw number), these sites raised TypeError at runtime when hit by the GSM8K coverage probe.

This is a minimal fix: each site is updated to unwrap .value from the _ResolvedValue result (or guard against None and return []/early exit). Semantics are identical — the value extracted is the same numeric payload; no new candidates are emitted or suppressed.

---

What changed in code

generate/math_candidate_parser.py

• _MONEY_SYMBOL widened to six-currency alternation.
• _CURRENCY_SYMBOLS constant: symbol → (unit_surface, factor) table.
• _resolve_currency: dispatcher for all currency symbol literals.
• _resolve_value: currency branch now delegates to _resolve_currency.
• _INITIAL_HAS_RE: optional adjective group inserted between value and unit slots.
• _INITIAL_FRACTION_OF_RE: new regex for N/M of [a/an] <unit>.
• _MULTI_WORD_CARDINAL_RE: new regex for <Entity> has <WORD_CARDINAL+> [adj?] <unit>.
• _fraction_of_candidates: extractor for axis 1.
• _multi_word_cardinal_candidates: extractor for axis 3.
• extract_initial_candidates: calls both new extractors (after primary, before G.4 extractors).
• _money_unit_normalization: extended for euro/yen/peso word forms.
• G.4 pre-existing type fixes: .value unwrap at six call sites.

generate/math_roundtrip.py

• _unit_grounds: widened for ¢, €, ¥, ₱ symbols (mirrors existing $ logic).
• _value_grounds: currency symbol prefix check widened from $-only to the full _CURRENCY_SYM_SET.

New files

• evals/math_capability_axes/G3_numerics/v1_1/cases.jsonl — 28 cases (5 per axis × 4 + 8 refusal probes).
• evals/math_capability_axes/G3_numerics/v1_1/runner.py — identical adapter pattern to v1; byte-equal report.json across runs.
• evals/math_capability_axes/G3_numerics/v1_1/report.json — committed run artifact.
• tests/test_adr_0131_G31_numerics_extensions.py — 42 tests.

---

Evidence

Axis lane (v1_1/runner.py)

axis:                  numerics_extensions
cases_total:           28
solved_correct:        20
solved_wrong:          0  (gate: must be 0)
refused_as_expected:   8
correct_rate_on_positive_cases: 100.0%
overall_pass:          True

Per-axis breakdown:

• Axis 1 (fractions): 5/5 solved_correct
• Axis 2 (multi-currency): 5/5 solved_correct (¢ € ¥ ₱; £ deferred)
• Axis 3 (multi-word cardinals): 5/5 solved_correct
• Axis 4 (word-num-adjective): 5/5 solved_correct
• Refusal probes: 8/8 refused (percentages ×2, sci-notation ×2, locale-separators ×2, 3-decimal-money ×2)

report.json byte-equal across two independent runs.

Test suite

42/42 pass in tests/test_adr_0131_G31_numerics_extensions.py (0.27s).

Parent v1 lane regression

20/20 + 6/6 = 26/26 — unchanged from PR #183 commit.

GSM8K coverage probe

admission_rate: 0/50 = 0.0%
admitted_wrong: 0  (safety rail intact)

No probe delta. Admission remains at 0/50 for the same structural reasons identified in G.3: most GSM8K refusals are verb-class or multi-clause failures (G.1 / G.4 axes), not literal-recognition gaps. Fractions and multi-word cardinals don't appear in the 50-case probe as the binding blocker. The safety rail (admitted_wrong == 0) is preserved.

---

Currencies deferred to G.3.2

£ / pound sterling: en_units_v1 is correctly populated; _resolve_value("£15") returns _ResolvedValue(15, "pounds sterling"). The blocker is the question extractor's single-token (?P<unit>\w+) group, which cannot parse "How many pounds sterling does Alice have?". Fixing this requires widening the question-extractor unit slot to support multi-word units — a distinct scoped change for G.3.2.

---

CLAUDE.md PR-checklist answers

• Capability/performance/security added: Extends the candidate-graph parser's literal-recognition to four deferred shape families from G.3. wrong == 0 on the axis lane proves no wrong answers were introduced.
• Invariant proving field remains valid: solved_wrong == 0 on the v1_1 axis lane; admitted_wrong == 0 on the GSM8K probe; no changes to algebra/, chat/, or core/.
• CLI/eval lane: PYTHONPATH=. python3 evals/math_capability_axes/G3_numerics/v1_1/runner.py and pytest tests/test_adr_0131_G31_numerics_extensions.py.
• Avoided hidden normalization/stochastic fallback/approximate recall/unreviewed mutation: Yes. All lookups are deterministic and pack-driven. Currency normalization is a fixed table. No solver or binding-graph changes.
• Trust boundary: User-controlled text → parser regex; all new regex patterns are closed alternations with no catastrophic-backtracking risk. Pack file paths use the existing safe_pack_id sanitiser (ADR-0051).