core-labs/core
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
core/docs/decisions
History
Shay 3005cd6f9a docs: ADR-0024 chain coverage across README, ADR index, contracts, papers 
Patent-grade precision pass over the doc surface so every claim
about the Forward Semantic Control chain is backed by a file path,
test count, or commit hash.

Updates by file:

README.md
  - Modernize Quick Start: add `core test --suite adr-0024`,
    `core demo phase6 / phase5 / all / list-results`, full CLI map.
  - New "Forward Semantic Control — The ADR-0024 Chain" section
    with layer/ADR mapping and CI-enforced C1/C2/C3 claims table.
  - Cross-links to runtime_contracts.md, phase5_stratified_findings,
    phase6_comparative_demo, and the central results directory.

docs/decisions/README.md
  - Index was stale at ADR-0014.  Add ADR-0015 through ADR-0026
    with accurate Accepted statuses.
  - New "ADR-0024 chain — Forward Semantic Control closure" section
    laying out the five-ADR / six-commit dependency order with test
    counts per phase.

docs/runtime_contracts.md
  - Add "Ranked-with-margin contract (ADR-0026 / Phase 3)" section
    between the existing Phase 2 refusal and Phase 4 rotor sections.
  - Documents threshold-mode vs margin-mode behaviour, δ = 0.4
    default, falsifiability gate, and Cl(4,1) signature motivation.

docs/PROGRESS.md
  - Add naming-note disambiguation: capability-roadmap "Phase N"
    vs ADR-0024 chain "Phase N" are distinct.
  - New top-of-document "ADR-0024 Chain — Forward Semantic Control
    Closure" section with per-phase commit + test-count table and
    a single-command verification path.

docs/Whitepaper.md
  - New Section XII "Forward Semantic Control — Generation Without
    Sampling" before Extensions.  Five-component description of the
    mechanism (region, intersection, destination check, rotor check,
    margin gate) with explicit "what a sampling LLM cannot exhibit"
    contrast.  Existing Section XII renumbered to XIII.

docs/Yellowpaper.md
  - New Section IX-B "Forward Semantic Control — Formal Admissibility
    Specification" with eight subsections covering:
      1. AdmissibilityRegion typed triple (I, B, Φ)
      2. Destination-side admissibility (σ_dest, admit_threshold)
      3. Rotor-side admissibility (σ_rotor, admit_rotor)
      4. Ranked-with-margin gate (admit_margin, deterministic
         tie-break by index, default δ = 0.4)
      5. Honest refusal (InnerLoopExhaustion typed evidence,
         RefusalReason enum, trace fold)
      6. Composition order at the generation seam
         (admit_step = intersection ∧ destination ∧ rotor)
      7. Replay determinism contract (5 test lanes pinning byte
         identity across reruns)
      8. Verification invariants table (6 new structural contracts)
  - Patent-grade: every predicate is named, every module is path-
    referenced, every test is file-referenced, the load-bearing
    architectural placement decision (rotor admissibility lives in
    generate/, NOT algebra/, NOT field/) is stated by name with
    its rejection reasoning.

No code changes; tests untouched (1099 passed, 2 skipped baseline
from commit 36aad75 still holds).
2026-05-17 16:28:54 -07:00
..
ADR-0001-vocab-layer-invariants.md
ADR-0002-ingest-layer-design.md
ADR-0003-coordinate-system-dissolution.md
ADR-0004-rotor-as-operator-not-property.md
ADR-0005-language-pack-contract.md
ADR-0006-field-energy-operator.md ADR-0006: wire energy recomputation into propagate_step, add test_energy.py, mark ADR Implemented 2026-05-14 12:39:49 -07:00
ADR-0007-valence-layer.md
ADR-0008-allocation-physics.md
ADR-0009-compositional-physics.md
ADR-0010-identity-physics.md
ADR-0011-renderer.md
ADR-0012-core-ingest-governance-layer.md
ADR-0013-sensorium-multimodal-protocol.md
ADR-0014-train-learning-loop.md
ADR-0015-language-packs-and-holonomy-resonance.md
ADR-0016-capability-roadmap.md feat(evals): Phase 0 — benchmark methodology lock-in and eval framework 2026-05-15 22:36:53 -07:00
ADR-0017-agency-scope.md docs(adr): resolve Agency + Tool-use scope decisions (ADR-0017, ADR-0018) 2026-05-16 14:51:42 -07:00
ADR-0018-tool-use-scope.md docs(adr): resolve Agency + Tool-use scope decisions (ADR-0017, ADR-0018) 2026-05-16 14:51:42 -07:00
ADR-0019-exact-vault-recall-acceleration.md feat(phase4): long-context-cost lane + ADR-0019 Stage 1 vault recall vectorisation 2026-05-16 16:39:30 -07:00
ADR-0020-phase5-rust-parity-sequencing.md perf(rust): versor_apply f64 parity port — 29x over Python, bit-identical 2026-05-16 20:43:01 -07:00
ADR-0021-epistemic-grade-policy.md docs(adr): ADR-0021 Epistemic Grade Policy — coherence is the only signal 2026-05-16 17:10:58 -07:00
ADR-0022-forward-semantic-control.md feat(adr-0022): Forward Semantic Control — Accepted 2026-05-17 12:10:20 -07:00
ADR-0023-forward-semantic-control-proof.md feat(adr-0023): Forward Semantic Control proof evidence — Accepted 2026-05-17 12:55:19 -07:00
ADR-0024-inner-loop-admissibility.md feat(adr-0024): Phase 1 addendum — retire v1/dev fixture rot 2026-05-17 14:43:34 -07:00
ADR-0025-rotor-frame-admissibility-design-note.md feat(adr-0025): Phase 4 — rotor / frame admissibility at the seam 2026-05-17 15:16:32 -07:00
ADR-0026-ranked-admissibility-with-margin.md feat(adr-0026): Phase 3 — ranked admissibility with margin 2026-05-17 15:03:03 -07:00
README.md docs: ADR-0024 chain coverage across README, ADR index, contracts, papers 2026-05-17 16:28:54 -07:00
SESSION-2026-05-12-b.md
SESSION-2026-05-12-language-packs-addendum.md
SESSION-2026-05-12.md
SESSION-2026-05-13.md

README.md

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-0001 Vocab Layer Invariants Accepted
ADR-0002 Ingest Layer Design (original) Archived — superseded by ADR-0012
ADR-0003 Coordinate System Dissolution Accepted
ADR-0004 Rotor as Operator, Not Property Accepted
ADR-0005 Language Pack Contract Accepted
ADR-0006 Field Energy Operator Accepted
ADR-0007 Valence Layer Accepted
ADR-0008 Allocation Physics Accepted
ADR-0009 Compositional Physics Accepted
ADR-0010 Identity Physics Accepted
ADR-0011 Renderer Accepted
ADR-0012 core_ingest Governance Layer Accepted
ADR-0013 sensorium/ Multimodal Protocol Layer Accepted
ADR-0014 train/ Learning Loop Accepted (Stub)
ADR-0015 Language Packs as Compiled Linguistic Manifolds Accepted
ADR-0016 Capability Roadmap and Eval Methodology Accepted
ADR-0017 Agency Scope: Responsive-with-Axiology Accepted
ADR-0018 Tool Use Scope: Typed Deterministic Operators Accepted
ADR-0019 Exact Vault Recall Acceleration Accepted
ADR-0020 Phase 5 / Rust Parity Sequencing Accepted (2026-05-16)
ADR-0021 Epistemic Grade Policy Accepted
ADR-0022 Forward Semantic Control Accepted (2026-05-17)
ADR-0023 Forward Semantic Control: Proof Evidence Accepted
ADR-0024 Inner-Loop Per-Rotor Admissibility Accepted
ADR-0025 Rotor / Frame Admissibility Accepted (2026-05-17)
ADR-0026 Ranked Admissibility with Margin Accepted (2026-05-17)

ADR-0024 chain — Forward Semantic Control closure

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

  1. ADR-0022 — Forward Semantic Control. Establishes the AdmissibilityRegion data structure (allowed indices, relation blade, frame versor) and the contract that a region restricts the admissible token set at generation time.
  2. ADR-0023 — Proof Evidence. Boundary-only proof that the admissibility region is honored at the region intersection level but not yet at the destination-token level.
  3. ADR-0024 — Inner-Loop Per-Rotor Admissibility. Adds the destination-side check: each per-step selection is re-evaluated by cga_inner(versor(candidate), relation_blade) > threshold, with honest refusal (InnerLoopExhaustion) when every admissible candidate is rejected. Six phases of implementation evidence (Phases 1-6) plus typed RefusalReason taxonomy.
  4. ADR-0025 — Rotor / Frame Admissibility. Adds the rotor-side check: when a region carries a frame_versor, the rotor's effect on the field state (versor_apply(V, F)) is additionally checked against the frame for positivity in CGA inner product. Lives in generate/rotor_admissibility.py — a sibling-but-separate module, not in algebra/versor.py (would couple algebra to pack state) and not in field/propagate.py (forbidden normalization site).
  5. ADR-0026 — Ranked Admissibility with Margin. Replaces static threshold tuning with a scale-invariant margin gate: admit iff the top blade-score exceeds the second by ≥ δ. Defaults to δ = 0.4. Falsifiable; characterization documented in docs/evals/phase5_stratified_findings.md.

Implementation evidence:

Phase Commit Tests
Phase 1 — pack-grounded fixtures 3940290 (rewrites)
Phase 2 — typed refusals + trace fold 310793a +10
Phase 3 — ranked-with-margin gate 639e107 +13
Phase 4 — rotor / frame admissibility 542e13d +11
Phase 5 — stratified mechanism-isolation b664984 +20
Phase 6 — comparative demo vs baseline a076506 +17
CLI surface (suite aliases + core demo) 36aad75 +14

Runtime contracts for the chain are pinned in docs/runtime_contracts.md (Refusal contract, Margin contract, Rotor admissibility contract sections).

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