core-labs/core
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
core/docs/decisions/README.md
Shay bf7f7895fe feat(adr-0061): PROCEDURE intent routes to pack-grounded surface 
Pre-ADR-0061 every "How do I X?" question fell through to the
universal disclosure even when X was a pack-resident lemma.  The
teaching corpus carries CAUSE/VERIFICATION chains only — procedural
knowledge is fundamentally different in kind from propositional
claims and deserves its own ratification path (deliberately out of
scope; a future parallel `procedure_chains_v1.jsonl` schema is
discussed in the ADR's non-goals).

ADR-0061 adds the honest cold-start fallback: ground the topic in
pack semantic_domains and note explicitly that ratified step-by-step
guidance does not exist yet.

Surface format:
  "procedure-grounded ({pack_id}): {lemma} ({d1}; {d2}).
   Step-by-step guidance for {lemma} is not yet ratified
   in this session."

Selector — **last** pack-resident lemma in the verb-phrase subject:
  "define a concept" → concept    (object beats verb)
  "verify a claim"   → verify     (verb wins when object is OOV)
  "correct an error" → correct
  "learn this"       → learn
  "do stuff"         → None       (falls through to universal disclosure)

Stopwords: only `be` and `have` (dialogue fillers).  Procedure verbs
are deliberately NOT stopworded so the verb-as-fallback rule fires
when the object is OOV — keeps surface coverage.

Trust-boundary invariants:
  - Every visible non-template token is lemma / pack-domain / template.
  - Deterministic: same subject_text → same bytes.
  - Returns None for fully-unknown utterances → universal disclosure
    fires.  Never fabricates surface from nothing (ADR-0053 contract).
  - "not yet ratified" trust-label preserved.

Cognition lane lift:
  public  : intent 100% / surface 100% / term 91.7% / versor 100%      (unchanged)
  holdout : intent 100% / surface 94.7%→100.0% / term 79.2%→83.3% / versor 100%

Two cases fixed:
  - procedure_define_010 ("How do I define a concept?") — surface +
    term `concept` now captured.
  - procedure_verify_034 ("How do I verify a claim?") — surface only
    (case has no expected_terms; the verb fallback grounds it).

Combined effect: holdout `surface_groundedness` closes to 100%; 4 of
5 architectural holdout misses now resolved (this ADR + ADR-0060 +
the supersede from epistemology v1).  Remaining 2 are UNKNOWN-intent
cases (unknown_spirit_041, unknown_word_018) — out of scope; deserve
their own ADR with distinct selector semantics.

- chat/pack_grounding.py — `_extract_procedure_topic_lemma` helper +
  `pack_grounded_procedure_surface` composer.
- chat/runtime.py — import + dispatch branch for `IntentTag.PROCEDURE`.
- tests/test_procedure_surface.py — 15 tests pin: extraction
  (last-wins / verb-by-elimination / be+have skipped / None on empty /
  strips punctuation / case-insensitive); surface (contains lemma /
  contains domains / pack_id / "not yet ratified" label / None for
  no-pack-lemma / deterministic); end-to-end through ChatRuntime.

Lanes (regression): smoke 67 / cognition 121 / teaching 17 /
procedure 15 — all green.

The non-negotiable field invariant (versor_condition < 1e-6) is
unaffected: this ADR changes surface composition only.
2026-05-18 14:22:19 -07:00

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