core-labs/core
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
core/docs/decisions/README.md
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

5.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-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