ecd580479a
Sibling to ADR-0048's DEFINITION/RECALL pack-grounded surface for
the COMPARISON intent. `pack_grounded_comparison_surface(a, b)` in
`chat/pack_grounding.py` composes a deterministic side-by-side
surface from both lemmas' pack `semantic_domains`, joined by the
fixed connective "contrasts with":
"{a} (d_a1; d_a2) contrasts with {b} (d_b1; d_b2) — pack-grounded
({pack_id}). No session evidence yet."
`chat/runtime.py:_maybe_pack_grounded_surface` gains a COMPARISON
branch that runs before the DEFINITION/RECALL check. Engages only
when both `intent.subject` and `intent.secondary_subject` are pack
lemmas and differ (identical-lemma comparison defers to disclosure).
Order-sensitive by design — matches the graph-layer's directional
CONTRAST edge.
Cognition eval (13-case public split):
surface_groundedness 61.5% → 69.2% (+7.7 pp)
term_capture_rate 50.0% → 58.3% (+8.3 pp)
intent_accuracy 100.0% (=)
versor_closure_rate 100.0% (=)
Case lifted: comparison_memory_recall_030 ("Compare memory and
recall"). Remaining unlift cases (CAUSE×2, VERIFICATION×1,
CORRECTION×1) need teaching-store chains or operator-driven
inference — pack lookup cannot supply causal explanations,
verifications, or corrections without fabrication.
Tests: tests/test_pack_grounded_comparison.py (15 tests).
Lanes green: smoke (67), cognition (121), runtime (19), algebra
(132), teaching (17), packs (6).
15 KiB
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-0027 | Identity Packs — swappable, ratified | Accepted (2026-05-17) |
| ADR-0028 | Identity Surface Wiring | Accepted (2026-05-17) |
| ADR-0029 | Safety Packs — never-swappable, fail-closed | Accepted (2026-05-17) |
| ADR-0030 | Depth-Language Hedge | Accepted (2026-05-17) |
| ADR-0031 | Score-Decomposition Surface | Accepted (2026-05-17) |
| ADR-0032 | SafetyCheck Predicate Surface | Accepted (2026-05-17) |
| ADR-0033 | Ethics Packs — third pack tier | Accepted (2026-05-17) |
| ADR-0034 | EthicsCheck Predicate Surface | Accepted (2026-05-17) |
| ADR-0035 | Turn-Loop Verdict Surfacing | Accepted (2026-05-17) |
| ADR-0036 | Safety-Only Typed Refusal | Accepted (2026-05-17) |
| ADR-0037 | Per-Predicate Ethics Refusal Opt-In | Accepted (2026-05-17) |
| ADR-0038 | Hedge Injection as Runtime Affordance | Accepted (2026-05-17) |
| ADR-0039 | Audit Completeness — TurnVerdicts + stub TurnEvent | Accepted (2026-05-17) |
| ADR-0040 | Structured-Logging Sink | Accepted (2026-05-17) |
| ADR-0041 | --show-verdicts + FanOutSink |
Accepted (2026-05-17) |
| ADR-0042 | Audit Tour Demo (core demo audit-tour) |
Accepted (2026-05-17) |
| ADR-0043 | Phase-2 pack measurements — claims → numbers | Accepted (2026-05-17) |
| ADR-0044 | Medical / clinical ethics pack (worked-example domain pack) | Accepted (2026-05-17) |
| ADR-0045 | Long-context recall: CORE vs transformer baselines | Accepted (2026-05-17) |
| ADR-0046 | PropositionGraph as forward AdmissibilityRegion + industry demos | Accepted (2026-05-18) |
| ADR-0047 | Wire forward graph constraint into the chat hot path (opt-in) | Accepted (2026-05-18) |
| ADR-0048 | Pack-grounded surface for cold-start DEFINITION / RECALL | Accepted (2026-05-18) |
| ADR-0049 | Intent classifier head-noun subject extraction | Accepted (2026-05-18) |
| ADR-0050 | Pack-grounded surface for cold-start COMPARISON | Accepted (2026-05-18) |
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:
- ADR-0022 — Forward Semantic Control. Establishes the
AdmissibilityRegiondata structure (allowed indices, relation blade, frame versor) and the contract that a region restricts the admissible token set at generation time. - 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.
- 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 typedRefusalReasontaxonomy. - 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 ingenerate/rotor_admissibility.py— a sibling-but-separate module, not inalgebra/versor.py(would couple algebra to pack state) and not infield/propagate.py(forbidden normalization site). - 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).
Pack-Layer chain — ADR-0027 through ADR-0045
ADR-0027 through ADR-0045 form the second coherent chain in the project: a load-bearing three-tier pack architecture (identity / safety / ethics) with deterministic remediation, full-stream audit, machine-readable telemetry, an operator-facing CLI readout, and an investor-facing walkthrough. Read in order:
| Group | ADRs | What it adds |
|---|---|---|
| Identity | ADR-0027 / ADR-0028 | Identity manifold loads from a swappable JSON pack at composition time. Pack carries surface_preferences that visibly drive hedging and claim strength. |
| Identity surface refinements | ADR-0030 / ADR-0031 | Depth-language hedge; score-decomposition surface. |
| Safety | ADR-0029 / ADR-0032 | Five universal safety boundaries unioned into every runtime manifold; SafetyCheck registry-of-predicates surface (observational). |
| Ethics | ADR-0033 / ADR-0034 | Third pack tier — deployment commitments, swappable like identity but propositional like safety; EthicsCheck predicate surface. |
| Turn-loop wiring | ADR-0035 | Both checks auto-invoked at end of every turn; verdicts attached to ChatResponse and TurnEvent. |
| Remediation tiers | ADR-0036 / ADR-0037 / ADR-0038 | Safety-only typed refusal → per-commitment ethics refusal opt-in → hedge injection. Three tiers per ethics commitment: audit / hedge / refuse. |
| Audit completeness | ADR-0039 | TurnVerdicts bundle + stub-path TurnEvent emission + refusal_emitted / hedge_injected flags. rt.turn_log covers every turn. |
| Machine + operator surfaces | ADR-0040 / ADR-0041 | Structured JSONL sink with redact-by-default trust boundary; FanOutSink composer; core chat --show-verdicts operator readout. |
| Demo | ADR-0042 | core demo audit-tour — four-scene investor-facing walkthrough; test-gated all_claims_supported flag. |
| Phase-2 measurements | ADR-0043 | Pack-driven identity-divergence + refusal-calibration runners convert load-bearing claims into CI-enforced numbers across the three ratified packs; combined report at evals/results/phase2_pack_measurements.json. |
| Worked-example domain pack | ADR-0044 | medical_clinical_ethics_v1 — six commitments across all three remediation tiers (refuse / hedge / audit); ratified end-to-end through scripts/ratify_ethics_pack.py; composes into the runtime manifold alongside the universal safety floor. |
| Long-context comparison | ADR-0045 | CORE exact needle-in-a-haystack measurement at N ∈ {100, 1k, 10k, 100k} paired with frozen transformer baselines (Claude 2.1, GPT-4 Turbo 128k, Gemini 1.5 Pro, RULER); recall_pct=100 for CORE by construction. |
Three sibling pack types compose into every runtime manifold:
identity.boundary_ids ∪ safety.boundary_ids ∪ ethics.commitment_ids → manifold.boundary_ids
Per-commitment ethics policy lives in two opt-in lists on the
ethics pack: refusal_commitments (hard stop) and
hedge_commitments (soft prepend), mutually exclusive at load time.
Safety is always in scope for refusal; the floor never moves.
Verification surface:
| Layer | Tests | Live demo |
|---|---|---|
| Identity packs | tests/test_identity_packs.py, tests/test_identity_surface_divergence.py |
core demo audit-tour Scene 1 |
| Safety pack + refusal | tests/test_safety_pack.py, tests/test_safety_check.py, tests/test_safety_refusal.py |
core demo audit-tour Scene 2 |
| Ethics pack + opt-ins | tests/test_ethics_packs.py, tests/test_ethics_check.py, tests/test_ethics_refusal_opt_in.py, tests/test_hedge_injection.py |
core demo audit-tour Scene 3 |
| Turn-loop verdicts + bundle | tests/test_turn_loop_verdicts.py, tests/test_turn_verdicts_bundle.py |
core chat --show-verdicts |
| Telemetry sink | tests/test_telemetry_sink.py, tests/test_telemetry_fanout_and_summary.py |
core demo audit-tour Scene 4 |
| Audit tour gate | tests/test_audit_tour.py — asserts all_claims_supported |
core demo audit-tour |
Pillar 1 → 2 → 3 coupling — ADR-0046 / ADR-0047
ADR-0046 extends the ADR-0022 → ADR-0026 forward-semantic-control
chain by giving the AdmissibilityRegion a new, geometry-derived
source: the PropositionGraph.
The graph was previously built after generate() ran, from the
walk's nearest-node results — a post-hoc descriptor of what the field
had already produced. ADR-0046 converts each graph's named-node
versors into an AdmissibilityRegion before generate() is
called, via the exact CGA top-k neighbourhood. The walk is now
constrained by the proposition's geometric meaning rather than
described by it after the fact.
geometry (CGA versor neighbourhood)
→ structure (PropositionGraph nodes)
→ propagation (AdmissibilityRegion fed to generate())
Three industry-facing demos under evals/industry_demos/ carry the
falsifiable claims for this coupling. The exact-recall-at-scale claim
remains under ADR-0045 / evals/long_context/, where it is measured
on the real vault path and not duplicated under a weaker construction.
| Layer | Tests | Live demo |
|---|---|---|
| Forward graph constraint (primitive) | tests/test_graph_constraint.py — 8 tests |
python -m evals.industry_demos.demo_01_forward_constraint |
| Forward graph constraint (live wiring) | tests/test_forward_graph_constraint_wiring.py — 5 tests |
RuntimeConfig(forward_graph_constraint=True) then core eval cognition |
| Geometry-driven identity | tests/test_identity_packs.py, tests/test_identity_surface_divergence.py |
python -m evals.industry_demos.demo_02_geometry_drives_identity |
| Architectural determinism | tests/test_telemetry_sink.py, tests/test_telemetry_fanout_and_summary.py |
python -m evals.industry_demos.demo_03_deterministic_audit |
ADR-0047 lands the wire-up behind an opt-in RuntimeConfig flag. The
characterisation it carries (A/B on the public cognition split)
shows the wiring is correct and safe but does not move
surface_groundedness or term_capture_rate on this lane — isolating
the next load-bearing pull to the realizer / surface-assembly path
rather than to propagation.
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 |