From fd9c36049c1b707489b58611f129294096e580a8 Mon Sep 17 00:00:00 2001 From: Shay Date: Wed, 27 May 2026 09:50:33 -0700 Subject: [PATCH] docs(ADR-0168.1): choose math FrameClaim proposal adapter (#365) --- ...0168.1-math-frameclaim-proposal-adapter.md | 276 ++++++++++++++++++ 1 file changed, 276 insertions(+) create mode 100644 docs/decisions/ADR-0168.1-math-frameclaim-proposal-adapter.md diff --git a/docs/decisions/ADR-0168.1-math-frameclaim-proposal-adapter.md b/docs/decisions/ADR-0168.1-math-frameclaim-proposal-adapter.md new file mode 100644 index 00000000..c5fd355e --- /dev/null +++ b/docs/decisions/ADR-0168.1-math-frameclaim-proposal-adapter.md @@ -0,0 +1,276 @@ +# ADR-0168.1 — MathFrameClaimProposal Adapter + +**Status:** Proposed (design bridge; no runtime FrameClaim admission in this PR) +**Date:** 2026-05-27 +**Author:** Shay +**Parent:** [ADR-0168](./ADR-0168-frameclaim-ratification.md) +**Related:** ADR-0057, ADR-0167, ADR-0163, ADR-0164, ADR-0166 + +--- + +## Context + +ADR-0168 identified a required compatibility bridge before any FrameClaim +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 FrameClaims originate elsewhere: + +```text +MathReaderRefusalEvidence / audit rows +``` + +Those rows are legitimate evidence of a teachable gap, but they are not +cognition corpus evidence and must never be laundered into cognition corpus +pointers. + +Therefore FrameClaim 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. + +--- + +## Decision + +Choose a math-specific proposal/ratification adapter: + +```text +MathFrameClaimProposal +``` + +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 +first FrameClaim bridge. + +Creating it now would require deciding: + +- corpus schema +- corpus lifecycle +- corpus indexing semantics +- corpus replay integration +- whether frame evidence, slot evidence, and composition evidence share one + corpus or separate corpora +- how accepted math evidence relates to pack manifests + +That is a larger substrate decision than FrameClaim needs. + +The adapter is 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. + +--- + +## Data shape + +A future implementation should define a frozen, canonicalizable data shape +similar to: + +```python +@dataclass(frozen=True, slots=True) +class MathFrameClaimProposal: + proposal_id: str + claim_signature: str + surface_form: str + frame_category: str + polarity: Literal["affirms", "falsifies"] + evidence: tuple[MathReaderRefusalEvidencePointer, ...] + replay_evidence: AdmissibilityReplayEvidence | None + review_state: Literal["pending", "accepted", "rejected", "withdrawn"] + operator_note: str + provenance: MathProposalProvenance | None +``` + +This is deliberately not a `TeachingChainProposal` because its evidence floor +is not cognition corpus evidence. + +It is also deliberately not a runtime frame registry entry. It is a proposal. + +--- + +## Evidence floor + +A `MathFrameClaimProposal` 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 `FrameClaim`, +5. an allowlisted `frame_category`, +6. `boundary_clean=True`, and +7. `polarity in {"affirms", "falsifies"}`. + +Audit evidence must include enough provenance to replay the claim: + +- case id +- sentence index +- token/span index when available +- missing operator +- refusal reason/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. + +--- + +## Replay gate + +The adapter uses the math-domain replay gate: + +```text +run_admissibility_replay_gate +``` + +Replay remains a precondition, not permission. + +If replay regresses any protected metric, the proposal auto-transitions to +`rejected` with an `auto_rollback_regression` note. + +If replay passes, the proposal remains `pending` until explicit operator +review. + +--- + +## Accepted proposal effect + +Accepting a `MathFrameClaimProposal` may only append or propose append to a +reviewed frame mapping artifact. + +It must not directly mutate: + +- active runtime state +- solver code +- parser code +- graph verifier code +- arithmetic semantics +- 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 | surface_form | frame_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. + +--- + +## 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. + +It may share infrastructure patterns from ADR-0057, but not evidence identity. + +--- + +## 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 frame 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 +- recognized-but-uninjectable remains refused unless fully admitted correctly + +--- + +## Non-goals + +This ADR does not implement: + +- FrameClaim runtime admission +- frame mapping artifact schema +- workbench rendering +- CompositionClaim +- ReferenceClaim +- SlotClaim +- reviewed math corpus substrate +- automatic acceptance + +This is only the bridge decision that makes future FrameClaim implementation +compatible with ADR-0057. + +--- + +## Decision summary + +> Use a dedicated `MathFrameClaimProposal` adapter for math-domain FrameClaim +> 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 frame artifact under deterministic replay gates.