core-labs/core
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
core/docs/decisions
History
Shay fa05be9293 feat(identity-packs): ADR-0027 — swappable identity manifold via packs 
Replaces the hardcoded IdentityManifold constructor in chat/runtime.py
with a content-addressed pack loader.  Identity is now load-bearing AND
swappable: deployments select an identity pack at startup, downstream
builders (robotics, personalization, creative tools) author their own
ratified packs without editing CORE Python.

Phase 1 — pack format + loader
  * packs/identity/loader.py — load_identity_manifold(pack_id, *,
    search_paths, require_ratified) with bounds checks (axis count,
    direction in [-1, 1], weight in [0, 10], threshold in [0, 1],
    axis-id uniqueness).
  * available_packs() helper for discovery.
  * IdentityPackError raised on every bounds violation.

Phase 2 — three v1 packs
  * default_general_v1.json — ship default; encodes the previous
    hardcoded three axes (truthfulness, coherence, reverence)
    byte-for-byte so existing runtime behavior is preserved.
  * precision_first_v1.json — boosts truthfulness weight, narrows
    coherence/reverence; tighter alignment threshold.
  * generosity_first_v1.json — boosts coherence weight, broadens
    reverence; looser alignment threshold.

Phase 3 — replace hardcoded constructor
  * chat/runtime.py:206 calls load_identity_manifold() using
    RuntimeConfig.identity_pack (default DEFAULT_IDENTITY_PACK).
  * Dead _default_identity_manifold() removed.
  * ChatRuntime.identity_pack_id surfaces the loaded pack id.

Phase 4 — CLI flag
  * core chat --identity <pack_id>  (also threaded into trace/oov via
    _add_runtime_policy_args).
  * core/config.py: RuntimeConfig.identity_pack added; empty string
    falls back to DEFAULT_IDENTITY_PACK = 'default_general_v1'.

Phase 5 — formation ratification — INTENTIONALLY DEFERRED.  Loader
currently calls require_ratified=False so the v1 packs (which carry
empty mastery_report_sha256) load.  Authoring SubjectSpecs for each
pack, running the formation pipeline end-to-end to produce signed
MasteryReports, and embedding the SHA into each pack file is a
follow-up.

Tests: 18 new tests in tests/test_identity_packs.py covering loader
happy paths, every bounds violation, runtime wiring, and pack-swap
divergence.

Suite status: cognition 121, teaching 17, runtime 19, formation 182,
smoke 67 — all green.

Docs: ADR-0027 (Accepted) + docs/identity_packs.md (operational ref) +
README.md §Identity Packs + docs/teaching_order.md Layer 1 cross-ref.
2026-05-17 19:24:39 -07:00
..
ADR-0001-vocab-layer-invariants.md docs: add ADR log and session decision record for 2026-05-12 2026-05-12 20:56:21 -07:00
ADR-0002-ingest-layer-design.md docs: add ADR log and session decision record for 2026-05-12 2026-05-12 20:56:21 -07:00
ADR-0003-coordinate-system-dissolution.md docs: add ADR log and session decision record for 2026-05-12 2026-05-12 20:56:21 -07:00
ADR-0004-rotor-as-operator-not-property.md docs: add ADR log and session decision record for 2026-05-12 2026-05-12 20:56:21 -07:00
ADR-0005-language-pack-contract.md docs(decisions): ADR-0005 language pack contract + session addendum [Batch 1] 2026-05-12 21:16:00 -07:00
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 docs: ADR-0006 field energy operator, ADR-0007 valence layer, session addendum 2026-05-12-b 2026-05-12 22:13:29 -07:00
ADR-0008-allocation-physics.md feat(physics): add mind-physics layer — ADR-0008/0009/0010, blueprint, and operator stubs 2026-05-12 23:20:58 -07:00
ADR-0009-compositional-physics.md feat(physics): add mind-physics layer — ADR-0008/0009/0010, blueprint, and operator stubs 2026-05-12 23:20:58 -07:00
ADR-0010-identity-physics.md feat(physics): add mind-physics layer — ADR-0008/0009/0010, blueprint, and operator stubs 2026-05-12 23:20:58 -07:00
ADR-0011-renderer.md chore: fix package name, add core/__init__.py, ADR-0011, session note 2026-05-13 2026-05-13 10:44:42 -07:00
ADR-0012-core-ingest-governance-layer.md docs: add ADR-0012, ADR-0013, ADR-0014, SESSION-2026-05-13 2026-05-13 11:24:10 -07:00
ADR-0013-sensorium-multimodal-protocol.md docs: add ADR-0012, ADR-0013, ADR-0014, SESSION-2026-05-13 2026-05-13 11:24:10 -07:00
ADR-0014-train-learning-loop.md docs: add ADR-0012, ADR-0013, ADR-0014, SESSION-2026-05-13 2026-05-13 11:24:10 -07:00
ADR-0015-language-packs-and-holonomy-resonance.md Document language pack manifold contract 2026-05-13 13:13:06 -07:00
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-0027 — swappable identity manifold via packs 2026-05-17 19:24:39 -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 docs: ADR-0006 field energy operator, ADR-0007 valence layer, session addendum 2026-05-12-b 2026-05-12 22:13:29 -07:00
SESSION-2026-05-12-language-packs-addendum.md docs(decisions): ADR-0005 language pack contract + session addendum [Batch 1] 2026-05-12 21:16:00 -07:00
SESSION-2026-05-12.md docs: add ADR log and session decision record for 2026-05-12 2026-05-12 20:56:21 -07:00
SESSION-2026-05-13.md docs: add ADR-0012, ADR-0013, ADR-0014, SESSION-2026-05-13 2026-05-13 11:24:10 -07:00

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