core-labs/core
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
core/docs/decisions/ADR-0168.1-math-frameclaim-proposal-adapter.md

6.9 KiB
Raw Blame History

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 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:

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:

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:

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:

@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:

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:

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:

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

Idempotency

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

Recommended identity:

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.