core-labs/core
core-labs/core
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
core/docs/audit/substrate-liveness-registry.md
Shay bdde8b4c2a
audit(L0): algebra primitives — CLOSED (#235) 
First per-layer audit of the substrate-liveness program. Establishes the
registry shape and standard of evidence for subsequent layers.

L0 (algebra primitives) is foundation; verdict CLOSED:

- 4 ADRs in scope (ADR-0001 versor invariant, ADR-0003 coordinate
  dissolution, ADR-0004 rotor as operator, ADR-0009 compositional
  physics).
- 6 modules (versor, rotor, cga, cl41, holonomy, backend); every
  module has at least 2 live-import sites outside the package and
  outside tests (38 distinct caller files overall).
- core test --suite algebra exercises every L0 module: 82 passed, 50
  skipped (Rust-parity tests, Python-only env — not a closure gap).
- Cross-layer contract pass 1 (mechanical): every exposed symbol has
  at least one downstream consumer.
- Cross-layer contract pass 2 (semantic): versor_condition < 1e-6
  invariant is measured per turn (core/cognition/trace.py:34), folded
  into deterministic trace payload, surfaced to operator via CLI, and
  gated at the eval boundary (evals/cognition/runner.py:60). Matches
  CLAUDE.md discipline of "measure and surface, don't weaken."

No cleanup performed — no dead code, no redundant modules, no
orphaned tests found at L0. Foundation is honest.

One scope-hypothesis correction: layering table cited "algebra/backend/"
(directory); reality is "algebra/backend.py" (file). Hypothesis drift,
recorded for amendment if it matters elsewhere.

Three forward-pointing notes left for downstream auditors:
- L1 should verify field propagation correctness is tested
  independently of L5's downstream versor_condition measurement.
- L2 should verify vault honors exact-CGA-recall end-to-end, not just
  at the algebra layer.
- ADR-0020 (Rust parity) is cross-cutting; audit when Rust integration
  is live rather than at any single layer.

Format established for subsequent per-layer commits. Audit progress
table in registry root tracks pending layers; resume-after-interruption
is "look at the progress table, start with the first pending layer."
2026-05-24 16:14:57 -07:00

191 lines
9.1 KiB
Markdown
Raw Blame History

# Substrate Liveness Registry
**Scope:** [substrate-liveness-audit-scope](../decisions/substrate-liveness-audit-scope.md) (v2)
**Status:** Active audit — append-only as layers are completed.
**Discipline:** [feedback-adr-cross-reference-discipline](../../../.claude/projects/-Users-kaizenpro-Projects-core/memory/feedback-adr-cross-reference-discipline.md), [feedback-cleanup-as-you-find](../../../.claude/projects/-Users-kaizenpro-Projects-core/memory/feedback-cleanup-as-you-find.md)
## Audit progress
| Layer | Status | Verdict | Cleanup performed | Last audited |
|---|---|---|---|---|
| L0 — Algebra primitives | ✅ Audited | **CLOSED** | None — no dead code found | 2026-05-24 |
| L1 — Field substrate | ⏳ Pending | — | — | — |
| L2 — Vault | ⏳ Pending | — | — | — |
| L3 — Language packs | ⏳ Pending | — | — | — |
| L4 — Recognition | ⏳ Pending | — | — | — |
| L5 — Cognition pipeline | ⏳ Pending | — | — | — |
| L6 — Chat runtime + surface composition | ⏳ Pending | — | — | — |
| L7 — Teaching loop | ⏳ Pending | — | — | — |
| L8 — Inter-session memory + contemplation | ⏳ Pending | — | — | — |
| L9 — Epistemic state + verdicts | ⏳ Pending | — | — | — |
L10 / L11 are not audit targets (no design to audit; flagged in scope as
gaps the audit will surface need for).
---
## L0 — Algebra primitives
**Audit date:** 2026-05-24
**Auditor:** primary agent (Claude)
**Verdict:** **CLOSED**
### Scope-hypothesis correction (per audit step 0)
The scope's layering table cited `algebra/backend/` (directory). Reality:
`algebra/backend.py` (single 267-line file). Hypothesis drift, not a
finding — recorded so the scope's layering map can be amended if it
matters elsewhere.
### ADRs in scope for L0
Triaged from the broader algebra/versor/CGA keyword grep against
`docs/decisions/`:
| ADR | Title | Status | Belongs at L0? |
|---|---|---|---|
| ADR-0001 | VocabManifold Versor Invariant | Accepted | Yes — defines the `versor_condition < 1e-6` invariant L0 must preserve |
| ADR-0003 | Coordinate System Dissolution | Accepted | Yes — algebraic foundation |
| ADR-0004 | Rotor as Operator, Not Vocabulary Property | Accepted | Yes — defines rotors as L0 primitives |
| ADR-0009 | Compositional Physics | Accepted | Yes — versor composition rules |
Other ADRs surfaced by the grep but assigned to higher layers (not
audited at L0): ADR-0006 (L1), ADR-0019 (L2), ADR-0010 (L3 identity),
ADR-0021/0022/0023/0024/0025 (L5 policy), ADR-0020 (cross-cutting Rust
parity, audit when relevant).
### Modules in scope for L0
| Module | Lines | Live-import sites (outside `algebra/`, outside `tests/`) | Test-import sites |
|---|---|---|---|
| `algebra/__init__.py` | 5 | (re-export shim) | — |
| `algebra/backend.py` | 267 | 21 | 16 |
| `algebra/cga.py` | 84 | 16 | 17 |
| `algebra/cl41.py` | 165 | 8 | 10 |
| `algebra/holonomy.py` | 100 | 2 | 5 |
| `algebra/rotor.py` | 179 | 5 | 8 |
| `algebra/versor.py` | 180 | 20 | 19 |
Every module has at least 2 live-import sites outside `algebra/`. No
dormant modules at L0.
### Caller-trace evidence
Sample of live callers (full grep: `grep -rn "from algebra\|import algebra" --include="*.py" | grep -v "^algebra/" | grep -v "tests/"` — 38 distinct caller files):
- `field/propagate.py:23` — versor application during field propagation (L1 → L0)
- `ingest/gate.py:33` — versor/energy at injection boundary (L1 → L0)
- `language_packs/compiler.py:14` — versor construction during pack compilation (L3 → L0)
- `chat/runtime.py` — versor operations in the live turn loop (L6 → L0)
- `generate/intent_ratifier.py`, `generate/admissibility.py`, `generate/proposition.py` — versor-gated generation (L5 → L0)
- `core/cli.py:446-469` — versor diagnostics surfaced to operator (CLI → L0)
Every live caller traces back to the runtime entry through at least one
of: `core chat`, `core eval cognition`, or the field/ingest pipeline.
### Exercising suite lane
`core test --suite algebra` — 13 test files, every L0 module covered:
| Module | Tests in algebra suite |
|---|---|
| `versor.py` | test_versor_closure, test_holonomy, test_energy, test_motor, test_versor_condition_rust_parity, test_versor_apply_rust_parity |
| `rotor.py` | test_versor_closure, test_energy |
| `holonomy.py` | test_holonomy, test_holonomy_resonance |
| `cga.py` | test_holonomy_resonance, test_null_cone, test_vault_recall |
| `cl41.py` | test_vault_recall_vectorised |
| `backend.py` | test_vault_recall_vectorised, test_vault_recall_rust_parity, test_cga_inner_rust_parity, test_geometric_product_rust_parity, test_versor_condition_rust_parity, test_versor_apply_rust_parity |
**Verification:** `python3 -m core.cli test --suite algebra -q` →
**82 passed, 50 skipped** (skipped are Rust-parity tests on a Python-
only environment; not a closure gap).
### Cross-layer contract check
**Pass 1 — mechanical (consumer-exists per exposed symbol):**
| Exposed symbol | Consumer evidence |
|---|---|
| `versor_apply` | `field/propagate.py`, `generate/stream.py`, `chat/runtime.py` (3+ live consumers) |
| `versor_condition` | `core/cognition/trace.py:34`, `evals/cognition/runner.py:60` (gated in evals at `< 1e-6`) |
| `normalize_to_versor` | `generate/intent_ratifier.py`, `generate/admissibility.py` |
| `cga_inner` | `vault/store.py`, `algebra/backend.py` (`_CGA_INNER_METRIC`), `evals/lab/vault_epistemic_trace.py` |
| `embed_point`, `is_null`, `null_project` | `vault/store.py`, `language_packs/compiler.py`, `field/operators.py` |
| `using_rust`, `vault_recall` (backend) | `vault/store.py`, all Rust-parity tests |
| `word_transition_rotor`, `make_rotor_from_angle` | `field/operators.py`, `generate/intent_ratifier.py` |
| `holonomy_encode`, `holonomy_similarity` | `vault/store.py`, `evals/lab/` |
| `N_COMPONENTS` (cl41) | `algebra/backend.py`, `algebra/cga.py` |
No exposed L0 symbol with zero downstream consumers.
**Pass 2 — semantic (judgment-required):**
ADR-0001's `versor_condition < 1e-6` invariant is the primary semantic
contract. Verified:
- **Measured per turn:** L0's `versor_condition()` is computed and
folded into the deterministic trace payload (`core/cognition/trace.py:34,70`)
on every turn.
- **Surfaced to operator:** displayed by `core chat` and `core` info
commands (`core/cli.py:398,461,469`).
- **Gated at eval boundary:** evals refuse to count a turn as
`versor_ok` if `versor_condition >= 1e-6` (`evals/cognition/runner.py:60`,
`evals/run_cognition_eval.py:54`).
- **NOT enforced inline as exception:** a turn with `vc >= 1e-6` still
completes; the violation is visible in trace + eval, not raised as
an error. This matches CLAUDE.md's discipline ("Do not weaken this
threshold to make tests pass. Fix the operator/construction
boundary that violated it.") — violations are surfaced for fix,
not catastrophically refused at runtime.
**Semantic mismatches flagged for human review:** none. The contract
is consistently consumed.
### Closure criteria scorecard
| Criterion | Status | Evidence |
|---|---|---|
| 1. Design artifact | ✅ | ADR-0001, ADR-0003, ADR-0004, ADR-0009 |
| 2. Code artifact | ✅ | `algebra/{backend,cga,cl41,holonomy,rotor,versor}.py` |
| 3. Live caller | ✅ | 38 distinct caller files outside `algebra/` and `tests/` |
| 4. Exercised by suite lane | ✅ | `core test --suite algebra` — 82/82 non-skipped pass; every L0 module covered |
| 5. Cross-layer consistency | ✅ | All exposed symbols consumed; `versor_condition` invariant measured + traced + gated |
**Verdict:** **CLOSED.**
### Cleanup performed
**None.** Audit found no dead, redundant, superseded, or orphaned code
at L0. Every module has live callers; every exposed symbol is consumed;
the suite lane exercises every module; the invariant is preserved
end-to-end.
### Findings / notes for downstream layers
- **L1 (Field substrate) auditor:** L0's `versor_condition` is consumed
at L5 (trace) and at the eval boundary, but L1 itself does not appear
to enforce the invariant — L1's propagation produces field states
that may later violate the invariant, with measurement deferred to
L5. Worth verifying that L1's propagation correctness is itself
tested independently of L5's downstream measurement.
- **L2 (Vault) auditor:** `vault/store.py` is one of the heaviest
consumers of L0 (cga_inner, embed_point, is_null, holonomy_encode).
L2's closure depends on L0's exact-CGA-recall guarantees; the L2
audit should verify the vault honors the exact-match discipline
end-to-end, not just at the algebra layer.
- **L6 (Chat runtime) auditor:** ADR-0020 (Phase 5 / Rust Parity
Sequencing) is cross-cutting; the 50 skipped tests in the algebra
suite are Rust-parity tests skipped in a Python-only environment.
Audit ADR-0020 wherever Rust integration is live (when it lands)
rather than at any single layer.
### Audit method footnote
This entry follows the per-layer audit format established here:
ADRs in scope → modules in scope → caller traces → suite lane
exercise → cross-layer contract (mechanical + semantic) → closure
scorecard → cleanup → notes for downstream. Subsequent layers should
follow the same format so the registry is uniformly machine- and
human-scannable.
---
Reference in a new issue View git blame Copy permalink