core/docs/decisions/ADR-0169-compositionclaim-ratification.md

ADR-0169 — CompositionClaim Ratification Doctrine

Status: Proposed (doctrine/scoping ADR; no runtime mutation in this PR) Date: 2026-05-27 Author: Shay Parent: ADR-0167 Related: ADR-0056, ADR-0057, ADR-0114a, ADR-0164, ADR-0165, ADR-0166, ADR-0168, ADR-0172, ADR-0167 FOLLOWUPS §1

---

Context

ADR-0167 scoped the first math-teaching corridor to LexicalClaim only. ADR-0168 extended doctrine to FrameClaim — bounded frame-opening admissibility under deterministic replay-constrained ratification.

CompositionClaim is the next sub-type in the queue from ADR-0167 FOLLOWUPS §1 and is, by counted audit evidence, the highest-leverage remaining handler:

• 12 quantity_extraction refusals
• 8 multi_quantity_composition refusals

— 20 of 47 audit refusals in evals/gsm8k_math/train_sample/v1/audit_brief_11.json, all carrying refusal_reason="incomplete_operation".

Correction note. ADR-0167 FOLLOWUPS §1 priority hint quoted "8+11 = 19 cases" for CompositionClaim. The actual audit count in audit_brief_11.json is 12 + 8 = 20 (quantity_extraction = 12, multi_quantity_composition = 8). This ADR uses the audit count.

CompositionClaim is qualitatively different from both LexicalClaim and FrameClaim.

A LexicalClaim says:

"surface form X belongs to lexical category Y"

A FrameClaim says:

"surface form X opens (or does not open) a semantic frame of class K"

A CompositionClaim says:

"surface pattern X composes a set of recognized quantities into a single derived quantity under composition category C"

That is an arithmetic-chain admissibility decision.

A CompositionClaim decides whether a frame which already recognized its slots is permitted to fold multiple bound quantities into one operand for downstream solver invocation. The hazard is direct and asymmetric:

• a mistaken lexical entry creates noise
• a mistaken frame opener creates false reasoning structure
• a mistaken composition pattern admits arithmetic errors

A wrong composition does not pollute the graph topology. It pollutes the operand fed to the solver. That is closer to the wrong > 0 surface than any prior sub-type.

This is the first ADR-0167 sub-type whose failure mode is:

producing a numerically wrong but structurally well-formed answer

That is materially worse than refusal and materially worse than graph fabrication, because the operator-facing trace looks correct.

---

Prior ADR compatibility audit

This ADR is not final until it remains compatible with prior ADR doctrine. The following audit was performed before opening implementation work.

Prior ADR	Load-bearing rule	ADR-0169 compatibility result
ADR-0056	Contemplation is cognitive only; no corpus mutation; reviewed evidence boundaries matter	Compatible. ADR-0169 keeps composition evidence proposal-only during contemplation; no corpus mutation.
ADR-0057	Replay-equivalence is precondition, not permission; operator accept required; proposal logs append-only; reviewed-corpus evidence floor for cognition TeachingChainProposal	Compatible with constraint. CompositionClaim MUST use the math-specific proposal/ratification adapter (see ADR-0169.1) to preserve ADR-0057 discipline without laundering audit evidence as cognition corpus evidence.
ADR-0114a	Zero wrong, typed refusal, adversarial misparse=0, determinism, operation provenance	Compatible and elevates wrong=0 to first-class concern: composition is the closest sub-type to the arithmetic surface, so case 0050 and recognized-but-uninjectable hazards are mandatory pins.
ADR-0164	Incremental reader over semantic categories; no hidden best guess; new categories/rules require ADR	Compatible. CompositionClaim ratifies reviewed composition-pattern membership only; no dynamic pattern synthesis.
ADR-0165	Regex only at lexeme level; never grammar templates	Compatible with care. Composition patterns are structural shape patterns over already-recognized quantity slots, not grammar templates over raw text. Pattern catalog stays at the bound-slot composition level (e.g. each <count> @ <one_unit_cost> once both slots are bound), not at the sentence level.
ADR-0166	Capability before measurement; no new eval lanes ahead of operators	Compatible. ADR-0169 is doctrine/capability scoping only and explicitly forbids new eval lanes in the implementation PR.
ADR-0167	Audit rows become teaching evidence; LexicalClaim first; harder sub-types require their own ADR	Compatible. ADR-0169 is the explicit follow-on sub-type ADR called out in FOLLOWUPS §1.
ADR-0168	FrameClaim is bounded frame-opening; allowlisted categories; refusal-first; proposal-only mutation	Compatible. CompositionClaim is downstream of FrameClaim and consumes already-opened frames; it never invents frames.
ADR-0172	Math-corpus decomposition mechanism — contemplation, decomposer, workbench corridor (Tier 1.5)	Compatible. ADR-0169 introduces the next change_kind (composition_reclassification) and the next ratifiable handler in the corridor ADR-0172 established.

Resolved tension: ADR-0057 evidence floor

ADR-0057's ordinary TeachingChainProposal eligibility requires at least one source="corpus" evidence pointer. Math-domain CompositionClaims originate from audit/refusal artifacts, not from the cognition teaching corpus.

ADR-0169 therefore does not weaken ADR-0057.

Implementation MUST use the math-specific proposal/ratification adapter (MathCompositionClaimProposal) defined in ADR-0169.1, whose evidence floor is MathReaderRefusalEvidence plus replay-admissibility evidence, while preserving ADR-0057's append-only / replay / operator-review discipline.

What is forbidden:

• treating audit evidence as cognition corpus evidence
• bypassing the reviewed-evidence floor
• auto-accepting because replay passed
• mutating runtime composition behavior outside the proposal/review boundary
• creating a second sub-type adapter that mimics ADR-0057 without these gates

This section is the compatibility trip-wire for any implementation PR.

---

Decision

CompositionClaim ratification is permitted only as a deterministic, replay-equivalent, operator-reviewed proposal surface with explicit hazard pins and category allowlists.

This ADR does not approve runtime implementation.

This ADR defines:

• what a CompositionClaim is
• what it is allowed to mutate
• what it is forbidden to mutate
• the replay obligations required before implementation
• the initial safe composition-category surface
• the explicit non-goals

Implementation is deferred to a follow-on PR (CC-2 in docs/handoff/COMPOSITIONCLAIM-BRIEF-PACK.md) that must prove the acceptance gates below.

---

Definition of a CompositionClaim

A CompositionClaim is a reviewed assertion that a structural shape pattern over already-bound quantity slots composes those quantities into one derived operand under a named composition category.

Canonical shape:

(surface_pattern, composition_category, polarity)

Where:

• surface_pattern is a deterministic structural pattern over already-recognized slots (e.g. bound(count) bound(unit_cost)), not a regex over raw text;
• composition_category is one entry of the SAFE_COMPOSITION_CATEGORIES allowlist;
• polarity is "affirms" (this pattern composes under category C) or "falsifies" (this pattern does NOT compose, refuse).

Examples (initial scope only):

Pattern (shape over bound slots)	Category	Meaning
bound(count) × bound(unit_cost)	multiplicative_composition	total cost = count × unit_cost
bound(qty_a) + bound(qty_b) (independent named quantities in same frame)	additive_composition	aggregate = qty_a + qty_b
bound(initial) − bound(removed)	subtractive_composition	remainder = initial − removed

The claim concerns:

• composition admissibility for a recognized slot tuple
• which operator binds those slots into one operand
• composition refusal stability when the pattern does not apply

It does NOT assert:

• frame admissibility (that is FrameClaim)
• entity identity
• quantity correctness (the slots are already bound)
• reference resolution (that is ReferenceClaim)
• slot completion (that is SlotClaim)
• solver validity

Those remain separate sub-types.

---

Why CompositionClaim is dangerous

Composition patterns sit immediately upstream of solver invocation.

• a lexical error may fail to ground
• a frame error may fabricate a graph
• a composition error feeds a wrong number to a correct solver

The principal hazard is:

recognized-and-well-formed-but-wrongly-composed operand

This is the asymmetric failure mode that produces:

• a structurally clean trace
• a typed, frame-opened, slot-bound graph
• an operator-plausible suggested CLI
• and a numerically wrong answer

Specifically threatening:

• GSM8K train-sample case 0050 (the canary preventing pre_frame_filler fixes from drifting into wrong > 0) — case 0050 illustrates how a composition mis-assignment can land a graph that looks admissible
• recognized-but-uninjectable skip-only fallback
• partial-graph greed promoted to full graph by a permissive composition pattern
• multi-quantity initial-state frames silently collapsing 3 distinct quantities into a sum that the original story did not require

The system must therefore prefer:

refuse > leave the operand unbound > compose under an unproven pattern

at all times.

---

Initial safe category scope

Initial implementation scope MUST be allowlist-only.

No freeform composition invention. No dynamic pattern synthesis. No embedding-nearest-pattern fallback. No "majority vote" across competing categories.

Initial safe categories:

Category	Scope
multiplicative_composition	bound(count) × bound(one_unit_cost) — produces a total under a single named unit semantic
additive_composition	sum of independent named quantities sharing the same frame and unit (e.g. apples + apples)
subtractive_composition	initial − removed, both bound in the same frame, sharing unit

Allowlist (canonical):

SAFE_COMPOSITION_CATEGORIES = {
    "multiplicative_composition",
    "additive_composition",
    "subtractive_composition",
}

Explicitly excluded initially:

Deferred category	Reason
distributive_composition	requires nested frame interaction; multi-operator semantics
ratio_composition	unit-changing operation; demands SlotClaim for the denominator unit
comparative_composition	demands ReferenceClaim and ordering semantics
percentage_composition	requires fraction_percentage_literal recognizer (separate sub-type)
unit_conversion_composition	requires unit_binding slot doctrine (SlotClaim)
time_composition	compound_time_literal is its own recognizer concern
chained_composition	composition-of-compositions; explicitly deferred until the three primitives prove stable

The decomposer dispatch table (teaching/math_contemplation.py, see CC-3) maps the audit's (refusal_reason, missing_operator) pairs into composition_reclassification only when the target category is in SAFE_COMPOSITION_CATEGORIES. Anything else routes to injector_sub_shape (the catch-all) — refuse-first.

---

Mutation boundary

A CompositionClaim ratification MAY mutate only:

• reviewed composition-pattern registries: language_packs/data/en_core_math_v1/compositions/{category}.jsonl
• proposal-layer artifacts (append-only proposal log)

A CompositionClaim ratification MUST NOT directly mutate:

• solver logic
• parser traversal order
• decomposer dispatch (heuristic changes ship as their own reviewed PR, not as a side effect of ratification)
• runtime graph execution
• arithmetic operators
• refusal logic
• graph verifier semantics
• frame-opener registries (those are FrameClaim's surface)
• lexical registries (those are LexicalClaim's surface)

The runtime consumes ratified composition data only through existing reviewed pack-loading mechanisms.

No direct hot-path mutation. No live-running registry edits.

---

Replay obligations

Before implementation, the following replay obligations must be proven.

1. Deterministic claim signature

Equivalent refusals MUST produce identical normalized claim signatures.

Canonical identity must include:

• normalized surface pattern (over bound-slot shape, not raw text)
• normalized composition category
• polarity
• audit-row digest
• refusal category (incomplete_operation)
• missing operator (quantity_extraction | multi_quantity_composition)

Equivalent evidence MUST deduplicate.

---

2. Replay equivalence

Ratified CompositionClaims MUST replay identically across:

• in-process runs
• cross-process runs (subprocess test)
• reordered candidate queues (queue-order independence)
• repeated ingestion of the same audit evidence (idempotency)

No queue-order dependence.

---

3. wrong==0 preservation

The implementation must prove:

new composition admission cannot silently convert a prior refusal
into an incorrect arithmetic answer

This specifically requires hazard pins for:

• case 0050 (gsm8k-train-sample-v1-0050) — pin in tests/test_math_composition_ratification.py::test_case_0050_hazard_pin; the case must remain refused after any synthetic CompositionClaim ratification in the allowlist
• recognized-but-uninjectable fallback
• partial graph acceptance
• multi-quantity initial-state collapse (e.g. case 0042: 3 quantities)
• operand swap (subtractive composition with reversed minuend/subtrahend)

---

4. Refusal stability

Previously refusing cases MAY become:

• correctly admitted (with a verified arithmetic answer)
• still refused

They MUST NOT become:

• partially admitted
• ambiguously admitted
• non-deterministically admitted
• structurally admitted with a wrong operand

Refusal stability MUST be verified across the full audit_brief_11.json corpus, not just the 20 composition cases.

---

Partition guarantees

CompositionClaims inherit the ADR-0167 domain partition.

Math-domain composition claims:

• use math-domain replay gates
• use math-domain contemplation routing
• do not borrow cognition corpus evidence
• do not reuse cognition semantic-domain classifiers
• do not produce cognition TeachingChainProposal records

Cross-domain leakage is prohibited.

The cognition TeachingChainProposal flow MUST NOT see math MathCompositionClaimProposal records and vice versa. This is a hard partition test in the implementation PR (mirror tests/test_math_frame_ratification.py::test_partition_*).

---

Refusal-first doctrine

The system must continue preferring:

refuse > speculate

throughout CompositionClaim processing.

Specifically forbidden:

• nearest-pattern guessing
• probabilistic fallback category selection
• majority-vote composition admission
• confidence-threshold operand coercion
• dynamic composition synthesis at runtime
• "best guess" multiplication vs addition when both slots present

A composition the engine cannot prove under an allowlisted category remains a refusal event.

The teaching corridor exists precisely so the engine does not need to invent arithmetic structure at runtime.

---

Non-goals

This ADR does NOT approve:

• ReferenceClaim
• SlotClaim
• distributive_composition, ratio_composition, comparative_composition, percentage_composition, unit_conversion_composition, time_composition, chained_composition
• dynamic composition synthesis
• graph-schema replacement
• automatic composition learning
• runtime self-modification
• autonomous pack mutation
• embedding-derived arithmetic repair
• a reviewed math corpus substrate (deferred — see ADR-0169.1 "Why not a reviewed math corpus first?")

This ADR also does NOT attempt to solve:

• generalized arithmetic reasoning
• open-ended quantity composition
• unit-changing operations
• multi-step arithmetic chains

The target is bounded deterministic composition admission for audited GSM8K-style reasoning surfaces under three allowlisted primitives.

---

Sequencing

Per ADR-0166:

Q1 — Capability

Adds one new operator-ratifiable admissibility surface:

bound-slot shape pattern -> reviewed composition category

using the existing audit → contemplation → replay → HITL corridor established by ADR-0167 and ADR-0172.

Q2 — Lane

No new eval lane.

Existing:

• GSM8K audit lane (evals/gsm8k_math)
• contemplation replay lane (core eval math-contemplation)
• wrong==0 gates
• determinism checks

remain the proof surface.

Q3 — Invariant

Must preserve:

• wrong == 0
• replay equivalence
• deterministic claim hashing
• refusal-first semantics
• explicit operator ratification
• reviewed mutation only
• domain partition (math vs cognition)

The implementation PR passes only when all seven are mechanically proven.

---

Acceptance gates for implementation PR

A future implementation PR (CC-2) must provide:

• deterministic claim canonicalization tests
• cross-process replay-equivalence tests (subprocess)
• queue-order independence tests (A→B == B→A ratify)
• duplicate ratification idempotency tests (AlreadyRatified on second call)
• evidence-tampering rejection tests
• case 0050 hazard pin — mandatory; mirror tests/test_math_frame_ratification.py::test_case_0050_hazard_pin; case 0050 must remain refused after any synthetic CompositionClaim ratification under the initial allowlist
• recognized-but-uninjectable regression pins
• refusal-stability regression suite across the full audit_brief_11.json corpus
• cross-domain partition tests (cognition TeachingChainProposal flow must NOT see math CompositionClaims and vice versa)
• no-corpus-mutation proof (cognition corpus bytes unchanged during math composition replay)
• no-runtime-hotpatch proof (solver / parser / decomposer / graph verifier bytes unchanged)
• audit-evidence-not-laundered-as-corpus test (the adapter must emit source="math_audit", never source="corpus")
• workbench dispatch test: composition_reclassification routes to CompositionClaim, not 501
• proposed_change_kind Literal accepts composition_reclassification
• W1 round-trip test extended for the new change_kind

without introducing:

• new eval lanes
• stochastic routing
• runtime graph guessing
• categories outside SAFE_COMPOSITION_CATEGORIES

---

Relationship to ADR-0167 and ADR-0168

ADR-0167 established:

audit rows become teaching evidence

ADR-0168 established:

frame-opening semantics may become reviewed teaching evidence

ADR-0169 establishes:

composition patterns over already-bound slots may become reviewed
teaching evidence — but only under deterministic replay-constrained
doctrine, and only inside an allowlisted category surface, because
composition errors are the closest sub-type to direct arithmetic
wrongness

The escalation is intentional:

• LexicalClaim teaches vocabulary
• FrameClaim teaches admissibility structure
• CompositionClaim teaches arithmetic-chain admissibility

Each step is materially more dangerous than the last and therefore requires explicit doctrine before implementation.

---

Decision

CORE may extend the ADR-0167 teaching corridor from lexical and frame ratification into bounded composition-pattern ratification, provided:

• replay equivalence remains deterministic
• wrong == 0 hazard pins hold (case 0050 mandatory)
• composition categories remain explicitly allowlisted
• runtime speculation remains prohibited
• all mutation remains proposal-reviewed and replay-auditable
• the math-domain proposal/ratification adapter (ADR-0169.1) is used; audit evidence is never laundered as cognition corpus evidence

Refusal remains preferable to speculative arithmetic composition.

Reopening this ADR requires evidence that:

1. the replay obligations cannot be satisfied mechanically, or
2. a graph-schema approach supersedes sub-type ratification entirely, or
3. composition wrong-rate cannot be held at zero under the proposed allowlist (in which case the allowlist contracts, not expands).