core-labs/core
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
core/docs/decisions/README.md
Shay e705f27d2e
docs(ADR-0164,0165): incremental comprehension reader + regex scope rule (#317) 
Replace the regex sentence-template front-end of the math admissibility
layer with an incremental compositional reader. Lock the architectural
boundary that regex is permitted only at the lexeme level, never as
sentence-structure templates.

ADR-0164 (Proposed) — Incremental Comprehension Reader. Word-by-word
state accumulation over a closed set of semantic categories, with the
operational lexicon living as a pack-shaped data artifact under
language_packs/data/en_core_math_v1/. Reader output type matches the
existing regex parser's output, so the binding-graph admissibility
(ADR-0132/0133/0134/0135), the solver (ADR-0116), and the verifier
(ADR-0117) stay unchanged. wrong=0 is preserved by construction —
the reader produces inputs to the existing admissibility gate, not a
bypass around it. Phased coexistence with the regex layer during
transition; regex sentence templates removed in Phase 3.

ADR-0165 (Proposed) — Regex Scope Rule. Structural invariant: regex
matches one piece of orthographic material with a closed rule
(currency literal, fraction literal, percentage, time-amount, closed
unit-noun sets), never a sentence shape. Lexeme-primitive registry is
closed and grown through the same contemplation -> proposal -> HITL
review corridor that grows vocabulary (ADR-0150 / 0152 / 0155 / 0161).
The engine acquires new recognition tools through reviewed teaching,
not through operator edits to parser code.

ADR-0163's diagnosis (front-end is the bottleneck) is reaffirmed.
Its Phase B-E prescription (regex DerivedRecognizers via
recognizer_match.py) is partially superseded by ADR-0164. ADR-0136
and its S-family (S.1 / S.2 / S.3 / S.4) have the same disposition:
regex sentence-template prescription superseded; empirical refusal
taxonomies and closed-set vocabulary preserved as lexicon seed.
The HITL corridor architecture is preserved; what flows through it
changes from regex recognizers to lexicon entries, categories, and
lexeme primitives.

Session log SESSION-2026-05-26-comprehension-reader.md captures the
narrative of how this decision emerged from the post-D.2 train-sample
baseline review (correct=3 refused=47 wrong=0, 34/47 refusals at the
question gate).

No runtime code changes. ADRs only.
2026-05-26 19:23:05 -07:00

22 KiB
Raw Blame History

Architecture Decision Records

This directory contains the Architecture Decision Records (ADRs) for the CORE project.

ADRs record significant architectural decisions: what was decided, why, what alternatives were considered, and what consequences follow. They are permanent records — superseded ADRs are archived, not deleted.

Index

ADR Title Status
ADR-0080 Contemplation Loop Accepted (2026-05-22)
ADR-0091 Domain Pack Contract v1 Accepted (2026-05-22)
ADR-0092 Reviewer Registry v1 Accepted (2026-05-22)
ADR-0093 Domain Pack Contract v1 implementation Accepted (2026-05-22)
ADR-0094 Proposal Source Provenance Accepted (2026-05-22)
ADR-0095 Miner-Sourced Teaching Proposals Accepted (2026-05-22)
ADR-0096 Fabrication-Control Eval Lane Accepted (2026-05-22)
ADR-0097 Mathematics-Logic Reasoning-Capable Ratification Accepted (2026-05-22)
ADR-0098 Demo Composition Contract Accepted (2026-05-22)
ADR-0099 Public Showcase Demo Accepted (2026-05-22)
ADR-0100 Physics Reasoning-Capable Ratification Accepted (2026-05-22)
ADR-0101 Systems-Software Reasoning-Capable Ratification Accepted (2026-05-22)
ADR-0102 Hebrew-Greek Textual-Reasoning Reasoning-Capable Ratification Accepted (2026-05-22)
ADR-0103 Fluency Lane Attachment for ADR-0102 Accepted (2026-05-22)
ADR-0104 Curriculum-Sourced Teaching Proposals Accepted (2026-05-22)
ADR-0105 Sealed Holdout Encryption via age Accepted (2026-05-22)
ADR-0106 Expert-Demo Promotion Contract Accepted (2026-05-22)
ADR-0107 mathematics_logic Expert-Demo Promotion — Deferred Accepted (2026-05-22)
ADR-0108 Proposed-ADR Sequencing Post-ADR-0105 Accepted (2026-05-22)
ADR-0109 Lane-Shape-Aware Thresholds (ADR-0106 Amendment) Accepted (2026-05-22)
ADR-0110 mathematics_logic Expert-Demo Promotion Accepted (2026-05-22)
ADR-0111 physics Expert-Demo Promotion Accepted (2026-05-22)
ADR-0112 Runnable Audit-Passed Showcase (originally "Expert-Demo") Accepted (2026-05-22)
ADR-0113 Rename expert-demo → audit-passed; Reserve expert for Future Capability Tier Accepted (2026-05-22)
ADR-0114 Expert-Capability Roadmap: GSM8K-Math First Proposed (2026-05-22)
ADR-0114a Anti-Overfitting Proof Obligations for expert Promotion Accepted (2026-05-22)
ADR-0115 Math Problem Parser and Typed Proposition Graph Phase 1.1+1.2+1.3 Accepted (2026-05-22)
ADR-0116 Deterministic Solver (MathProblemGraph → SolutionTrace) Accepted (2026-05-22)
ADR-0117 SolutionTrace Verifier (independent of solver) Accepted (2026-05-22)
ADR-0118 Stepped Realizer (SolutionTrace → Prose) Accepted (2026-05-22)
ADR-0118a OOD Surface Generator for GSM8K-Style Parser Dev Accepted (2026-05-22)
ADR-0122 systems_software Audit-Passed Promotion: Deferred Accepted (2026-05-22)
ADR-0123 symbolic_logic Lane-Shape Remap (ADR-0109 Amendment) Accepted (2026-05-22)
ADR-0124 systems_software Audit-Passed Promotion Accepted (2026-05-22)
ADR-0123a all_three_pass_rate Synonym in inference_shape (ADR-0109 Amendment) Accepted (2026-05-22)
ADR-0125 Reasoning-Isolation Perturbation Suite Accepted (2026-05-22)
ADR-0119 GSM8K Eval Lane Roadmap (Phase 5; decomposes into 5.1..5.8) Proposed (2026-05-22)
ADR-0119.1 Seal fabrication_control Holdout (ADR-0105 Amendment) Accepted (2026-05-23)
ADR-0119.2 GSM8K Eval Corpus Dev/Public Splits Accepted (2026-05-22)
ADR-0119.3 gsm8k_math Lane Runner (Phase 5.3) Accepted (2026-05-22)
ADR-0119.4 GSM8K Math: Frontier-Baseline Comparison (ADR-0114a §Obligation #7) Accepted (2026-05-22)
ADR-0119.5 GSM8K Math Adversarial Generation (ADR-0114a Obligation #8) Accepted (2026-05-23)
ADR-0119.6 GSM8K Math Depth-Curve Measurement Harness Accepted (2026-05-23)
ADR-0119.7 Sealed GSM8K Test Set as gsm8k_math Holdout Accepted (2026-05-23)
ADR-0119.8 gsm8k_math Overall Lane Gate (gsm8k_capability_shape) Accepted (2026-05-23)
ADR-0120 First expert Promotion Contract (composes ADR-0114a 10/10) Proposed (2026-05-23)
ADR-0121 mathematics_logic expert Promotion — Deferred (first attempt) Accepted (2026-05-23)
ADR-0122 Parser Expansion: Rate / Per-Unit Reasoning (substrate-only; lift deferred) Accepted (2026-05-22)
ADR-0123 Comparison-Phrasing Realizer (surface increment on the ADR-0123 substrate; _compare_additive_sentence + _compare_multiplicative_sentence) Accepted (2026-05-23)

Current frontier

The ADR-0091..0114 slate is fully accepted (0091..0113) plus one proposed-roadmap entry (0114) and mechanically evidenced:

  • Domain Pack Contract v1 — ADR-0091
  • Reviewer Registry v1 — ADR-0092
  • Domain Contract v1 enforcement — ADR-0093
  • Proposal Source Provenance — ADR-0094
  • Miner-Sourced Teaching Proposals — ADR-0095
  • Fabrication-control negative eval lane — ADR-0096
  • mathematics_logic reasoning-capable ratification — ADR-0097
  • Demo Composition Contract — ADR-0098
  • Public Showcase Demo — ADR-0099
  • physics reasoning-capable ratification — ADR-0100
  • systems_software reasoning-capable ratification — ADR-0101
  • hebrew_greek_textual_reasoning multi-pack reasoning-capable ratification — ADR-0102
  • Hebrew/Greek fluency lane attachment for ADR-0102 — ADR-0103
  • Curriculum-Sourced Teaching Proposals — ADR-0104
  • Sealed Holdout Encryption via age — ADR-0105
  • Expert-Demo Promotion Contract — ADR-0106
  • mathematics_logic Expert-Demo Promotion deferred (first attempt) — ADR-0107
  • Proposed-ADR Sequencing — ADR-0108
  • Lane-Shape-Aware Thresholds (ADR-0106 amendment) — ADR-0109
  • mathematics_logic Expert-Demo Promotion (first successful) — ADR-0110
  • physics Expert-Demo Promotion (second successful) — ADR-0111
  • Runnable Audit-Passed Showcase (originally "Expert-Demo"; renamed) — ADR-0112 + ADR-0113
  • Rename expert-demo → audit-passed; reserve expert namespace — ADR-0113
  • Expert-Capability Roadmap (GSM8K-Math first); proposed — ADR-0114
  • Math Problem Parser & Typed Graph (Phase 1.1 schema + 5 seeds + Phase 1.2 45 more cases + Phase 1.3 parser engine; 50/50 byte-equal) — ADR-0115
  • Anti-Overfitting Proof Obligations for any future expert promotion (10-point falsifiable framework) — ADR-0114a
  • Deterministic Solver (Phase 2; SolutionTrace + en_arithmetic_v1 pack; discharges ADR-0114a obligations #3, #4, #9, #10) — ADR-0116
  • SolutionTrace Verifier (Phase 3; solver-independent replay; lifts ADR-0114a Obligation #3 to verifier fidelity) — ADR-0117
  • OOD Surface Generator (150 deterministic variants; discharges ADR-0114a obligation #2 for the GSM8K-style parser dev lane) — ADR-0118a
  • Stepped Realizer (Phase 4; SolutionTrace → show-your-work prose; substrate for ADR-0119 GSM8K eval lane) — ADR-0118
  • symbolic_logic Lane-Shape Remap (ADR-0109 amendment) — ADR-0123
  • systems_software Audit-Passed Promotion (third successful) — ADR-0124
  • all_three_pass_rate Synonym in inference_shape (ADR-0109 Amendment) — ADR-0123a
  • Reasoning-Isolation Perturbation Suite (224 deterministic applicable semantic perturbations; discharges ADR-0114a obligation #5 for the GSM8K-style parser dev lane) — ADR-0125
  • GSM8K Eval Lane Roadmap (Phase 5; decomposes into 5.1..5.8; proposed) — ADR-0119
  • Seal fabrication_control Holdout (ADR-0105 Amendment) — ADR-0119.1
  • GSM8K Eval Corpus Dev/Public Splits (200 CORE-original cases; verify.py 200/200; sealed holdout placeholder reserved for ADR-0119.7) — ADR-0119.2
  • gsm8k_math Lane Runner (Phase 5.3; correct/wrong/refused triple; wrong==0 gate; current: 200/200 correct on dev+public) — ADR-0119.3
  • GSM8K Math: Frontier-Baseline Comparison (citations for Claude 3.5, GPT-4, Gemini 1.5; comparison_v1.json; discharges ADR-0114a §Obligation #7) — ADR-0119.4
  • GSM8K Math Depth-Curve Measurement Harness (discharges ADR-0114a Obligation #6 measurement-side) — ADR-0119.6
  • Sealed GSM8K Test Set (1,319 cases age-encrypted; one-way seal; first honest CORE-vs-real-GSM8K measurement: 0/1319 correct, 0 wrong — ADR-0114a Obligation #4 holds against external corpus) — ADR-0119.7
  • GSM8K Math Adversarial Generation (38 cases × 12 families; closes ADR-0114a Obligation #8; misparse rate 0/38; 10 of 10 obligations now discharged on main) — ADR-0119.5
  • gsm8k_math Overall Lane Gate (Phase 5.8; new gsm8k_capability_shape in LANE_SHAPE_REGISTRY; composes wrong==0 + correct+refused==total + overall_pass; live dev 50/50 + public 150/150 pass) — ADR-0119.8
  • First expert Promotion Contract (composes all 10 ADR-0114a obligations + correct_rate ≥ 0.60 floor + depth-curve ε=0.05 + signed expert_claims; proposed; ADR-0121 the first worked attempt) — ADR-0120
  • First expert Promotion Attempt — mathematics_logic — DEFERRED (mirrors ADR-0107 → ADR-0110 pattern for audit-passed; all 10 obligations pass; correct_rate gate refuses honestly at 0/1319; parser-expansion arc is the named unlock; wrong == 0 discipline holds against external benchmark) — ADR-0121
  • Parser-Expansion Arc — first class shipped (rate/per-unit) as substrate-only with lift deferred (Rate dataclass + apply_rate operation kind + parser/solver/verifier/realizer + en_arithmetic_v1:apply_rate pack lemma; 41 invariants pinned; sealed correct_rate stays at 0/1319 with wrong == 0; multi-construction barrier documented — every real GSM8K rate problem combines rate with ≥1 other class, so per-ADR lift signal is corrected to cumulative-after-3rd-or-4th-class) — ADR-0122
  • Parser-Expansion Arc — comparison-phrasing class shipped fully end-to-end as substrate (PR #155 feat/adr-0123-substrate: Comparison dataclass + compare_additive/compare_multiplicative operation kinds + parser patterns for N more/N fewer/twice/N times/half + solver/verifier wiring + en_arithmetic_v1:compare_additive + en_arithmetic_v1:compare_multiplicative pack lemmas) + surface (this ADR: _compare_additive_sentence + _compare_multiplicative_sentence realizer helpers wired into _step_sentence; parse_problem → solve → realize operates end-to-end on all four comparison shapes); sealed correct_rate stays at 0/1319 with wrong == 0 (multi-construction barrier holds; cumulative lift signal expected after the 3rd/4th class lands) — ADR-0123
  • Phase 5 complete (2026-05-22): All ADR-0119 sub-phases (5.1..5.8) landed; ADR-0114a 10/10 obligations discharged for the gsm8k_math lane on main; first honest CORE-vs-real-GSM8K measurement published (0/1319 correct, 0 wrong, 1319 refused); ADR-0120 (first expert promotion contract) is the next gate.

ADR-0080 has also landed: Contemplation Loop Phase 1 adds a read-only frontier-compare miner that emits SPECULATIVE findings only.

Seven lanes are SHA-pinned in scripts/verify_lane_shas.py and gated by the lane-shas GitHub Actions workflow:

  • reviewer_registry
  • domain_contract_validation
  • miner_loop_closure
  • curriculum_loop_closure
  • fabrication_control_summary
  • demo_composition
  • public_demo

Proposed-but-unimplemented ADRs

Sequencing per ADR-0108. Listed in priority order:

  1. ADR-0084 — Definitional Layer for Lexicon Packs. Optional per-entry definitional block. Deferred — value surfaces during a worked expert promotion that needs definitional depth.
  2. ADR-0087 — Rhetorical Style Axis. A third substantive selection axis sibling to anchor-lens. Lowest current priority — no active downstream consumer; register + anchor-lens already demonstrate the orthogonality pattern.

ADR-0080 (Contemplation Loop, Phase 1), ADR-0110 (math audit-passed), ADR-0111 (physics audit-passed), and ADR-0124 (systems_software audit-passed) have all landed — mathematics_logic, physics, and systems_software are at audit_passed=true; the contemplation loop emits read-only SPECULATIVE findings from frontier_compare reports. The remaining ratified domain (hebrew_greek_textual_reasoning) needs its own promotion ADR.

ADR-0122 attempted systems_software promotion and deferred honestly on a lane-shape contract mismatch (symbolic_logic output shape vs registered checker), resolved by ADR-0123's shape remap and successfully promoted via ADR-0124.

Open candidate directions (no ADR yet)

  • Multi-reviewer holdout governance and threshold signing. ADR-0105 seals holdout payloads with a single recipient identity; multi-reviewer governance remains future work.

Accepted reasoning-capable domains

Per ADR-0106, audit_passed is contract-gated, not threshold-only: a domain row may carry audit_passed=true only when a reviewer-signed audit_passed_claims entry exists whose evidence-bundle digest reproduces byte-for-byte. ADR-0107 attempted the first worked promotion and the contract refused; ADR-0109 amended the threshold rules; ADR-0110 then successfully promoted mathematics_logic (the first domain at audit_passed=true); ADR-0111 promoted physics second without further contract change, retiring the "math-only" objection. The other two ratified domains remain at reasoning-capable pending their own promotion ADRs.

Domain Ratification ADR Pack(s) Evidence summary
mathematics_logic ADR-0097 + ADR-0110 en_mathematics_logic_v1 All nine ADR-0091 predicates pass; ledger row is audit-passed (first such promotion, ADR-0110); all three attached lanes meet ADR-0109 shape thresholds on public + holdout.
physics ADR-0100 + ADR-0111 en_physics_v1 All nine predicates pass; causal/modal operator coverage meets threshold; ledger row is audit-passed (second such promotion, ADR-0111); foundational_physics_ood 117/117 public + 39/39 holdout; shares inference_closure + fabrication_control results with math (distinct digest via domain_id).
systems_software ADR-0101 + ADR-0124 en_systems_software_v1 All nine predicates pass; transitive/causal operator coverage meets threshold; ledger row is audit-passed (third promotion, ADR-0124); all three attached lanes meet thresholds on public + holdout.
hebrew_greek_textual_reasoning ADR-0102 + ADR-0103 grc_logos_micro_v1, grc_logos_cognition_v1, he_logos_micro_v1, he_core_cognition_v1 First multi-pack ratification; all four packs carry uniform contract fields; causal/contradiction operator coverage meets threshold; ADR-0103 attaches Hebrew and Koine Greek fluency lanes with dev/public/holdout coverage.

ADR chain notes

Forward Semantic Control closure — ADR-0022 through ADR-0026

ADR-0022 through ADR-0026 form a single coherent chain that closes forward semantic control as a non-stochastic, replay-deterministic, trace-evidenced mechanism.

  1. ADR-0022 establishes AdmissibilityRegion and the contract that a region restricts the admissible token set at generation time.
  2. ADR-0023 records proof evidence that the admissibility region is honored at the region-intersection level.
  3. ADR-0024 adds destination-side per-step admissibility and honest InnerLoopExhaustion when all admissible candidates are rejected.
  4. ADR-0025 adds rotor/frame admissibility when a region carries a frame_versor.
  5. ADR-0026 replaces static threshold tuning with ranked admissibility and a scale-invariant margin gate.

Runtime contracts for the chain are pinned in docs/runtime_contracts.md.

Pack-layer chain — ADR-0027 through ADR-0045

ADR-0027 through ADR-0045 establish the identity / safety / ethics pack architecture with deterministic remediation, audit completeness, telemetry, operator readout, audit-tour demo, pack measurements, a worked-example medical ethics pack, and long-context comparison measurements.

Evidence-governed domain chain — ADR-0091 through ADR-0111

ADR-0091 through ADR-0111 establish the current domain-ratification substrate and the audit-passed promotion gate that distinguishes contract-passing from demonstrated:

contract definition (0091)
    ↓
reviewer trust root (0092)
    ↓
validator / ledger enforcement (0093)
    ↓
negative-control fabrication lane (0096)
    ↓
reasoning-capable domain ratification (0097 / 0100 / 0101 / 0102)
    ↓
language-specific fluency lane attachment (0103)
    ↓
audit-passed promotion contract (0106 + 0109 amendment)
    ↓
worked audit-passed promotion (0110 — mathematics_logic, first)
    ↓
worked audit-passed promotion (0111 — physics, second; no contract change)

No domain claim should be treated as mature merely because a pack exists. reasoning-capable means the nine ADR-0091 predicates pass; audit-passed requires a reviewer-signed evidence-bundle digest that reproduces byte-for-byte from on-disk lane results.

The contract has been demonstrated end-to-end: refused once honestly (ADR-0107), amended once cleanly (ADR-0109), succeeded against mathematics_logic (ADR-0110), and succeeded against physics without further contract change (ADR-0111).

Comprehension-reader pivot — ADR-0164 and ADR-0165 (2026-05-26)

The GSM8K admissibility front-end is replaced. The regex sentence-template parsing layer in generate/math_candidate_parser.py and generate/recognizer_match.py is recognized as overfitting by construction — it enumerates memorized surface shapes while pretending to encode a closed grammar that English does not have.

  • ADR-0164 — Incremental Comprehension Reader. Word-by-word state accumulation over a closed set of semantic categories. The reader is a deterministic shift-reduce parser over categories, not over tokens. Output type is identical to the regex parser's output, so the binding-graph admissibility (ADR-0132/0133/0134/0135) downstream is unchanged. Operational lexicon lives in language_packs/data/en_core_math_v1/ alongside the existing packs.

  • ADR-0165 — Regex Scope Rule. Structural invariant: regex is permitted only at the lexeme level (currency literal, fraction literal, percentage literal, time-amount, closed-set unit-noun), never at the sentence-structure level. The primitive set is a closed registry grown through the same contemplation → proposal → HITL review corridor that grows vocabulary.

These ADRs preserve every load-bearing piece of the prior work: the binding graph (ADR-0132–0135), the solver / verifier / realizer substrate (ADR-0116–0118), the capability-axis lanes G1–G5 and S1, the HITL corridor (ADR-0150 / 0152 / 0155 / 0161), the wrong = 0 doctrine and the replay-equivalence gate (ADR-0057, ADR-0114a). The contemplation → proposal → review corridor architecture is reaffirmed and its scope is generalized: it now ratifies lexicon entries, categories, and lexeme primitives — not regex recognizers.

ADR-0163's diagnosis (the front-end is the bottleneck) is reaffirmed; its prescription (Phases B–E recognizer production) is partially superseded. ADR-0136 and its S-family have the same disposition.

Session Logs

Session logs record the decisions and rationale from individual working sessions. They are not ADRs — they are the narrative record that informed the ADRs.

Date File
2026-05-12 SESSION-2026-05-12.md
2026-05-12 (addendum) SESSION-2026-05-12-b.md
2026-05-12 (language packs) SESSION-2026-05-12-language-packs-addendum.md
2026-05-13 SESSION-2026-05-13.md
2026-05-26 (comprehension reader) SESSION-2026-05-26-comprehension-reader.md