core-labs/core
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
core/docs/decisions/README.md
Shay 36053317be
feat(capability): implement ADR-0109 lane-shape-aware thresholds (#116) 
Replaces the cognition-shape-uniform threshold dispatch in
core/capability/expert_demo.py with an explicit LANE_SHAPE_REGISTRY
mapping 8 ratified lane ids to 5 shapes:

  cognition           -> cognition_shape
  elementary_math_ood -> accuracy_shape
  foundational_physics_ood -> accuracy_shape
  symbolic_logic      -> symbolic_logic_shape
  hebrew_fluency      -> accuracy_shape
  koine_greek_fluency -> accuracy_shape
  inference_closure   -> inference_shape
  fabrication_control -> refusal_shape

Each shape has a documented threshold checker. Unknown lane ids
fail-closed with a named reason. ADR-0106 \xc2\xa71.1/\xc2\xa71.3/\xc2\xa71.4/\xc2\xa71.5
unchanged; only \xc2\xa71.2 (threshold rules) dispatches by shape.

tests/test_lane_shape_thresholds.py pins all four ADR-0109 invariants
plus dead-shape and threshold-value gates (13 new tests).
tests/test_expert_demo_contract.py fixtures updated to provide
shape-appropriate metrics (no semantic change to those tests; same
12 cases still pin the ADR-0106 contract).

ADR-0109 status: Proposed -> Accepted. README sequencing updated
(ADR-0110 now only blocked by inference_closure, not by metric-shape
amendment).

Ledger: all five domains remain reasoning-capable, expert_demo=false.
2026-05-22 12:11:58 -07:00

9 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-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)

Current frontier

The ADR-0091..0105 slate is fully accepted 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

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-0110 (reserved) — mathematics_logic expert-demo re-attempt. ADR-0109 has landed; the metric-shape blocker is cleared. The remaining blocker is inference_closure substantively passing (currently all_pass_rate=0.4 on public).
  2. ADR-0080 — Contemplation Loop. Sandboxed, read-only Phase 1 self-interrogation; emits SPECULATIVE findings from frontier_compare reports. Converts gap-finding from human-driven to system-emitted-and-reviewed.
  3. ADR-0084 — Definitional Layer for Lexicon Packs. Optional per-entry definitional block. Deferred — value surfaces during a worked expert promotion that needs definitional depth.
  4. 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.

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, expert_demo is contract-gated, not threshold-only: a domain row may carry expert_demo=true only when a reviewer-signed expert_demo_claims entry exists whose evidence-bundle digest reproduces byte-for-byte. ADR-0107 attempted the first worked promotion (mathematics_logic) and the contract refused — recording two evidence-side blockers now reserved for follow-up as ADR-0109 (lane-shape amendment) and ADR-0110 (re-attempt). All four ratified domains sit at expert_demo=false.

Domain Ratification ADR Pack(s) Evidence summary
mathematics_logic ADR-0097 en_mathematics_logic_v1 All nine ADR-0091 predicates pass; ledger row is reasoning-capable; expert_demo remains false; lanes include positive coverage, inference closure, and fabrication control.
physics ADR-0100 en_physics_v1 All nine predicates pass; causal/modal operator coverage meets threshold; ledger row is reasoning-capable; expert_demo remains false.
systems_software ADR-0101 en_systems_software_v1 All nine predicates pass; transitive/causal operator coverage meets threshold; ledger row is reasoning-capable; symbolic_logic is the v1 closest-fit eval lane.
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-0103

ADR-0091 through ADR-0103 establish the current domain-ratification substrate:

contract definition
    ↓
reviewer trust root
    ↓
validator / ledger enforcement
    ↓
negative-control fabrication lane
    ↓
reasoning-capable domain ratification
    ↓
language-specific fluency lane attachment

No domain claim should be treated as mature merely because a pack exists. Capability status belongs to the generated ledger and its evidence predicates.

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