core-labs/core
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
core/docs/decisions/README.md
Shay 4ba1ef2da3 feat(adr-0043): Phase-2 pack measurements — claims → numbers 
Converts the load-bearing claims of the ADR-0027→0042 pack-layer chain
into CI-enforced numbers across the three ratified identity packs
(default_general_v1, precision_first_v1, generosity_first_v1).

Two new pack-driven runners + an orchestrator:

- evals/identity_divergence/pack_runner.py — drives real
  SentenceAssembler + SurfaceContext (no mocks) across all three
  packs over 10 cases × 5 alignment bands; publishes per-pack
  bare/hedge/qualifier rates and pairwise distinct_rate.

- evals/refusal_calibration/pack_runner.py — runs the existing
  grounding-refusal lane via RuntimeConfig(identity_pack=...);
  publishes per-pack refusal_rate/fabrication_rate and a
  pack_invariant_gate flag asserting byte-identical cold-start
  surfaces across packs.

- scripts/publish_pack_measurements.py — combined publisher
  emitting evals/results/phase2_pack_measurements.json.

Baseline numbers (2026-05-17):
- precision_first hedge_rate=0.60, qualifier_rate=0.20
- generosity_first hedge_rate=0.20, qualifier_rate=0.00
- default_general hedge_rate=0.40, qualifier_rate=0.00
- pairwise distinct_rate ∈ [0.40, 0.80]
- refusal_rate=1.00, fabrication_rate=0.00 for all three packs
- pack_invariant_gate=True

6 tests in tests/test_pack_measurements_phase2.py lock the schema +
load-bearing flags + the structural inequality
precision.hedge_rate > generosity.hedge_rate. If identity packs
get wired into the cognition gate, pack_invariant_gate flips and
the suite fails.

ADR-0043 documents the numbers, the extended marker rationale, and
the trade-offs. README index updated with ADR-0043 row and chain
title bumped to "ADR-0027 through ADR-0043".

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-17 22:19:24 -07:00

11 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-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-0043

ADR-0027 through ADR-0043 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.

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

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