docs(matcher-extension): dispatch pack (ME-1) (#399)
Follow-up to PR #398 — lights up the dormant consumption path by extending _match_rate_with_currency to publish composition_shape + pre-composed CandidateInitial in parsed_anchors. Scope: one matcher extension (_match_rate_with_currency) for the currency-per-unit composition shape ("$X each"). Other composition shapes (multi-quantity, additive, subtractive) deferred to ME-3/4/5 follow-ups. Subject binding decision pinned: Option A (refuse when same-sentence subject is absent). Forbids Option B (placeholder subject — fabricates attribution). Defers Option C (cross-sentence subject) to its own ME-2 brief. Honest consequence: case 0019 stays refused in THIS PR (requires Option C). Truth-test #1 replaced with a synthetic "Maria bought 3 vet appointments at $400 each" canary that has same-sentence subject. The flywheel turns one revolution: ratify → compile → load → consume → admit, end-to-end on the synthetic canary. Operator profile: Opus (load-bearing wrong=0; pre-composed CandidateInitial; case 0050 mandatory pin). Test surface enumerated (4 test files, 12+ tests): - test_matcher_extension_currency_per_unit (8 narrowness tests) - test_matcher_extension_case_0050_hazard_pin (mandatory) - test_matcher_extension_end_to_end_admission (truth test) - test_matcher_extension_train_sample_baseline_preserved - test_matcher_extension_public_split_preserved 6-row truth test pinned. Anti-regression invariants enumerated. Forbidden surface includes Option B + new SAFE category entries + solver mutation. Recommended next dispatch sequence: ME-1 → ME-2 (case 0019) → ME-3/4/5 (remaining composition shapes).
This commit is contained in:
Shay
GitHub
parent
78ddab79b4
commit
7a0b1ed931
1 changed files with 441 additions and 0 deletions
441
docs/handoff/MATCHER-EXTENSION-DISPATCH-PACK.md
Normal file
441
docs/handoff/MATCHER-EXTENSION-DISPATCH-PACK.md
Normal file
|
|
@ -0,0 +1,441 @@
|
|||
# Matcher Extension — Dispatch Pack (ME-1)
|
||||
|
||||
**Goal:** Light up the dormant consumption path in PR #398 by extending
|
||||
the recognizer matcher to publish `composition_shape` + a pre-composed
|
||||
`CandidateInitial` in `parsed_anchors`. With this PR, the math
|
||||
compounding loop's `ratify → admit` closure becomes operational for
|
||||
the `each`/`per`-framed cost composition shape — and case 0019
|
||||
admits.
|
||||
|
||||
**Parent briefs:**
|
||||
- `docs/handoff/COMPOSITION-FRAME-CONSUMPTION-WIRING-BRIEF.md` (PR #396)
|
||||
- `docs/handoff/CONSUMPTION-WIRING-DISPATCH-PACK.md` (PR #397)
|
||||
- PR #398 — the consumption-wiring implementation (merged into context)
|
||||
|
||||
**Parent ADRs:** ADR-0163 (recognizer registry), ADR-0167, ADR-0168 / 0168.1,
|
||||
ADR-0169 / 0169.1, ADR-0170 (injector contract widening), ADR-0172
|
||||
|
||||
**Type:** Implementation dispatch; not a doctrine ADR
|
||||
|
||||
---
|
||||
|
||||
## Why this brief exists
|
||||
|
||||
PR #398 shipped the consumption infrastructure (compile, loaders,
|
||||
manifest, injector consultation). All 38 new tests pass. But the
|
||||
truth-test rows #1 and #3 (case 0019 admits; train_sample 3/47 →
|
||||
≥4/46) **partial**: the wiring is positioned correctly but stays
|
||||
dormant because the existing matchers don't publish
|
||||
`composition_shape` in `parsed_anchors`.
|
||||
|
||||
PR #398 §"Scope Boundary" named this finding. This brief is the
|
||||
follow-up.
|
||||
|
||||
The matchers in `generate/recognizer_match.py`:
|
||||
|
||||
| Matcher | Currently | Needs to |
|
||||
|---|---|---|
|
||||
| `_match_rate_with_currency` | Extracts `(currency_symbol, amount, per_unit)` per anchor; **detection + extraction** | Detect the outer count in the same sentence; emit `composition_shape` + `composed_initial` when count is present |
|
||||
| `_match_currency_amount` | Detection-only (returns empty anchors); refuses if per-unit framing present | **Out of scope** — this matcher's discriminator deliberately rejects per-unit framing |
|
||||
| `_match_multiplicative_aggregation` | Detection-only; matches "M outer × N inner" shape | **Out of scope** (Phase B follow-up) — multiplicative_aggregation maps to a different solver shape than `currency_per_unit_rate` |
|
||||
|
||||
So the minimum-scope extension is **`_match_rate_with_currency`**.
|
||||
|
||||
---
|
||||
|
||||
## Bundling rule
|
||||
|
||||
**One PR.** Single matcher extension + injector wire for the
|
||||
per-unit-cost composition shape. Don't bundle multi-quantity_composition
|
||||
or additive_composition cases into this brief — those are separate
|
||||
matcher targets and each carries its own subject-binding risk.
|
||||
|
||||
Branch: `feat/matcher-extension-currency-per-unit-composition`
|
||||
|
||||
---
|
||||
|
||||
## Operator profile
|
||||
|
||||
**Opus** (load-bearing wrong=0 surface; the matcher extension produces
|
||||
a `CandidateInitial` whose value is the product of two recognized
|
||||
quantities — same hazard surface as CC-2, with case 0050 as mandatory
|
||||
pin).
|
||||
|
||||
---
|
||||
|
||||
## Dispatch
|
||||
|
||||
```bash
|
||||
git fetch origin main && \
|
||||
git worktree add /tmp/wt-matcher origin/main && \
|
||||
cd /tmp/wt-matcher && \
|
||||
git checkout -b feat/matcher-extension-currency-per-unit-composition
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Reads required FIRST
|
||||
|
||||
- `generate/recognizer_match.py`:
|
||||
- `_match_rate_with_currency` (lines 290–344) — the extension target
|
||||
- `RecognizerMatch` dataclass (line 139) — `parsed_anchors` is `tuple[Mapping[str, Any], ...]`
|
||||
- `generate/recognizer_anchor_inject.py`:
|
||||
- `inject_from_match` (lines 73–98) — already consults composition_registry on `composition_shape`
|
||||
- `_consult_composition_registry` (lines 100–170) — the contract: matcher must publish `composition_shape` + `composed_initial` OR `composed_operation`
|
||||
- `generate/comprehension/composition_registry.py` — `is_affirmed`, `is_falsified`, allowlist
|
||||
- `generate/math_candidate_parser.py::CandidateInitial` — required fields:
|
||||
`(initial, source_span, matched_anchor, matched_value_token, matched_unit_token, matched_entity_token)`
|
||||
- `generate/math_problem_graph.py::InitialPossession, Quantity`
|
||||
- Case 0019 audit row in `evals/gsm8k_math/train_sample/v1/audit_brief_11.json`
|
||||
- The literal text of case 0019 in `evals/gsm8k_math/train_sample/v1/cases.jsonl`
|
||||
- `tests/test_composition_consult_in_injector.py` — the synthetic-anchor tests
|
||||
showing the consumption path admits when given populated anchors
|
||||
- `tests/test_consumption_case_0050_hazard_pin.py` — the case-0050
|
||||
parametrized canary
|
||||
|
||||
---
|
||||
|
||||
## The target case
|
||||
|
||||
**Case 0019:**
|
||||
|
||||
> "John adopts a dog from a shelter. The dog ends up having health
|
||||
> problems and this requires 3 vet appointments, which cost $400
|
||||
> each. After 2.5 years of these appointments John discovers that his
|
||||
> dog's appointments are only 50% covered by insurance. How much did
|
||||
> John pay total?"
|
||||
|
||||
The sentence that triggers the composition is:
|
||||
|
||||
> "The dog ends up having health problems and this requires 3 vet
|
||||
> appointments, which cost $400 each."
|
||||
|
||||
Recognized data the extended matcher must bind:
|
||||
|
||||
- outer count: **3**
|
||||
- unit cost: **$400**
|
||||
- per-unit token: **each**
|
||||
- currency symbol: **$**
|
||||
|
||||
Pre-composed admission target:
|
||||
|
||||
```python
|
||||
CandidateInitial(
|
||||
initial=InitialPossession(
|
||||
entity=<resolved_subject>, # see "Subject binding" below
|
||||
quantity=Quantity(value=1200, unit="dollars"),
|
||||
),
|
||||
source_span="3 vet appointments, which cost $400 each",
|
||||
matched_anchor="cost",
|
||||
matched_value_token="1200", # the composed value as a token
|
||||
matched_unit_token="dollars",
|
||||
matched_entity_token=<resolved_subject>,
|
||||
)
|
||||
```
|
||||
|
||||
`composition_shape = "bound(count) × bound(unit_cost)"`
|
||||
(must match the surface_pattern an operator ratifies in
|
||||
`compositions/multiplicative_composition.jsonl`)
|
||||
|
||||
---
|
||||
|
||||
## Subject binding (the load-bearing decision)
|
||||
|
||||
The CandidateInitial requires a non-empty `entity`. Case 0019's
|
||||
sentence ("The dog ends up having health problems…") has no human
|
||||
subject in the same sentence — "John" lives in sentence 0.
|
||||
|
||||
**Three options, pick one (recommend Option A):**
|
||||
|
||||
### Option A — Refuse when same-sentence subject is absent
|
||||
|
||||
The matcher checks the statement for a recognized proper-noun subject.
|
||||
If absent (case 0019's situation), the matcher returns `None` for the
|
||||
composition extension — falling back to the existing detection-only
|
||||
behavior. **The composition admission does NOT fire for case 0019.**
|
||||
|
||||
This is honest refusal-preferring: cross-sentence subject binding is
|
||||
its own hazard surface (the wrong subject = wrong arithmetic
|
||||
attribution).
|
||||
|
||||
If you choose Option A, case 0019 stays refused — the brief's truth
|
||||
test #1 is still **partial** for THIS PR. Pick a different canary
|
||||
sentence with same-sentence subject (e.g. construct a synthetic case
|
||||
where the subject IS in the same sentence).
|
||||
|
||||
### Option B — Use a placeholder subject (DISCOURAGED)
|
||||
|
||||
Insert `entity="anonymous"` or similar. **Strongly discouraged** —
|
||||
this fabricates a subject and pollutes the candidate graph. The
|
||||
solver may produce a "correct" total but attribute it wrongly, which
|
||||
is structurally the same shape as case 0050 hazard (correct-looking
|
||||
trace, wrong attribution).
|
||||
|
||||
Forbidden unless explicitly approved.
|
||||
|
||||
### Option C — Cross-sentence subject lookup
|
||||
|
||||
Make the matcher consult prior-sentence state to find the most recent
|
||||
proper-noun entity. This requires either:
|
||||
|
||||
- threading sentence-state context into the recognizer match path
|
||||
(currently the matcher only sees one sentence at a time), or
|
||||
- extending `RecognizerMatch` with an optional `prior_subject` field
|
||||
populated upstream
|
||||
|
||||
Either is a larger surface than a single PR should land. **Defer to
|
||||
its own brief.**
|
||||
|
||||
### Recommendation
|
||||
|
||||
**Ship Option A**, document the case-0019 gap as "requires Option C"
|
||||
in the PR body, and demonstrate the truth-test fires via a
|
||||
**purpose-built test case** that has same-sentence subject. Example:
|
||||
|
||||
> "Maria bought 3 vet appointments, which cost $400 each."
|
||||
|
||||
For Maria-with-3-appointments: count=3, unit_cost=400, subject=Maria
|
||||
(same sentence) → CandidateInitial(entity="Maria", quantity=$1200).
|
||||
|
||||
Add this case to `evals/gsm8k_math/train_sample/v1/cases.jsonl` as a
|
||||
synthetic test case OR write a stand-alone Python test that builds
|
||||
the recognizer match directly and verifies admission.
|
||||
|
||||
---
|
||||
|
||||
## Outcome
|
||||
|
||||
### Modules touched (minimum scope)
|
||||
|
||||
1. **`generate/recognizer_match.py`**:
|
||||
- Extend `_match_rate_with_currency` (or add a sibling helper
|
||||
called from it) that:
|
||||
- detects an outer count token in the same statement
|
||||
- parses the count + per-unit cost
|
||||
- resolves the subject under Option A (same-sentence
|
||||
proper-noun extraction; refuse otherwise)
|
||||
- constructs the pre-composed `CandidateInitial`
|
||||
- publishes the anchor with keys `composition_shape`,
|
||||
`composed_initial`, `currency_symbol`, `amount`, `per_unit`,
|
||||
`outer_count`, `subject` (for debug/audit)
|
||||
|
||||
2. **`generate/recognizer_anchor_inject.py`** — **no changes**.
|
||||
The consumption wire from PR #398 already handles `composition_shape`
|
||||
+ `composed_initial`. This PR proves it lights up.
|
||||
|
||||
### Manifest / pack changes
|
||||
|
||||
**None.** The operator must separately ratify
|
||||
`bound(count) × bound(unit_cost)` under `multiplicative_composition`
|
||||
via `apply_composition_claim()` — that ratification already exists in
|
||||
the canonical pack (or can be re-ratified). The matcher extension
|
||||
makes the existing dormant ratification load-bearing.
|
||||
|
||||
---
|
||||
|
||||
## Hard requirements
|
||||
|
||||
- **Refusal-preferring.** Subject absent → matcher does NOT emit a
|
||||
composition anchor. The existing currency_per_unit_rate detection
|
||||
path continues to fire (no regression).
|
||||
- **Outer-count parse narrowness.** The outer count must be a single
|
||||
integer or known number-word adjacent to a counted noun (mirror
|
||||
`_match_discrete_count_statement`'s narrowness layers). Multi-count
|
||||
or ambiguous → refuse the composition extension.
|
||||
- **Per-unit token in observed set.** Only fire when the matched
|
||||
per-unit token (e.g. "each", "per") is in the spec's
|
||||
`observed_per_units` (existing narrowness from
|
||||
`_match_rate_with_currency`).
|
||||
- **`composition_shape` MUST match a SAFE category.** The matcher
|
||||
emits `"bound(count) × bound(unit_cost)"` — the operator's
|
||||
ratification of this exact pattern under
|
||||
`multiplicative_composition` is what lights it up. Any other
|
||||
shape string is forbidden.
|
||||
- **Pre-composed value is `int` or `float` per `Quantity` invariants.**
|
||||
Compute `outer_count * unit_cost`; if either is non-numeric,
|
||||
refuse.
|
||||
- **Source-span requirement.** `source_span` must be a verbatim
|
||||
substring of the statement (existing CandidateInitial discipline).
|
||||
- **Case 0050 hazard pin.** The matcher extension MUST NOT cause
|
||||
case 0050 to admit. The extension's narrowness must reject case
|
||||
0050's sentence shape (which has no per-unit framing of this
|
||||
form).
|
||||
- **No new eval lanes** (ADR-0166).
|
||||
- **No solver / parser / decomposer mutation** (ADR-0169
|
||||
§"Mutation boundary").
|
||||
|
||||
---
|
||||
|
||||
## Tests
|
||||
|
||||
### `tests/test_matcher_extension_currency_per_unit.py`
|
||||
|
||||
1. **`test_outer_count_extracted_with_subject`** — synthetic sentence
|
||||
"Maria bought 3 vet appointments, which cost $400 each."; matcher
|
||||
returns anchor with composition_shape + composed_initial(value=1200, entity="Maria")
|
||||
2. **`test_subject_absent_refuses_composition_extension`** — case 0019's
|
||||
exact sentence "The dog ends up having health problems and this
|
||||
requires 3 vet appointments, which cost $400 each."; matcher
|
||||
returns the existing rate anchors but does NOT publish
|
||||
composition_shape (Option A)
|
||||
3. **`test_per_unit_token_outside_observed_set_refuses`** — narrowness
|
||||
guard
|
||||
4. **`test_multiple_counts_refuse_composition`** — narrowness guard
|
||||
(refusal-preferring on ambiguity)
|
||||
5. **`test_count_word_form_admits`** — "Maria bought three vet
|
||||
appointments at $400 each" → composed_initial(value=1200)
|
||||
6. **`test_negative_or_zero_count_refuses`**
|
||||
7. **`test_currency_symbol_outside_observed_refuses`**
|
||||
8. **`test_emits_canonical_unit_dollars`** — `Quantity.unit == "dollars"`
|
||||
for `$` symbol
|
||||
|
||||
### `tests/test_matcher_extension_case_0050_hazard_pin.py`
|
||||
|
||||
1. **`test_case_0050_does_not_emit_composition_shape`** — feed case
|
||||
0050's actual sentences through the extended matcher; assert no
|
||||
anchor carries `composition_shape`. Mandatory; runs in CI.
|
||||
|
||||
### `tests/test_matcher_extension_end_to_end_admission.py`
|
||||
|
||||
The TRUTH TEST for this PR:
|
||||
|
||||
1. **`test_synthetic_maria_admits_via_composition_registry`** — start
|
||||
from a clean pack, ratify `bound(count) × bound(unit_cost)` under
|
||||
`multiplicative_composition`, run the candidate-graph pipeline
|
||||
on the synthetic Maria sentence, assert the result is a correct
|
||||
admission (not refusal).
|
||||
2. **`test_train_sample_case_0019_partial`** — explicit test
|
||||
documenting case 0019's refusal-preserving status under Option A
|
||||
(refuses because cross-sentence subject; not a bug, an honest
|
||||
gap). Comment names Option C as the next brief.
|
||||
|
||||
### `tests/test_matcher_extension_train_sample_baseline_preserved.py`
|
||||
|
||||
1. **`test_train_sample_counts_unchanged_or_better`** — full
|
||||
`train_sample` reader-on eval; assert `correct >= 3`, `wrong == 0`,
|
||||
`refused <= 47`. Any improvement is a bonus; no regression is
|
||||
mandatory.
|
||||
|
||||
### `tests/test_matcher_extension_public_split_preserved.py`
|
||||
|
||||
1. **`test_gsm8k_math_public_150_150_preserved`** — `core eval
|
||||
gsm8k_math --split public --json` returns `cases_total=150`,
|
||||
`correct=150`, `wrong=0`, `refused=0`. Mandatory.
|
||||
|
||||
---
|
||||
|
||||
## Truth test (binding 6-row table for this PR)
|
||||
|
||||
| # | Assertion | How to verify |
|
||||
|---|---|---|
|
||||
| 1 | Synthetic Maria sentence admits | `test_synthetic_maria_admits_via_composition_registry` passes |
|
||||
| 2 | Case 0050 stays refused | `test_matcher_extension_case_0050_hazard_pin.py` passes |
|
||||
| 3 | `train_sample` `correct ≥ 3`, no regression | full train_sample reader-on run; report green |
|
||||
| 4 | `wrong == 0` preserved (train_sample) | same |
|
||||
| 5 | `public` split 150/150 unchanged | `core eval gsm8k_math --split public --json` |
|
||||
| 6 | All PR #398 tests still pass | `core test --suite packs -q` green |
|
||||
|
||||
Row #1 replaces the original case-0019 row from PR #397's truth test
|
||||
(case 0019 stays refused under Option A; that's a Option C concern,
|
||||
not this PR).
|
||||
|
||||
---
|
||||
|
||||
## Anti-regression invariants
|
||||
|
||||
- `wrong == 0` on `core eval gsm8k_math --split public` preserved
|
||||
- Case 0050 stays refused under the parametrized hazard pin
|
||||
- ADR-0166 — no new eval lanes
|
||||
- ADR-0167 partition — matcher remains math-domain only
|
||||
- Empty composition_registry runtime byte-identical to today
|
||||
- `SAFE_COMPOSITION_CATEGORIES` enforced at write AND load
|
||||
- Refusal-preferring discipline: subject-absent → no composition emission
|
||||
- `engine_state/*` never committed
|
||||
- Pinned-lane SHAs may move (intentional `correct` delta if admission
|
||||
fires); call out the move in the PR body
|
||||
|
||||
---
|
||||
|
||||
## Forbidden surface
|
||||
|
||||
- Option B (placeholder subject) — fabricates entity attribution
|
||||
- Option C (cross-sentence subject) — defer to its own brief
|
||||
- New SAFE_COMPOSITION_CATEGORIES entries (this PR is read-only over
|
||||
the existing allowlist)
|
||||
- Mutating `_match_currency_amount` (its discriminator is correct;
|
||||
don't conflate)
|
||||
- Mutating `_match_multiplicative_aggregation` (different shape;
|
||||
separate brief)
|
||||
- Adding new ShapeCategory values
|
||||
- Solver / parser / decomposer / arithmetic-operator mutation
|
||||
- Manifest schema changes (PR #398 already added the optional
|
||||
composition_checksum field)
|
||||
|
||||
---
|
||||
|
||||
## What ships when this PR lands
|
||||
|
||||
- One matcher extension at `_match_rate_with_currency`
|
||||
- 12+ new tests
|
||||
- The first case (synthetic Maria) admits via the
|
||||
ratify → compile → load → consume → admit chain
|
||||
- `train_sample` counts improve OR stay at baseline (no regression)
|
||||
- The dormant consumption path in PR #398 becomes load-bearing for
|
||||
the per-unit-cost composition shape
|
||||
- Case 0019 remains refused — but explicitly under documented
|
||||
scope-boundary, not under structural unknown
|
||||
|
||||
## Sequencing
|
||||
|
||||
- **No upstream blocker** beyond PR #398 landing on main.
|
||||
- **Subsequent briefs** (each its own PR):
|
||||
- **ME-2:** Cross-sentence subject binding (Option C); admits case 0019
|
||||
- **ME-3:** Multi-quantity_composition matcher (8 audit cases)
|
||||
- **ME-4:** Additive composition matcher (independent named quantities)
|
||||
- **ME-5:** Subtractive composition matcher
|
||||
|
||||
Each subsequent brief carries its own canary case + truth test.
|
||||
|
||||
---
|
||||
|
||||
## Memory pointers
|
||||
|
||||
- [[project-ratification-consumption-gap-2026-05-27]] — the original finding
|
||||
- [[feedback-ratify-vs-consume-loop-closure]] — pattern
|
||||
- [[feedback-wrong-zero-hazard-case-0050]] — mandatory pin
|
||||
- [[feedback-production-line-pattern]] — dispatch pattern
|
||||
- [[feedback-parallel-agent-worktrees]]
|
||||
- [[feedback-address-critiques-dont-waive]] — Option A is the honest
|
||||
refusal-preferring choice; Option B is the convenient cheat that
|
||||
this brief explicitly forbids
|
||||
|
||||
---
|
||||
|
||||
## Copy-paste dispatch line
|
||||
|
||||
```text
|
||||
Read docs/handoff/MATCHER-EXTENSION-DISPATCH-PACK.md (entire file).
|
||||
git fetch origin main && git worktree add /tmp/wt-matcher origin/main && cd /tmp/wt-matcher && git checkout -b feat/matcher-extension-currency-per-unit-composition
|
||||
```
|
||||
|
||||
Operator instruction sequence:
|
||||
1. Read this brief plus the three "parent briefs" + ADR-0169 + the four `Reads required FIRST` files.
|
||||
2. Implement the matcher extension in `_match_rate_with_currency` (or a sibling helper) per Option A.
|
||||
3. Write the 12 tests across the four test files.
|
||||
4. Run the 6-row truth-test sequence end-to-end.
|
||||
5. Confirm all 6 rows hold before opening PR.
|
||||
6. PR title: `feat(matcher-extension): currency-per-unit composition admission (ME-1)`.
|
||||
|
||||
---
|
||||
|
||||
## Decision summary
|
||||
|
||||
This PR closes the "consumption path is dormant" finding from PR #398
|
||||
**for the simplest possible composition shape** (currency × per-unit
|
||||
count). It does NOT close case 0019 — that requires cross-sentence
|
||||
subject binding (Option C) and is the next brief.
|
||||
|
||||
The honest scoping: ship the matcher extension, prove the loop runs
|
||||
end-to-end on a synthetic case where same-sentence subject binding
|
||||
holds, leave case 0019 as the next domino. The flywheel turns one
|
||||
revolution.
|
||||
Loading…
Reference in a new issue