core/docs/decisions/ADR-0169.1-math-compositionclaim-proposal-adapter.md

# ADR-0169.1 — MathCompositionClaimProposal Adapter

**Status:** Proposed (design bridge; no runtime CompositionClaim admission in this PR)
**Date:** 2026-05-27
**Author:** Shay
**Parent:** [ADR-0169](./ADR-0169-compositionclaim-ratification.md)
**Related:** ADR-0057, ADR-0163, ADR-0164, ADR-0166, ADR-0167, ADR-0168, ADR-0168.1, ADR-0172

---

## Context

ADR-0169 identified a required compatibility bridge before any
CompositionClaim implementation can land.

ADR-0057 ordinary `TeachingChainProposal` eligibility requires a
reviewed `source="corpus"` evidence pointer. That is correct for
cognition teaching chains, where the claim is grounded in reviewed
teaching-corpus material.

Math-domain CompositionClaims originate elsewhere:

```text
MathReaderRefusalEvidence / audit rows
```

— specifically the 20 rows in
`evals/gsm8k_math/train_sample/v1/audit_brief_11.json` under
`refusal_reason="incomplete_operation"` with `missing_operator` in
`{"quantity_extraction", "multi_quantity_composition"}`.

Those rows are legitimate evidence of a teachable composition gap,
but they are not cognition corpus evidence and must never be laundered
into cognition corpus pointers.

Therefore CompositionClaim cannot simply reuse ordinary
`TeachingChainProposal` as-is without either:

1. weakening ADR-0057's reviewed-evidence floor, or
2. falsely treating audit evidence as cognition corpus evidence.

Both are forbidden.

This ADR is structurally analogous to ADR-0168.1
(`MathFrameClaimProposal`). The same bridge logic applies, with the
data shape and evidence floor specialized to composition.

---

## Decision

Choose a math-specific proposal/ratification adapter:

```text
MathCompositionClaimProposal
```

instead of creating a reviewed math corpus artifact first.

This adapter preserves ADR-0057's discipline:

- append-only proposal log
- replay-equivalence/admissibility as precondition, not permission
- explicit operator review before mutation
- no deletion
- no auto-accept
- no active-pack mutation during replay

but gives math-domain audit evidence its own honest evidence floor.

---

## Why not a reviewed math corpus first?

A reviewed math corpus may eventually be useful, but it is premature
for the second math sub-type bridge (FrameClaim is the first; see
ADR-0168.1).

Creating it now would require deciding:

- corpus schema
- corpus lifecycle
- corpus indexing semantics
- corpus replay integration
- whether frame evidence, slot evidence, composition evidence, and
  reference evidence share one corpus or separate corpora
- how accepted math evidence relates to pack manifests

That is a larger substrate decision than CompositionClaim needs.

The adapter remains narrower:

```text
one claim type
one proposal surface
one replay gate
one operator acceptance boundary
```

It keeps the capability path moving without inventing a new corpus
family before the need is proven across at least two sub-types
(FrameClaim and CompositionClaim) and converged.

When (and only when) the third or fourth math sub-type adapter is
needed, the case for collapsing them into a reviewed math corpus
becomes load-bearing. Not yet.

---

## Data shape

A future implementation should define a frozen, canonicalizable data
shape similar to:

```python
@dataclass(frozen=True, slots=True)
class MathCompositionClaimProposal:
    proposal_id: str
    claim_signature: str
    surface_pattern: str  # normalized structural pattern over bound slots
    composition_category: str  # must be in SAFE_COMPOSITION_CATEGORIES
    polarity: Literal["affirms", "falsifies"]
    evidence: tuple[MathReaderRefusalEvidence, ...]
    replay_evidence: AdmissibilityReplayEvidence | None
    review_state: Literal["pending", "accepted", "rejected", "withdrawn"]
    operator_note: str
    provenance: MathProposalProvenance | None
```

Mirror the structure of `MathFrameClaimProposal` (ADR-0168.1) exactly,
swapping `surface_form` / `frame_category` for `surface_pattern` /
`composition_category`.

This is deliberately not a `TeachingChainProposal` because its
evidence floor is not cognition corpus evidence.

It is also deliberately not a runtime composition registry entry. It
is a proposal.

---

## Evidence floor

A `MathCompositionClaimProposal` is eligible only if it has:

1. at least one audit/refusal evidence pointer,
2. a deterministic audit-row digest,
3. a normalized claim signature,
4. a known `missing_operator` subtype mapping to `CompositionClaim`
   (i.e. `quantity_extraction` or `multi_quantity_composition`),
5. an allowlisted `composition_category` (one of
   `SAFE_COMPOSITION_CATEGORIES` from ADR-0169),
6. `boundary_clean=True`, and
7. `polarity in {"affirms", "falsifies"}`.

Audit evidence must include enough provenance to replay the claim:

- case id
- sentence index
- frame index when available
- bound-slot tuple digest (the slot shape over which the composition
  pattern is asserted)
- missing operator
- refusal reason (`incomplete_operation`) and refusal detail
- recognized terms digest
- audit row canonical digest

The evidence pointer source must be a math-specific value such as:

```text
source="math_audit"
```

It must **not** be `source="corpus"` unless and until a real reviewed
math corpus exists. This is the no-laundering trip-wire shared with
ADR-0168.1.

---

## Replay gate

The adapter uses the math-domain replay gate:

```text
run_admissibility_replay_gate
```

(the same gate used by `MathFrameClaimProposal`), parameterized by the
composition-pattern target artifact rather than the frame target
artifact.

Replay remains a precondition, not permission.

If replay regresses any protected metric (`wrong == 0`, refusal
stability, partition, determinism), the proposal auto-transitions to
`rejected` with an `auto_rollback_regression` note.

If replay passes, the proposal remains `pending` until explicit
operator review. This preserves ADR-0057's "replay is precondition,
not permission" rule.

---

## Accepted proposal effect

Accepting a `MathCompositionClaimProposal` may only append (or propose
append) to a reviewed composition-pattern artifact:

```text
language_packs/data/en_core_math_v1/compositions/{category}.jsonl
```

where `{category}` is one of the entries in `SAFE_COMPOSITION_CATEGORIES`.

It must not directly mutate:

- active runtime state
- solver code
- parser code
- decomposer code (heuristic changes are their own reviewed PR)
- graph verifier code
- arithmetic semantics
- frame-opener registries (FrameClaim's surface)
- lexical registries (LexicalClaim's surface)
- cognition corpus
- cognition packs

Acceptance should produce an append-only provenance record linking:

```text
proposal_id -> claim_signature -> target artifact row -> reviewer
```

---

## Idempotency

`proposal_id` must derive from canonical claim identity, not clock
time.

Recommended identity:

```text
sha256(
    domain
  | subtype             # "composition_claim"
  | surface_pattern     # normalized bound-slot shape
  | composition_category
  | polarity
  | evidence_digest_set
)
```

Equivalent evidence should deduplicate. Adding a second audit row for
the same claim may either:

1. append evidence to the existing proposal record, or
2. create a new event referencing the existing proposal id.

It must not create a second independent mutation opportunity for the
same claim.

Calling `apply_composition_claim()` a second time on an already-ratified
proposal must raise `AlreadyRatified` (mirror
`teaching/math_frame_ratification.py` semantics).

---

## Partition guarantees

The adapter is math-domain only.

It must not:

- consume cognition corpus evidence,
- emit cognition `TeachingChainProposal` records,
- append to cognition chains,
- read cognition semantic-domain classifiers,
- use cognition replay gates,
- be visible to cognition contemplation/proposal flows.

It may share infrastructure patterns from ADR-0057 and from
`MathFrameClaimProposal` (ADR-0168.1), but not evidence identity.

The partition test in the implementation PR
(`tests/test_math_composition_ratification.py::test_partition_cognition_proposals_not_seen`)
must mechanically pin that cognition `TeachingChainProposal` records
do not flow into the math composition handler and vice versa.

---

## Trip-wires that close the ADR-0057 compatibility gap

The implementation PR must mechanically prove each of:

1. **No corpus laundering.** The adapter emits `source="math_audit"`
   and never `source="corpus"`. Pinned by
   `test_audit_evidence_not_laundered_as_corpus`.
2. **Append-only proposal log.** No deletion path; rejected/withdrawn
   states are transitions, not removals.
3. **Replay is precondition, not permission.** Replay pass leaves the
   proposal `pending`. Operator accept is required for mutation.
4. **Replay regression auto-rejects.** Any regression in `wrong`,
   refusal stability, partition, or determinism flips the proposal to
   `rejected` with an `auto_rollback_regression` note.
5. **Deterministic proposal id.** `proposal_id` is derived from
   canonical claim identity; equivalent evidence produces equivalent
   ids across processes.
6. **Active-pack bytes unchanged during replay.** The replay gate must
   not mutate `language_packs/data/en_core_math_v1/**` byte content
   until operator accept lands.
7. **No cross-domain emission.** The handler does not produce
   cognition-domain artifacts.
8. **Allowlist enforcement.** A `composition_category` outside
   `SAFE_COMPOSITION_CATEGORIES` raises `WrongCompositionCategory`
   before any provenance is written.

---

## Acceptance gates for implementation

A future implementation PR must prove:

- deterministic claim signature
- deterministic proposal id
- duplicate evidence deduplication
- append-only proposal log behavior
- replay-gate selection = math admissibility replay
- replay pass leaves proposal pending, not accepted
- replay regression auto-rejects
- operator accept is required for mutation
- accept writes only the reviewed math composition target artifact
- active corpus and active pack bytes are unchanged during replay
- audit evidence is never serialized as cognition corpus evidence
- case 0050 remains safe under any synthetic ratification in the
  initial allowlist
- recognized-but-uninjectable remains refused unless fully admitted
  correctly
- multi-quantity initial-state cases (e.g. case 0042 with 3 quantities)
  do not silently collapse under an unproven aggregation
- subtractive composition does not silently swap minuend and subtrahend

---

## Non-goals

This ADR does not implement:

- CompositionClaim runtime admission
- composition-pattern artifact schema (deferred to the implementation PR;
  the JSONL layout under `language_packs/data/en_core_math_v1/compositions/`
  is the artifact target but its row schema is not fixed here)
- workbench rendering
- ReferenceClaim
- SlotClaim
- reviewed math corpus substrate
- automatic acceptance
- additional composition categories beyond the ADR-0169 initial allowlist

This is only the bridge decision that makes future CompositionClaim
implementation compatible with ADR-0057.

---

## Decision summary

> Use a dedicated `MathCompositionClaimProposal` adapter for
> math-domain CompositionClaim evidence. Preserve ADR-0057's
> replay/review discipline, but do not impersonate ADR-0057's cognition
> corpus evidence floor. Audit evidence stays audit evidence;
> operator-reviewed accepted proposals may later append to a reviewed
> math composition artifact under deterministic replay gates, scoped
> to the `SAFE_COMPOSITION_CATEGORIES` allowlist defined in ADR-0169.