core-labs/core
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
core/docs/decisions/README.md
Shay b5ba9b6d6f feat(adr-0064): cross-pack teaching chains + relations_chains_v1 seed (Phase 1.3+1.4) 
ADR-0064 is the corpus-layer sibling of ADR-0063.  The teaching-grounded
surface composer was hardcoded to cognition_chains_v1, so kinship CAUSE/
VERIFICATION prompts fell through to the universal disclosure even though
en_core_relations_v1 was mounted on the live runtime (ADR-0063).

Architectural change in chat/teaching_grounding.py:

  - New TeachingCorpusSpec dataclass (corpus_id, path, pack_id).
  - TEACHING_CORPORA tuple registers every active corpus.  Each
    corpus is 1:1-bound to one lexicon pack — cross-domain triples
    deferred per docs/teaching_order.md §5.
  - _load_corpus(spec) loads one corpus with pack-residency scoped
    to its declared pack.
  - _all_chains_index() aggregates across all registered corpora
    (first-match-wins; cognition first preserves byte-identity).
  - _pack_for_corpus(corpus_id) → bound pack lexicon.
  - clear_teaching_caches() atomic cache invalidation.
  - TeachingChain gains corpus_id field → surface tag follows resolving corpus.

Wiring updates:

  - teaching_grounded_surface + teaching_grounded_surface_composed
    consult _all_chains_index; surface tag follows chain.corpus_id.
  - teaching/discovery.py gate uses chat.pack_resolver.is_resolvable
    (any mounted pack) + _all_chains_index (any registered corpus).
  - teaching/replay.py _swap_corpus_path rewrites the registry path
    + clears all teaching caches during the gate's transient phase.
    Active corpus bytes unchanged (replay invariant preserved).
  - evals/learning_loop/run_demo.py scene-5 swap mirrors the new
    pattern so the demo still grounds against transient corpora.

Back-compat preserved: _corpus_index, _CORPUS_PATH, TEACHING_CORPUS_ID
remain cognition-corpus-specific for audit/replay consumers.

Phase 1.4 — relations_chains_v1 seeded with 7 reviewed kinship chains:
  cause_parent_precedes_child
  cause_child_follows_parent
  cause_ancestor_precedes_descendant
  cause_descendant_follows_ancestor
  cause_family_grounds_parent
  verification_child_requires_parent
  verification_descendant_requires_ancestor

5 of 8 relations lemmas covered.  All connectives already humanised.
Strict pack-internal to en_core_relations_v1 (no cross-domain in v1).
Seed pattern matches cognition_chains_v1's original pre-ADR-0055 seed.

Live verification:
  > Why does parent exist?
  parent — teaching-grounded (relations_chains_v1):
  kinship.ascendant.direct; kinship.parent.
  parent precedes child (kinship.descendant.direct).
  grounding_source = teaching

Cognition eval byte-identical to pre-ADR baseline:
  public:  intent 100% / surface 100% / term 91.7% / closure 100%
  holdout: intent 100% / surface 100% / term 83.3% / closure 100%

Lanes green: smoke 67 / cognition 121 / teaching 17 / packs 6 /
runtime 19 / algebra 132 / full 1933 passed.
2026-05-18 16:04:20 -07:00

20 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-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-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