core-labs/core
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
core/docs/decisions
History
Shay 226f14a941 feat(adr-0040): structured-logging sink for turn-event audit 
Adds the canonical JSONL sink surface consuming TurnEvent records
that ADR-0039 made uniform across main and stub paths.  One
deterministic line per turn; redact-by-default trust boundary;
opt-in content emission; runtime auto-emits on attached sink.

Trust boundary (CLAUDE.md):
- Metadata-only by default — no surfaces or input tokens emitted.
  include_content=True opt-in at attachment time.
- Path fixed at construction for JsonlFileSink; no user-controlled
  paths interpreted at emit time.
- Sink errors propagate — telemetry failures should surface, not
  silently drop audit signal.

Determinism:
- sort_keys=True; compact separators. Same event → byte-identical line.
- No implicit wall-clock; timestamps caller-provided.
- Field set fixed; missing TurnEvent attrs fall back to safe defaults.

API:
- serialize_turn_event(event, **kwargs) -> dict  (pure)
- format_turn_event_jsonl(event, **kwargs) -> str (pure, deterministic)
- TurnEventSink Protocol; JsonlBufferSink; JsonlFileSink
- ChatRuntime.attach_telemetry_sink(sink, *, include_content=False)
- _emit_turn_event invoked after both turn_log.append sites

Wire format (alphabetised, always present): cycle_cost_total,
dialogue_role, ethics_pack_id, ethics_runtime_checkable_count,
ethics_upheld, ethics_violated, flagged, hedge_injected,
identity_pack_id, refusal_emitted, safety_pack_id,
safety_runtime_checkable_count, safety_upheld, safety_violated,
stub_path, turn, vault_hits, versor_condition.

Conditional: identity_* (when score present), surface /
walk_surface / articulation_surface / input_tokens (when
include_content=True), timestamp (when provided).

Files:
- chat/telemetry.py (new) — serializer, formatter, sinks
- chat/runtime.py — attach + emit + post-append calls
- tests/test_telemetry_sink.py (new) — 29 tests
- docs/decisions/ADR-0040-telemetry-sink.md (new)

Verification:
- Combined pack-layer + telemetry suite: 199 green (was 170 after
  ADR-0039; +29)
- CLI suites unchanged: smoke 67, runtime 19, cognition 121
- core eval cognition: intent 100%, versor_closure 100% (baseline)
2026-05-17 21:39:58 -07:00
..
ADR-0001-vocab-layer-invariants.md
ADR-0002-ingest-layer-design.md
ADR-0003-coordinate-system-dissolution.md
ADR-0004-rotor-as-operator-not-property.md
ADR-0005-language-pack-contract.md
ADR-0006-field-energy-operator.md ADR-0006: wire energy recomputation into propagate_step, add test_energy.py, mark ADR Implemented 2026-05-14 12:39:49 -07:00
ADR-0007-valence-layer.md
ADR-0008-allocation-physics.md
ADR-0009-compositional-physics.md
ADR-0010-identity-physics.md
ADR-0011-renderer.md
ADR-0012-core-ingest-governance-layer.md
ADR-0013-sensorium-multimodal-protocol.md
ADR-0014-train-learning-loop.md
ADR-0015-language-packs-and-holonomy-resonance.md
ADR-0016-capability-roadmap.md feat(evals): Phase 0 — benchmark methodology lock-in and eval framework 2026-05-15 22:36:53 -07:00
ADR-0017-agency-scope.md docs(adr): resolve Agency + Tool-use scope decisions (ADR-0017, ADR-0018) 2026-05-16 14:51:42 -07:00
ADR-0018-tool-use-scope.md docs(adr): resolve Agency + Tool-use scope decisions (ADR-0017, ADR-0018) 2026-05-16 14:51:42 -07:00
ADR-0019-exact-vault-recall-acceleration.md feat(phase4): long-context-cost lane + ADR-0019 Stage 1 vault recall vectorisation 2026-05-16 16:39:30 -07:00
ADR-0020-phase5-rust-parity-sequencing.md perf(rust): versor_apply f64 parity port — 29x over Python, bit-identical 2026-05-16 20:43:01 -07:00
ADR-0021-epistemic-grade-policy.md docs(adr): ADR-0021 Epistemic Grade Policy — coherence is the only signal 2026-05-16 17:10:58 -07:00
ADR-0022-forward-semantic-control.md feat(adr-0022): Forward Semantic Control — Accepted 2026-05-17 12:10:20 -07:00
ADR-0023-forward-semantic-control-proof.md feat(adr-0023): Forward Semantic Control proof evidence — Accepted 2026-05-17 12:55:19 -07:00
ADR-0024-inner-loop-admissibility.md feat(adr-0024): Phase 1 addendum — retire v1/dev fixture rot 2026-05-17 14:43:34 -07:00
ADR-0025-rotor-frame-admissibility-design-note.md feat(adr-0025): Phase 4 — rotor / frame admissibility at the seam 2026-05-17 15:16:32 -07:00
ADR-0026-ranked-admissibility-with-margin.md feat(adr-0026): Phase 3 — ranked admissibility with margin 2026-05-17 15:03:03 -07:00
ADR-0027-identity-packs.md feat(identity-packs): ADR-0028 — pack-driven hedge & claim-strength shaping 2026-05-17 19:42:54 -07:00
ADR-0028-identity-surface-wiring.md feat(identity-packs): ADR-0028 — pack-driven hedge & claim-strength shaping 2026-05-17 19:42:54 -07:00
ADR-0029-safety-packs.md feat(safety): ADR-0029 — always-loaded, never-replaceable safety pack 2026-05-17 19:56:29 -07:00
ADR-0030-depth-language-hedge.md feat(surface): ADR-0030 — depth-language hedge wiring 2026-05-17 20:05:45 -07:00
ADR-0031-score-decomposition-surface.md feat(surface): ADR-0031 — score-decomposition surface (per-axis hedges) 2026-05-17 20:16:22 -07:00
ADR-0032-safety-check-surface.md feat(safety): ADR-0032 — SafetyCheck structural surface 2026-05-17 20:25:22 -07:00
ADR-0033-ethics-packs.md feat(adr-0033): ethics packs — third pack-layer sibling to identity + safety 2026-05-17 20:41:04 -07:00
ADR-0034-ethics-check-surface.md feat(adr-0034): EthicsCheck — structural surface parallel to SafetyCheck 2026-05-17 20:46:34 -07:00
ADR-0035-turn-loop-verdict-surfacing.md feat(adr-0035): turn-loop auto-invocation — surfacing only 2026-05-17 20:57:33 -07:00
ADR-0036-safety-refusal-policy.md feat(adr-0036): safety-only typed refusal policy 2026-05-17 21:10:52 -07:00
ADR-0037-per-predicate-ethics-refusal.md feat(adr-0037,adr-0038): per-predicate ethics refusal + hedge injection 2026-05-17 21:23:28 -07:00
ADR-0038-hedge-injection.md feat(adr-0037,adr-0038): per-predicate ethics refusal + hedge injection 2026-05-17 21:23:28 -07:00
ADR-0039-audit-completeness.md feat(adr-0039): audit completeness — TurnVerdicts bundle, stub TurnEvent, hedge_injected 2026-05-17 21:32:46 -07:00
ADR-0040-telemetry-sink.md feat(adr-0040): structured-logging sink for turn-event audit 2026-05-17 21:39:58 -07:00
README.md docs: ADR-0024 chain coverage across README, ADR index, contracts, papers 2026-05-17 16:28:54 -07:00
SESSION-2026-05-12-b.md
SESSION-2026-05-12-language-packs-addendum.md
SESSION-2026-05-12.md
SESSION-2026-05-13.md

README.md

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

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