core/docs/decisions

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-0051	Trust-boundary hardening pass	Accepted (2026-05-18)
ADR-0052	Teaching-grounded surface for cold-start CAUSE / VERIFICATION	Accepted (2026-05-18)
ADR-0053	Cognition lane closure: dev-driven corpus expansion + CORRECTION acknowledgement	Accepted (2026-05-18)
ADR-0054	Vault recall matrix-cache indexing + batched API; holdout split wired into eval CLI	Accepted (2026-05-18)
ADR-0055	Inter-session memory: reviewed discovery promotion (phased design — DiscoveryCandidate, TeachingChainProposal, replay-equivalence gate); Phase A + Phase B Accepted	Phase A + B Accepted; C–E Proposed (2026-05-18)
ADR-0056	Contemplation loop (Phase C1): question decomposition, polarity (affirms/falsifies/undetermined), claim_domain typing (factual/relational/evaluative), sync-only by design	Accepted (2026-05-18, implemented 4eecf73)
ADR-0057	Teaching-chain proposal + review + replay-equivalence gate (Phase C2): the only path to active-corpus extension; eligibility predicate; auto-reject on metric regression; operator accept/reject/withdraw; append-only proposal log	Accepted (2026-05-18)
ADR-0058	forward_graph_constraint remains opt-in default-False; no identity pack flips it on; ADR-0047 null-lift on cognition lane promoted to CI-enforced invariant (regression test); identity-pack→RuntimeConfig composition deferred until at least one such preference shows lift	Accepted (2026-05-18)
ADR-0059	ChatRuntime.correct() emits a discriminated "type": "correction" JSONL event to the existing telemetry sink with target_turn, records_count, turn_idxs_affected, max_delta_norm, mean_delta_norm, SHA-256 correction-versor digest, pack ids — no raw versor coordinates; deterministic; no-op without sink	Accepted (2026-05-18)
ADR-0060	CORRECTION acknowledgement surface weaves the first pack-resident topical lemma from the utterance (left-to-right, excluding correction itself and be/have fillers) into a fixed template; backward-compatible with ADR-0053 (no-arg path byte-identical); closes correction_truth_040 holdout miss; holdout term_capture_rate 75.0% → 79.2%	Accepted (2026-05-18)
ADR-0061	PROCEDURE intent ("How do I X?") routes to new pack_grounded_procedure_surface; selector picks last pack-resident lemma from verb-phrase subject (object > verb), falls back to verb when object is OOV, returns None (→ universal disclosure) for no-pack-lemma utterances; closes procedure_define_010 (term concept) + procedure_verify_034 (surface); holdout surface_groundedness 94.7% → 100.0%; term_capture_rate 79.2% → 83.3%	Accepted (2026-05-18)
ADR-0062	Composed teaching-grounded surface: when a chain (A, intent_A, conn_A, B) has a follow-up chain (B, ?, conn_B, C), emit "{A} {conn_A} {B}, which {conn_B} {C}" instead of just "{A} {conn_A} {B}"; depth-1 (one hop) + cycle guard + pack-residency guard; degrades to single-chain byte-identically when no follow-up survives the guards; opt-in via RuntimeConfig.composed_surface=False default; cognition lane null-drop invariant (metrics byte-identical flag OFF/ON) CI-pinned	Accepted (2026-05-18)
ADR-0067	Cross-pack teaching chains (Plan Phase 4): chat/cross_pack_grounding.py + teaching/cross_pack_chains/cross_pack_chains_v1.jsonl seeded with 5 reviewed chains; each chain carries explicit subject_pack_id + object_pack_id, loader verifies per-chain residency, same-pack entries rejected (anti-leakage); fall-through after in-pack composer in CAUSE/VERIFICATION (cognition-lane byte-identity preserved); NARRATIVE + EXAMPLE composers merge cross-pack chains into multi-clause aggregation with widened corpus tag (e.g. cognition_chains_v1 + cross_pack_chains_v1); first cross-domain edges (family grounds identity, identity requires family, etc.) — relations × cognition; no prose generation, no new mutation surface, supersession honoured	Accepted (2026-05-18)
ADR-0066	Turn-level composition (Plan Phase 3): bounded session-thread context (P3.1) + opt-in deterministic anaphora prefix (Recalling turn N: chain X.) (P3.2, default off) + IntentTag.NARRATIVE multi-clause composer for "Tell me about X" walking every chain rooted on X across registered corpora (P3.3) + IntentTag.EXAMPLE reverse-chain composer for "Give me an example of X" surfacing chains where X is the object (P3.4); no prose generation, no new corpus mutation, all composers consult ADR-0064's cross-corpus aggregator; cognition lane byte-identical	Accepted (2026-05-18)
ADR-0065	OOV gradient + relations v2 (Plan Phase 2): five-tier honesty gradient replaces the OOV cliff — pack / teaching / partial (one OOV + one known) / oov (learning invitation surface naming the unknown token + mounted-pack list) / universal disclosure; sink-emit OOVCandidates → core teaching oov-gaps aggregator → core teaching oov-queue auto-promotion mirrors P1.1+P1.2 architecture for vocab gaps; en_core_relations_v2 adds 8 pronoun + role-filler lemmas (mother/father/son/daughter/brother/sister/grandparent/grandchild) with 7 reviewed v2-internal chains; no content synthesis, no domain inference, no auto-pack-mutation	Accepted (2026-05-18)
ADR-0064	Cross-pack teaching chains: chat/teaching_grounding.py registers a tuple of TeachingCorpusSpec(corpus_id, path, pack_id); each corpus is 1:1-bound to one lexicon pack (cross-domain triples deferred per teaching_order.md §5); new _all_chains_index() aggregates across registered corpora (first-match-wins); surface composers + discovery gate consult the aggregated view; TeachingChain gains corpus_id field; surface tag follows the resolving corpus id; replay-equivalence gate rewrites registry path during transient phase; relations_chains_v1 seeded with 7 reviewed kinship chains; cognition lane byte-identical	Accepted (2026-05-18)
ADR-0063	Cross-pack surface resolver: chat/pack_resolver.py introduces resolve_lemma(lemma, pack_ids) that maps a lemma to (resolving_pack_id, semantic_domains) across an ordered tuple of mounted lexicon packs (first-match-wins); pack-grounded DEFINITION / RECALL / COMPARISON / CORRECTION / PROCEDURE composers now consult the resolver instead of a hardcoded en_core_cognition_v1; surface trust-boundary tag follows the resolving pack id; en_core_relations_v1 joins RuntimeConfig.input_packs defaults — kinship lemmas now ground on the live path without a separate composer module; cognition-lane surfaces remain byte-identical (cognition is resolved first)	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:

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

---

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