docs(adr-0244,adr-0245): D4 Phase 0 — governance reconciliation
Reconciles ADR-0244 against its own D0 blockers and commits ADR-0245 as
a real companion ADR (previously a dangling reference in ADR-0244 §4).
ADR-0244 governance annotation expanded (11 items, all body text below
preserved verbatim for R&D provenance; annotation governs on conflict):
1. Q_top proof (already landed) now explicitly drops the §2.2 egress
ΔQ_top conjunct (it is a hollow, always-true discriminator).
2. §4-vs-§2 contradiction RESOLVED — new §4a is the governing spec;
§4 kept verbatim as the (contradictory) original R&D sketch.
3. §2.1 axis construction was underspecified (packs ship dim-3
directions, not 32-vectors) — resolved via a grade-1 lift at the
e1/e2/e3 slots (algebra.cl41.basis_vector), not embed_point.
4. §2.2 amended: signed overlap (never abs()'d — anti-alignment must
stay distinguishable from orthogonality); leakage norm is the
positive-definite Euclidean coefficient norm, not the indefinite
Cl(4,1) inner product (which (+,+,+,+,-) permits to vanish for
nonzero leakage).
5. Inalienability reframed as 5 testable layers (algebraic / runtime
/ pipeline / operational / semantic) — only the first is a math
guarantee.
6. Paraphrase-invariance reworded as an empirical, measured property;
Q_top conservation scoped to pure versors only (relax_to_ground
can converge to non-versor superpositions — the ADR-0243 SD-A
subtlety).
7. boundary_ids activation (currently stored, never evaluated).
8. Identity manifold is FROZEN — biography holonomy accumulates
separately and never mutates the identity subspace.
9-11. Filename correction (multimodal_lifecycle.py doesn't exist;
real file is cognitive_lifecycle.py), ADR-0245 cross-link,
theological citation labeled ESV + analogy disclaimer.
New §4a supersedes §4 with a typed, Gram/leakage-correct specification
(ManifoldConditioningError, IdentityGateRefusal, bounded/abstaining
C_id, isfinite + shape guards — no bare assert) for Phase 1/2 to build
against under TDD.
ADR-0245 committed Proposed, verbatim from the R&D export, with a
governance annotation mapping its 4 decisions + Sec 3 acceptance gate
against what the cohesion-directive arc already landed (Rust f32 GP,
_cached_eigh, digest hot-path all done; f64->f32 cast + Sec 3's
speedup/collision proofs open — tracked as D4 Phase 4/5).
Audit doc (adr-0244-cohesion-directive-audit-2026-07-17.md) wrinkles
1-2 and Q5 sequencing updated from 'pending'/'must reconcile' to
resolved, cross-referencing this landing.
[Verification]: in-worktree smoke gate 176 passed; provenance/ADR
governance pins (test_adr_0241_governance_p12.py,
test_adr_0242_topological_quarantine.py, test_third_door_cohesion.py)
30 passed — confirms ADR-0244 stays Proposed (no status flip) and no
existing ADR provenance guard was disturbed. Docs-only change, no
executable surface touched.
This commit is contained in:
parent
0f2b8d5e4f
commit
ad37d03b19
4 changed files with 273 additions and 9 deletions
|
|
@ -4,16 +4,27 @@
|
||||||
**Date**: 2026-07-17
|
**Date**: 2026-07-17
|
||||||
**Authors**: Joshua Shay \+ Multi-model R\&D
|
**Authors**: Joshua Shay \+ Multi-model R\&D
|
||||||
**Traceability**: Notion R\&D (CORE Engineering Reference hub: Live-Entity Design Decisions, `core_HA` Patterns)
|
**Traceability**: Notion R\&D (CORE Engineering Reference hub: Live-Entity Design Decisions, `core_HA` Patterns)
|
||||||
**Related**: ADR-0003, ADR-0006, ADR-0010, ADR-0021, ADR-0028, ADR-0031, ADR-0035, ADR-0039, ADR-0238, ADR-0239, ADR-0241, ADR-0242, ADR-0243, `core/physics/identity.py`, `algebra/cl41.py`
|
**Related**: ADR-0003, ADR-0006, ADR-0010, ADR-0021, ADR-0028, ADR-0031, ADR-0035, ADR-0039, ADR-0238, ADR-0239, ADR-0241, ADR-0242, ADR-0243, **ADR-0245** (companion — mechanical-sympathy + semantic-rigor foundation), `core/physics/identity.py`, `algebra/cl41.py`
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
> **Governance annotation (D0 landing, 2026-07-17).** Committed **Proposed**, verbatim from the R&D export, so the record exists — but two load-bearing items are held open for the D4 implementation plan and must be resolved *in this ADR* before any of §2.1–2.3 becomes an in-path egress gate. This annotation is editorial (added at landing); the body below is unchanged.
|
> **Governance annotation (D0 landing 2026-07-17; reconciled at D4 Phase 0, 2026-07-17).** Committed **Proposed**, verbatim from the R&D export, so the record exists. **§1–§4 below are preserved unchanged as the original R&D proposal** — including §4's code sketch, which item 2 below identifies as contradicting the governing decision. This annotation, and the new **§4a** inserted after §4, carry the authoritative engineering reconciliation. Where this annotation disagrees with the body, **this annotation governs**.
|
||||||
>
|
>
|
||||||
> 1. **§2.3 topological charge `Q_top` is PROVEN vacuous (hollow gate) — retire from egress.** In odd Cl(4,1) the pseudoscalar `I₅` is central, so `ψ I₅ ψ̃ = I₅·(ψψ̃)`; for any unit versor `ψψ̃ = 1` (no grade-5 part), hence `Q_top = ⟨I₅⟩₀ = 0` identically. Empirically confirmed (`evals/adr_0244_qtop_vacuity`, pinned by `tests/test_adr_0244_qtop_vacuity.py`): `Q_top = 0.000e+00` exactly across every rotor and boost tested; off the versor manifold `Q_top = −grade₅(ψψ̃)`, nonzero only where the I-05 closure residual already fires; it is a conserved Spin(4,1) invariant but identically 0 on the valid manifold; and the decisive test shows an aligned identity and an adversarially-rotated one (overlap 0.963, a valid versor) **both** read `Q_top = 0`, so `ΔQ_top = 0` passes the attack the spectral-leakage / closure check actually catches. This is the exact failure mode that retired the PR #19 pseudoscalar gate. `Q_top` must **not** be an egress admit condition; keep it, if at all, as a diagnostic derived from the closure check.
|
> 1. **§2.3 topological charge `Q_top` is PROVEN vacuous (hollow gate) — retired from egress.** In odd Cl(4,1) the pseudoscalar `I₅` is central, so `ψ I₅ ψ̃ = I₅·(ψψ̃)`; for any unit versor `ψψ̃ = 1` (no grade-5 part), hence `Q_top = ⟨I₅⟩₀ = 0` identically. Empirically confirmed (`evals/adr_0244_qtop_vacuity`, pinned by `tests/test_adr_0244_qtop_vacuity.py`): `Q_top = 0.000e+00` exactly across every rotor and boost tested; off the versor manifold `Q_top = −grade₅(ψψ̃)`, nonzero only where the I-05 closure residual already fires; it is a conserved Spin(4,1) invariant but identically 0 on the valid manifold; and the decisive test shows an aligned identity and an adversarially-rotated one (overlap 0.963, a valid versor) **both** read `Q_top = 0`, so `ΔQ_top = 0` passes the attack the spectral-leakage / closure check actually catches. This is the exact failure mode that retired the PR #19 pseudoscalar gate. `Q_top` must **not** be an egress admit condition; keep it, if at all, as a diagnostic derived from the closure check. **The §2.2 egress condition's `∧ ΔQ_top = 0` conjunct is dropped** (see item 4).
|
||||||
> 2. **§4 "conformed implementation" contradicts §2.1–2.2.** The §4 code computes a per-axis `|⟨ψ · reverse(axis)⟩₀|` resonance, not the metric-exact **Gram-matrix subspace projection**, the **identity spectral leakage** norm, or the `ManifoldConditioningError` the decision section specifies. It also references a dangling "ADR-0245" and uses a bare `assert` for the byte-order guard (stripped under `-O`; violates this ADR's own typed-failure doctrine). §4 is illustrative only; §2.1–2.2 is the governing decision. The two must be reconciled before implementation.
|
> 2. **§4 "conformed implementation" contradicted §2.1–2.2 — RESOLVED, see §4a.** The §4 code computed a per-axis `|⟨ψ · reverse(axis)⟩₀|` resonance, not the metric-exact **Gram-matrix subspace projection**, the **identity spectral leakage** norm, or the `ManifoldConditioningError` the decision section specifies. It also referenced a then-dangling "ADR-0245" (now real, see item 10) and used a bare `assert` for the byte-order guard (stripped under `-O`; violated this ADR's own typed-failure doctrine). §4 remains illustrative-only, kept verbatim for provenance; **§4a is the governing specification**.
|
||||||
|
> 3. **§2.1 axis eigenmode construction, previously underspecified, is a grade-1 lift.** `IdentityManifold` value axes ship as **dim-3** unit vectors in every existing pack (verified: `packs/identity/default_general_v1.json`); §2.1 assumes each axis is already a 32-component `ψ_axis ∈ Cl(4,1)` and is silent on how. Resolution: lift `direction ∈ R^3` to Cl(4,1) by placing the 3 components at the grade-1 `e1/e2/e3` slots (`algebra.cl41.basis_vector(0..2)`), **not** `algebra.cga.embed_point` (which sends points to the null cone, turning the Gram matrix into a distance table rather than a metric inner product). Orthonormal axes ⇒ `G = I`. See §4a.
|
||||||
|
> 4. **§2.2 egress condition amended.** The `∧ ΔQ_top = 0` conjunct is dropped (item 1 — it is always true, hence vacuous as a discriminator). The per-axis inner product is a **signed** overlap `⟨ψ_axis, ψ⟩₀` — never `abs()`'d; a large negative value is *anti-alignment* (opposition), a materially different and worse condition than orthogonality, and must remain distinguishable from it. The leakage norm `‖S_id‖` is the **positive-definite coefficient-Euclidean norm** `sqrt(Σ_k S_id[k]²)` — explicitly **not** the indefinite Cl(4,1) inner product `⟨S_id, S̃_id⟩₀`, which the (+,+,+,+,−) signature permits to be zero (or negative) for nonzero leakage, silently hiding a breach. Operative score: `score = 1 − ‖S_id‖ / ‖ψ_traj‖`; egress ⟺ `score ≥ manifold.alignment_threshold` (equivalently `‖S_id‖ ≤ γ_id`). See §4a.
|
||||||
|
> 5. **Inalienability is layered, not monolithic.** Only one of the following is a mathematical guarantee; the rest are engineering/governance properties this ADR's *implementation* must make visible, not properties the *algebra alone* confers: **(a) algebraic** — specified rotor/versor transformations provably preserve the chosen invariant (this is what §2.3's conservation argument actually establishes, scoped per item 6); **(b) runtime** — no public/tool/memory/retrieval/generation API can directly overwrite the authoritative identity state; **(c) pipeline** — all cognitive state entering action selection passes through the identity manifold and its gate (D4 Phase 2's wiring target); **(d) operational** — identity definitions, calibration data, and axis bases are versioned, content-addressed, and reviewable (§2.7, D1); **(e) semantic** — adversarial paraphrases and indirect attacks are empirically shown to produce detectable leakage (item 7, D4 Phase 2 eval suite). "Inalienable" in §2's framing means all five hold together, not that (a) alone suffices.
|
||||||
|
> 6. **Paraphrase-invariance reworded.** §2.2 item 1's claim ("completely paraphrase-invariant... as long as the upstream encoder maps semantic equivalents into proximal field states") states its own precondition as a caveat, which is correct but easy to misread as unconditional. Operative claim: *"The identity gate is invariant under transformations that preserve the trajectory's identity-relevant field geometry. Paraphrase robustness is an empirical property of the encoder + propagation pipeline, measured by the D4 Phase 2 eval suite — not a property of the projection operator alone."* Similarly, §2.3's conservation claim holds **only for pure versors** (`R ∈ Spin(4,1)`, `R̃R = 1`); `relax_to_ground` (ADR-0243) can converge to a ground eigenstate that is a multi-grade superposition, not a versor, and the conservation argument does not directly apply there — this is the same subtlety that forced ADR-0243's sketch-defect pin SD-A. §2.3's charge-conservation claim is scoped to the crystallization/vault path where versor closure is already required (ADR-0243 I-05), not asserted of every state the lifecycle produces.
|
||||||
|
> 7. **`boundary_ids` activated.** `IdentityManifold.boundary_ids` is stored but never evaluated by the live `check()` (verified: `core/physics/identity.py`, current `check()` iterates `value_axes` only). D4 Phase 2 activates it as a hard-boundary evaluation alongside the axis-leakage check; the violation predicate is designed in-phase (Phase 2 is the first place boundary semantics are specified in code, not merely stored).
|
||||||
|
> 8. **Identity-continuity: the manifold is FROZEN.** Axis eigenmodes are computed once at manifold/pack load and never mutated within a session. ADR-0243's biography holonomy accumulation (`H_bio ← H_bio · R`) is a separate process and does **not** rewrite the identity subspace. This is what makes "inalienable" true by construction — the subspace a trajectory is checked against cannot itself drift as a side effect of the trajectory being checked.
|
||||||
|
> 9. **Filename correction.** ADR-0245 (item 10) and its R&D commentary reference `core/physics/multimodal_lifecycle.py`; that file does not exist. The real module is `core/physics/cognitive_lifecycle.py` (ADR-0243).
|
||||||
|
> 10. **ADR-0245 is real.** `docs/adr/ADR-0245-cga-unification-mechanical-sympathy-and-semantic-rigor.md`, committed **Proposed** as a companion ADR at D4 Phase 0. It is the mechanical-sympathy + semantic-rigor foundation this ADR's identity gate sits on: Rust `geometric_product` fast-path (its §2.1 ≡ this ADR's §2.6), the f64→f32 serving-boundary cast (its §2.2 ≡ this ADR's §2.5 — one contract, two ADRs), content-addressing rigor (its §2.3 ≡ this ADR's §2.7), and `eigh` memoization (its §2.4 ≡ this ADR's §2.8).
|
||||||
|
> 11. **Theological citation.** The quoted John 1:1–2 text matches the **ESV** (English Standard Version). It is cited as an engineering analogy that makes the architecture legible to humans, not as a scientific or theological proof of the geometric claims in §2.
|
||||||
>
|
>
|
||||||
> Full mandate audit + these decisions: `docs/analysis/adr-0244-cohesion-directive-audit-2026-07-17.md`.
|
> **Governance anchors (ADR-0225).** *Safety/identity boundary:* this ADR defines the identity trust boundary itself — items 4, 7, 8 above are exactly that boundary's shape. *Versor closure:* axis eigenmodes and `ψ_traj` are validated for shape (`N_COMPONENTS`,) and finiteness before projection (§4a); the manifold does not assume `ψ_traj` is itself a unit versor (item 6 — it may be a superposition). *Reconstruction-over-storage:* the manifold stores only axis directions + calibration certificates; `ψ_traj` is read from `final_state.F` per-turn, never duplicated into the manifold. *Replay-equivalence:* the identity gate's fail-closed path must preserve byte-identical output for non-flagged turns (D4 Phase 2 acceptance criterion — the gate is flag-gated off by default until calibrated). *Mutation standing:* the identity manifold is frozen (item 8), never mutated in-path; `C_id`'s corrective displacement acts on the trajectory, never on the manifold.
|
||||||
|
>
|
||||||
|
> Full mandate audit: `docs/analysis/adr-0244-cohesion-directive-audit-2026-07-17.md`. D4 implementation plan + live progress tracker: `docs/handoff/ADR-0244-D4-IMPLEMENTATION-PLAN.md`.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -397,10 +408,103 @@ class IdentityCheck:
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## 4a. D4 Phase 0 — Reconciled Implementation Specification (supersedes §4)
|
||||||
|
|
||||||
|
§4 above is preserved verbatim as the original R&D sketch. Per governance annotation item 2, it contradicts the governing §2.1–2.2 decision and is **not** the specification implementers build against. This section is that specification. It is normative *shape* — the literal shipped code is produced under TDD in D4 Phase 1 (`core/physics/identity_manifold.py`) and Phase 2 (`core/physics/identity.py`); this block is not the final diff.
|
||||||
|
|
||||||
|
**Phase 1 primitive — `core/physics/identity_manifold.py` (§2.1):**
|
||||||
|
|
||||||
|
```python
|
||||||
|
class ManifoldConditioningError(ValueError):
|
||||||
|
"""Gram matrix condition number exceeds the mode-aliasing bound (10**5)."""
|
||||||
|
|
||||||
|
def lift_axis(direction3: tuple[float, float, float]) -> np.ndarray:
|
||||||
|
"""Grade-1 lift: R^3 -> Cl(4,1) at the e1/e2/e3 slots.
|
||||||
|
|
||||||
|
Uses algebra.cl41.basis_vector(0..2) — NOT algebra.cga.embed_point, which
|
||||||
|
maps to null-cone points and would make the Gram matrix a distance table
|
||||||
|
rather than a metric inner product. Precomputed once at manifold load:
|
||||||
|
f64 precision domain (the f64->f32 serving-boundary cast, Sec 2.5 /
|
||||||
|
ADR-0245 Sec 2.2, applies only to the live per-turn psi_traj, not to this
|
||||||
|
offline axis construction).
|
||||||
|
"""
|
||||||
|
psi = np.zeros(N_COMPONENTS, dtype=np.float64)
|
||||||
|
for k, component in enumerate(direction3):
|
||||||
|
psi = psi + component * basis_vector(k).astype(np.float64)
|
||||||
|
return psi
|
||||||
|
|
||||||
|
def gram_matrix(axes_psi: Sequence[np.ndarray]) -> np.ndarray:
|
||||||
|
n = len(axes_psi)
|
||||||
|
G = np.empty((n, n), dtype=np.float64)
|
||||||
|
for i in range(n):
|
||||||
|
for j in range(n):
|
||||||
|
G[i, j] = scalar_part(geometric_product(axes_psi[i], reverse(axes_psi[j])))
|
||||||
|
cond = float(np.linalg.cond(G))
|
||||||
|
if cond > 1e5:
|
||||||
|
raise ManifoldConditioningError(f"Gram condition number {cond:.3e} exceeds 1e5")
|
||||||
|
return G
|
||||||
|
|
||||||
|
def project(psi: np.ndarray, axes_psi: Sequence[np.ndarray], g_inv: np.ndarray) -> np.ndarray:
|
||||||
|
"""P_id(psi) = sum_ij psi_axis_i * (G^-1)_ij * <psi_axis_j, psi>_0 — signed."""
|
||||||
|
c = np.array([scalar_part(geometric_product(reverse(a), psi)) for a in axes_psi])
|
||||||
|
coeffs = g_inv @ c
|
||||||
|
return sum(w * a for w, a in zip(coeffs, axes_psi))
|
||||||
|
|
||||||
|
def leakage_norm(s_id: np.ndarray) -> float:
|
||||||
|
"""Positive-definite coefficient-Euclidean norm — NOT the indefinite Cl(4,1)
|
||||||
|
inner product <S, S~>_0, which signature (+,+,+,+,-) permits to vanish for
|
||||||
|
nonzero leakage, silently hiding a breach (governance annotation item 4)."""
|
||||||
|
return float(np.linalg.norm(s_id, ord=2))
|
||||||
|
```
|
||||||
|
|
||||||
|
**Phase 2 gate — `core/physics/identity.py` (§2.2; dual-mode, fail-closed):**
|
||||||
|
|
||||||
|
```python
|
||||||
|
class IdentityGateRefusal(Exception):
|
||||||
|
"""Fail-closed refusal: leakage or boundary check failed and C_id could not
|
||||||
|
recover alignment within its bound. Live parameters are unchanged."""
|
||||||
|
|
||||||
|
def _axis_projection(axis, psi_traj, axis_psi) -> float:
|
||||||
|
psi_arr = np.ascontiguousarray(psi_traj, dtype=np.float32)
|
||||||
|
if psi_arr.dtype.byteorder not in ("<", "="):
|
||||||
|
raise ValueError("Identity gate requires little-endian float32")
|
||||||
|
if not np.all(np.isfinite(psi_arr)):
|
||||||
|
raise ValueError("Identity gate encountered nonfinite values in psi_traj")
|
||||||
|
if psi_arr.shape != (N_COMPONENTS,):
|
||||||
|
raise ValueError(f"psi_traj must be shape ({N_COMPONENTS},), got {psi_arr.shape}")
|
||||||
|
# Signed overlap — do NOT abs(): a large negative value is anti-alignment
|
||||||
|
# (opposition), a materially worse condition than orthogonality, and must
|
||||||
|
# stay distinguishable from it (governance annotation item 4).
|
||||||
|
return float(scalar_part(geometric_product(psi_arr, reverse(axis_psi))))
|
||||||
|
|
||||||
|
# Malformed psi_traj (NaN / wrong shape / wrong byte-order) raises — it never
|
||||||
|
# falls through to the legacy scalar-L2 path (Sec 3's dual-mode fallback is
|
||||||
|
# for ABSENT psi_traj only, not malformed psi_traj).
|
||||||
|
```
|
||||||
|
|
||||||
|
Egress condition (replaces §2.2 item 2's formula — `∧ ΔQ_top = 0` dropped per governance annotation item 1):
|
||||||
|
|
||||||
|
```
|
||||||
|
psi_minus = F_cognitive(psi_t, u_t)
|
||||||
|
r_id = psi_minus - P_id(psi_minus) # leakage
|
||||||
|
psi_plus = C_id(psi_minus, r_id) # bounded, abstaining corrector
|
||||||
|
admit <=> leakage_norm(psi_plus - P_id(psi_plus)) <= gamma_id
|
||||||
|
```
|
||||||
|
|
||||||
|
`C_id` is a **bounded, abstaining** corrector: it may apply a bounded corrective displacement toward the manifold; if it cannot recover alignment within that bound, it **abstains** — raises `IdentityGateRefusal`, live parameters are kept unchanged. `C_id` must **not** rewrite reasoning arbitrarily to force a low leakage score — a corrector that can do that creates a "good-metric, bad-cognition" failure mode, which is a new defect, not a fix.
|
||||||
|
|
||||||
|
`boundary_ids` (governance annotation item 7) is evaluated as a hard-boundary check alongside the axis-leakage score; a boundary violation is refused independent of the leakage score (its predicate is designed in D4 Phase 2, not prescribed here).
|
||||||
|
|
||||||
|
**Identity-continuity (governance annotation item 8):** `axes_psi` above is computed once at manifold/pack load and frozen for the session. ADR-0243 biography holonomy accumulation is a separate, non-mutating process with respect to this subspace.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 5\. References
|
## 5\. References
|
||||||
|
|
||||||
1. `algebra/cl41.py` — Precomputed geometric product table.
|
1. `algebra/cl41.py` — Precomputed geometric product table.
|
||||||
2. `core/physics/wave_manifold.py` — Continuous wave-field substrate.
|
2. `core/physics/wave_manifold.py` — Continuous wave-field substrate.
|
||||||
3. `core/physics/goldtether.py` — GoldTether residual monitoring.
|
3. `core/physics/goldtether.py` — GoldTether residual monitoring.
|
||||||
4. `core/physics/fibonacci_search.py` — Fibonacci search contract.
|
4. `core/physics/fibonacci_search.py` — Fibonacci search contract.
|
||||||
|
5. `docs/adr/ADR-0245-cga-unification-mechanical-sympathy-and-semantic-rigor.md` — companion mechanical-sympathy + semantic-rigor foundation ADR.
|
||||||
|
6. `docs/handoff/ADR-0244-D4-IMPLEMENTATION-PLAN.md` — D4 implementation plan + live progress tracker.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,160 @@
|
||||||
|
# ADR-0245: CGA Unification — Mechanical Sympathy, Boundary Rigor, and Eigendecomposition Memoization
|
||||||
|
|
||||||
|
**Status**: Proposed (acceptance path: benchmark evidence \+ Joshua review)
|
||||||
|
**Date**: 2026-07-17
|
||||||
|
**Authors**: Joshua Shay \+ Multi-model R\&D
|
||||||
|
**Traceability**: Notion R\&D (CORE Engineering Reference hub: Live-Entity Design Decisions, `core_HA` Patterns)
|
||||||
|
**Related**: ADR-0003, ADR-0006, ADR-0010, ADR-0238, ADR-0241, ADR-0242, ADR-0243, ADR-0244 (companion — identity-gate consumer of this ADR's foundation), `algebra/cl41.py`, `core/physics/wave_manifold.py`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
> **Governance annotation (D4 Phase 0 landing, 2026-07-17).** Committed **Proposed**, verbatim from the R&D export, so the record exists. The body below is unchanged; this annotation is editorial (added at landing) and carries the engineering status map + corrections.
|
||||||
|
>
|
||||||
|
> **Filename correction.** §2 Context and §4 References (item 4) cite `core/physics/multimodal_lifecycle.py`. That file does not exist. The real module implementing the ADR-0243 wave-field cognitive lifecycle is `core/physics/cognitive_lifecycle.py`. All decisions below (§2.2 in particular) apply to that file.
|
||||||
|
>
|
||||||
|
> **Status map — three of four decisions were already landed by the ADR-0244-cohesion-directive arc before this ADR was committed to the repo:**
|
||||||
|
>
|
||||||
|
> | § | Decision | Status |
|
||||||
|
> |---|---|---|
|
||||||
|
> | 2.1 | PyO3 Rust `geometric_product` f32 fast-path | ✅ **Done** — `algebra/backend.py`, pre-existing before this arc. |
|
||||||
|
> | 2.2 | Gated f64→f32 serving boundary | ❌ **Open** — the one genuinely-unbuilt decision. Identical in substance to ADR-0244 §2.5 (same cast, same boundary); tracked as **one contract, two ADRs** — D4 Phase 4. |
|
||||||
|
> | 2.3 | Semantic rigor in content addressing (full 256-bit digest, no `default=str`, byte-order guard) | ◐ **Hot-path done, residual open** — `cognitive_lifecycle.py` / `biography_wiring.py` / `self_authorship.py` fixed (cohesion-directive D1). Three contemplation-module content-id sites (`core/contemplation/schema.py`, `plan_preflight.py`, `miners/articulation_quality.py`) still truncate to 16 hex chars and/or use `default=str` — D4 Phase 5. |
|
||||||
|
> | 2.4 | `_cached_eigh` memoization (`functools.lru_cache`, keyed on `hamiltonian_id` + `matrix.tobytes()`) | ✅ **Done** — `core/physics/cognitive_lifecycle.py::_cached_eigh` (cohesion-directive D2), exactly as specified including the canonical two-part cache key. |
|
||||||
|
>
|
||||||
|
> **§3 acceptance gate — partial:**
|
||||||
|
>
|
||||||
|
> - **Accuracy & parity** (bit-identical Rust vs Python, N=10,000): ✅ done — `tests/test_geometric_product_f64_parity.py::test_rust_f64_gp_is_bit_identical_to_python_n10000` (the f64 kernel; the f32 kernel referenced in §2.1 predates this arc and has its own long-standing parity coverage).
|
||||||
|
> - **Latency & throughput** (≥10× speedup, dense products, Rust vs pure-Python): ❌ **not benchmarked** — no test asserts a speedup ratio. D4 Phase 5 gap.
|
||||||
|
> - **Memory allocations** (`_cached_eigh` ⇒ 0 heap allocations / 0 LAPACK calls on repeat): ◐ partially covered by `tests/test_adr_0244_mechanical_sympathy.py`; full 0-allocation assertion is D4 Phase 5 work.
|
||||||
|
> - **Collision resistance** (`_content_id`, no two distinct metadata dicts collide under the strict path): ❌ **not proven** — D4 Phase 5 gap.
|
||||||
|
>
|
||||||
|
> This ADR's remaining scope (§2.2 cast contract + the four §3 gaps above) is tracked as part of **D4** alongside ADR-0244. See `docs/handoff/ADR-0244-D4-IMPLEMENTATION-PLAN.md` (Phase 4 for §2.2, Phase 5 for the §3 gate) and `docs/analysis/adr-0244-cohesion-directive-audit-2026-07-17.md` for the prior mandate audit that landed §2.1/§2.3(hot-path)/§2.4.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1\. Context and Problem Statement
|
||||||
|
|
||||||
|
With the continuous wave-field substrate ($\\psi \\in Cl(4,1)$) of [ADR-0241](https://drive.google.com/file/d/1F_7QYtPysBP4qMbLGlGPnXgYx9IXug8nUYrpiCGSunE/view?usp=drivesdk), the deterministic Fibonacci-section search of [ADR-0242](https://drive.google.com/file/d/15_NECCPy-tEWGfYi_BNqawm8GytUTMkz1DsOqGVMXhI/view?usp=drivesdk), and the wave-field cognitive lifecycle of [ADR-0243](https://drive.google.com/file/d/1-ZtokpoiQZD7sdcX54monT_WNeBkUhJuyLPN4mLCEmk/view?usp=drivesdk) established, we perform a deep codebase audit against our three core design pillars: **Mechanical Sympathy, Semantic Rigor, and the Third Door**.
|
||||||
|
|
||||||
|
This audit reveals four critical performance bottlenecks and semantic gaps across the algebraic and physics boundaries:
|
||||||
|
|
||||||
|
- **Concern A: `geometric_product` CPython Loop**: The primary algebraic primitive in `algebra/cl41.py` executes a nested Python loop of $32 imes 32 \= 1,024$ iterations. In the worst case (dense input), this burns \~40 µs per call on the M1, while a compiled, vectorised Rust FFI can compute the product in sub-microsecond cycles.
|
||||||
|
- **Concern B: Float32 vs. Float64 serving boundary**: Numerical stable eigen-relaxation in `multimodal_lifecycle.py` requires double precision (`float64`) for LAPACK convergence, but the `IdentityCheck` gate in `identity.py` requires only `float32`. Carrying `float64` through the identity gate promotes `float32` axis directions to `float64` silently, halving M1 NEON SIMD vector throughput.
|
||||||
|
- **Concern C: Hash Truncation and Silent Coercion**: Truncating the SHA-256 digest of content-addressed vault objects to 24 hex characters (96 bits) introduces a birthday-collision risk at $2^{48}$ entries. This can silently corrupt the Delta-CRDT merge semilattice. Furthermore, using `default=str` in `json.dumps` silently coerces non-serializable objects (collapsing different objects with identical string representations), and we lack explicit byte-order assertions on raw array bytes.
|
||||||
|
- **Concern D: Redundant Eigendecompositions**: Performing LAPACK `eigh` on non-diagonal Hamiltonians takes 50–200 µs on M1. Because `ProblemHamiltonian` is frozen, immutable, and content-addressed, executing a fresh decomposition on identical instances wastes massive Apple Silicon AMX compute.
|
||||||
|
|
||||||
|
This ADR resolves these concern areas by establishing clear, high-assurance contracts that maximize performance and ensure semantic rigor.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2\. Decision and Architectural Formulation
|
||||||
|
|
||||||
|
We resolve these four concern areas by implementing the following high-assurance system-level decisions:
|
||||||
|
|
||||||
|
\[Ingress Wave (f64)\] \---\> \[Eigendecomposition: Cached/eigh\] (AMX Optimized)
|
||||||
|
|
||||||
|
|
|
||||||
|
|
||||||
|
v
|
||||||
|
|
||||||
|
\[GoldTether / Certification\]
|
||||||
|
|
||||||
|
| (Serves-Boundary Cast Contract)
|
||||||
|
|
||||||
|
v
|
||||||
|
|
||||||
|
\[Live Wave-State (f32)\]
|
||||||
|
|
||||||
|
|
|
||||||
|
|
||||||
|
\+-----------------+-----------------+
|
||||||
|
|
||||||
|
| |
|
||||||
|
|
||||||
|
v (M1 NEON SIMD Lanes) v (Domain-Separated 256-bit Hash)
|
||||||
|
|
||||||
|
\[Rust cl41\_geometric\_product\] \[Delta-CRDT Vault Storage\]
|
||||||
|
|
||||||
|
(Gather-Scatter FFI) (Zero Collision Risk)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.1 Decision 1: PyO3 Rust-Wired `geometric_product` Fast-Path
|
||||||
|
|
||||||
|
To achieve the performance declared in our system's README ("Rust computes algebra on the CPU with zero heap allocation in the hot path"), we wire the CPython `cl41.py` module to our native Rust extension:
|
||||||
|
|
||||||
|
1. **Fast-Path Delegation**: When the PyO3-compiled `_rust_cl41` module is available, and both operand arrays are of dtype `float32`, the product is delegated directly to the Rust binary:
|
||||||
|
|
||||||
|
def geometric\_product(A, B):
|
||||||
|
|
||||||
|
\# Fast path: Rust extension available and both are float32
|
||||||
|
|
||||||
|
if \_rust\_cl41 is not None and A.dtype \== np.float32 and B.dtype \== np.float32:
|
||||||
|
|
||||||
|
return \_rust\_cl41.cl41\_geometric\_product(A, B)
|
||||||
|
|
||||||
|
\# Fallback: Pure-Python Workbench path
|
||||||
|
|
||||||
|
...
|
||||||
|
|
||||||
|
2. **SIMD Vectorization**: The Rust kernel implements the product as an auto-vectorized (or NEON-explicit) gather-scatter operation over static precomputed tables, bypassing CPython interpreter overhead.
|
||||||
|
3. **Parity Gate**: Both the Python fallback and the Rust fast-path must produce bit-identical results, verified programmatically by the existing testing suite.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.2 Decision 2: Gated f64-to-f32 Serving Boundary
|
||||||
|
|
||||||
|
We establish the **Serves-Boundary Cast Contract** to resolve the tension between precision and execution throughput:
|
||||||
|
|
||||||
|
1. **The Precision Domain (`float64`)**: Eigendecomposition, Hamiltonian relaxation, and numerical validation remain inside the lifecycle and are evaluated in `float64` for LAPACK stability.
|
||||||
|
2. **The Serving Boundary (`float32`)**: Upon successful certification, the relaxed wave-field $\\psi\_{ ext{steady}}$ is cast explicitly to `float32` before flowing to the `IdentityCheck` gate and linguistic readback paths. This doubles the vector throughput of every subsequent NEON SIMD operation on the M1, where `float32` precision is mathematically sufficient.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.3 Decision 3: Semantic Rigor in Content Addressing
|
||||||
|
|
||||||
|
We secure our Delta-CRDT semilattice and audit trails from hash collision and silent coercion:
|
||||||
|
|
||||||
|
1. **96-bit Truncation Removal**: For the Delta-CRDT merge key, the `psi_digest` and all content-addressed vault objects (such as `TurnEvent` trace hashes) must retain the full **256-bit SHA-256 hex digest** (64 characters), removing the birthday-collision risk entirely. Truncation is permitted only on human-readable labels, never on machine merge keys.
|
||||||
|
2. **Halt on Silent Coercion**: The `default=str` fallback is removed from `json.dumps` in `_content_id`. Any non-serializable metadata or parameter structure must raise a typed `TypeError` at the serialization boundary rather than silently collapsing different objects.
|
||||||
|
3. **Byte-Order Guard**: Before serializing any array to raw bytes via `.tobytes()`, we enforce the canonical byte-order contract: `assert psi.dtype.byteorder in ('<', '=')` This guarantees that the resulting content-addressed digest remains identical across all little-endian platforms (M1/x86\_64).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.4 Decision 4: Eigendecomposition Memoization
|
||||||
|
|
||||||
|
To prevent redundant LAPACK `eigh` calls on identical, frozen `ProblemHamiltonian` instances, we implement a memoized LAPACK solver:
|
||||||
|
|
||||||
|
1. **Caching Strategy**: The eigendecomposition is decorated with `functools.lru_cache(maxsize=128)`.
|
||||||
|
2. **Canonical Cache Keys**: To make the cache completely collision-resistant, the cache key comprises both the `hamiltonian_id` and the immutable `matrix.tobytes()` of the Hamiltonian:
|
||||||
|
|
||||||
|
@functools.lru\_cache(maxsize=128)
|
||||||
|
|
||||||
|
def \_cached\_eigh(hamiltonian\_id: str, matrix\_bytes: bytes):
|
||||||
|
|
||||||
|
matrix \= np.frombuffer(matrix\_bytes, dtype=np.float64).reshape(32, 32\)
|
||||||
|
|
||||||
|
return np.linalg.eigh(matrix)
|
||||||
|
|
||||||
|
This saves up to 200 µs of AMX compute per redundant call on the active reasoning turn.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3\. Comparative Benchmarking (Phase 1 Acceptance Gate)
|
||||||
|
|
||||||
|
Before promoting these updates, the implementation must be validated against the **Falsifiability & Benchmark Framework** in the local calibration area:
|
||||||
|
|
||||||
|
- **Accuracy & Parity**: Verify that the PyO3 Rust extension and the Python fallback produce bit-identical multivector coefficients for $N \= 10,000$ random products.
|
||||||
|
- **Latency & Throughput**: Compare the pure-Python loop against the Rust extension. The target threshold is a **$\\ge 10 imes$ speedup** for dense products under the Rust path.
|
||||||
|
- **Memory Allocations**: Assert that `_cached_eigh` results in exactly 0 heap allocations and 0 LAPACK calls during repeated evaluations of a static Hamiltonian.
|
||||||
|
- **Collision Resistance**: Prove that no two distinct metadata dictionaries can produce identical `_content_id` outputs under the strict, non-coerced JSON path.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4\. References
|
||||||
|
|
||||||
|
1. `algebra/cl41.py` — Legacy precomputed geometric product table.
|
||||||
|
2. `core/physics/wave_manifold.py` — Unified wave-field substrate.
|
||||||
|
3. `core/physics/goldtether.py` — GoldTether residual monitoring.
|
||||||
|
4. `core/physics/multimodal_lifecycle.py` — Ingestion and articulation.
|
||||||
|
5. `core-rs/src/vault.rs` — Rust FFI Delta-CRDT semilattice.
|
||||||
|
|
@ -28,8 +28,8 @@ The directive is directionally sound but was drafted against a **pre-Phase-3 sna
|
||||||
|
|
||||||
## Spec-level wrinkles (all surfaced)
|
## Spec-level wrinkles (all surfaced)
|
||||||
|
|
||||||
1. **ADR-0244 §2.3 `Q_top` is likely vacuous** — central `I₅` in odd Cl(4,1) ⇒ the charge collapses on versor states (the #19 pseudoscalar failure mode). Pending an empirical discriminating counterexample before it can be an egress gate. (Annotated in ADR-0244.)
|
1. **ADR-0244 §2.3 `Q_top` — RESOLVED, proven vacuous** — central `I₅` in odd Cl(4,1) ⇒ the charge collapses identically to 0 on every versor state (the #19 pseudoscalar failure mode), confirmed empirically (`evals/adr_0244_qtop_vacuity`). See Q4 below. Retired from egress; ADR-0244 annotated.
|
||||||
2. **ADR-0244 §4 contradicts §2.1–2.2** — per-axis resonance vs. Gram-projection/leakage-norm/`ManifoldConditioningError`; dangling "ADR-0245"; `assert` byte-order guard (stripped under `-O`). §2 governs; reconcile before implementation. (Annotated in ADR-0244.)
|
2. **ADR-0244 §4 contradicted §2.1–2.2 — RESOLVED at D4 Phase 0** — per-axis resonance vs. Gram-projection/leakage-norm/`ManifoldConditioningError`; the then-dangling "ADR-0245" reference is now a real, committed companion ADR; the bare `assert` byte-order guard is replaced by typed `ValueError` guards (incl. `isfinite`). §2 governs; ADR-0244 §4a is the reconciled specification (see ADR-0244 governance annotation items 2–4, 10 and `docs/handoff/ADR-0244-D4-IMPLEMENTATION-PLAN.md` Phase 0).
|
||||||
3. **Directive §4 says "six criteria" but lists five** — the missing one is the **Mechanical-Sympathy gate** (see below); criteria 1–2 cover Semantic Rigor, 3–4 honesty/falsifiability, 5 Autonomy/Third-Door — **Pillar I had no acceptance criterion**.
|
3. **Directive §4 says "six criteria" but lists five** — the missing one is the **Mechanical-Sympathy gate** (see below); criteria 1–2 cover Semantic Rigor, 3–4 honesty/falsifiability, 5 Autonomy/Third-Door — **Pillar I had no acceptance criterion**.
|
||||||
4. **Quarantine wording** — "every refactored module must reside strictly inside `evals/`" can't apply to an in-place `algebra/cl41.py` refactor. Adopted reading: *new capabilities* live in `evals/`; in-place core refactors keep the A-04 transitive serve-quarantine + smoke/fast-lane gates until acceptance.
|
4. **Quarantine wording** — "every refactored module must reside strictly inside `evals/`" can't apply to an in-place `algebra/cl41.py` refactor. Adopted reading: *new capabilities* live in `evals/`; in-place core refactors keep the A-04 transitive serve-quarantine + smoke/fast-lane gates until acceptance.
|
||||||
5. **Doc placement** — the directive's canonical path is `docs/analysis/`; it sat untracked at `docs/`. The untracked `docs/research/core_cohesion_master_plan.md` and `docs/research/ADR-0243-…md` are stale raw re-exports (the research master-plan predates the AGENTS.md R-01 doctrine note the tracked `docs/analysis/` copy carries); removed, not committed.
|
5. **Doc placement** — the directive's canonical path is `docs/analysis/`; it sat untracked at `docs/`. The untracked `docs/research/core_cohesion_master_plan.md` and `docs/research/ADR-0243-…md` are stale raw re-exports (the research master-plan predates the AGENTS.md R-01 doctrine note the tracked `docs/analysis/` copy carries); removed, not committed.
|
||||||
|
|
@ -64,6 +64,6 @@ Directive §4 lists five gates but claims six. The missing one closes the Mechan
|
||||||
- **Q2 (M6):** κ=1.0-on-failure *is* the required "parameters unchanged" no-op, and the typed `OptimizationFailure` is already returned alongside — so the fix is legibility (a test pinning that failure surfaces as `OptimizationFailure`) + the reason rename to `sampled_unimodality_violation_observed`, **not** breaking the working seam.
|
- **Q2 (M6):** κ=1.0-on-failure *is* the required "parameters unchanged" no-op, and the typed `OptimizationFailure` is already returned alongside — so the fix is legibility (a test pinning that failure surfaces as `OptimizationFailure`) + the reason rename to `sampled_unimodality_violation_observed`, **not** breaking the working seam.
|
||||||
- **Q3:** the sixth criterion is the Mechanical-Sympathy gate above; adopt the quarantine reading in wrinkle #4.
|
- **Q3:** the sixth criterion is the Mechanical-Sympathy gate above; adopt the quarantine reading in wrinkle #4.
|
||||||
- **Q4 (ADR-0244 §2.3):** **RESOLVED — `Q_top` proven vacuous, retire from egress.** The non-vacuity demonstration was attempted and failed: `evals/adr_0244_qtop_vacuity` (pinned by `tests/test_adr_0244_qtop_vacuity.py`) shows `Q_top = 0.000e+00` exactly on every versor, redundant with the closure residual off the manifold, and blind to a versor-preserving identity attack (`ΔQ_top = 0` passes an attack that drops identity overlap to 0.963). Do **not** wire it as an egress gate; keep only as a closure-derived diagnostic.
|
- **Q4 (ADR-0244 §2.3):** **RESOLVED — `Q_top` proven vacuous, retire from egress.** The non-vacuity demonstration was attempted and failed: `evals/adr_0244_qtop_vacuity` (pinned by `tests/test_adr_0244_qtop_vacuity.py`) shows `Q_top = 0.000e+00` exactly on every versor, redundant with the closure residual off the manifold, and blind to a versor-preserving identity attack (`ΔQ_top = 0` passes an attack that drops identity overlap to 0.963). Do **not** wire it as an egress gate; keep only as a closure-derived diagnostic.
|
||||||
- **Q5 sequencing:** ADR-0243 Phase 4 → Phase 5 → **D0** (this) → **D1** (semantic rigor) → **D2** (mechanical sympathy) → **D3** (search honesty). D4 = ADR-0244 implementation, own plan after §4-vs-§2 + `Q_top` are resolved in the ADR.
|
- **Q5 sequencing:** ADR-0243 Phase 4 → Phase 5 → **D0** (this) → **D1** (semantic rigor) → **D2** (mechanical sympathy) → **D3** (search honesty). **D4 = ADR-0244 + ADR-0245 implementation — IN PROGRESS.** Both prerequisites (§4-vs-§2 reconciliation, `Q_top` vacuity) are resolved in the ADRs as of D4 Phase 0 (2026-07-17); full phased plan + live progress: `docs/handoff/ADR-0244-D4-IMPLEMENTATION-PLAN.md`.
|
||||||
|
|
||||||
Every D-batch PR: in-worktree smoke gate + fast lane green before merge; merge-commit on explicit authorization; local-first CI.
|
Every D-batch PR: in-worktree smoke gate + fast lane green before merge; merge-commit on explicit authorization; local-first CI.
|
||||||
|
|
|
||||||
|
|
@ -117,7 +117,7 @@ Dependencies: `0 → {1, 4}` · `1 → 2 → 3` · `5 after 0` · `6 last`. Each
|
||||||
**Objective:** the metric-exact projection primitive, no runtime wiring.
|
**Objective:** the metric-exact projection primitive, no runtime wiring.
|
||||||
**Files:** new `core/physics/identity_manifold.py` (keep `identity.py` as compat shell + dual-mode host); `tests/test_adr_0244_identity_manifold.py`.
|
**Files:** new `core/physics/identity_manifold.py` (keep `identity.py` as compat shell + dual-mode host); `tests/test_adr_0244_identity_manifold.py`.
|
||||||
**Steps:**
|
**Steps:**
|
||||||
- `lift_axis(direction3) → ψ_axis(32)`: grade-1 embedding at `e1/e2/e3` blade indices (VERIFY indices against `algebra.cl41` basis ordering first).
|
- `lift_axis(direction3) → ψ_axis(32)`: grade-1 embedding via `algebra.cl41.basis_vector(0..2)` = e1/e2/e3 at component indices 1/2/3 (verified at Phase 0 against `cl41.py`'s grade-lexicographic blade ordering: grade-1 occupies indices 1–5; `basis_vector(i)` sets `v[1+i]=1.0`). Full §4a spec already drafted in ADR-0244 — implement directly against it.
|
||||||
- `gram(axes) → G` (`G_ij = scalar_part(gp(ψ_i, reverse(ψ_j)))`), symmetric; `cond(G) > 1e5 → ManifoldConditioningError` (typed).
|
- `gram(axes) → G` (`G_ij = scalar_part(gp(ψ_i, reverse(ψ_j)))`), symmetric; `cond(G) > 1e5 → ManifoldConditioningError` (typed).
|
||||||
- `project(ψ, axes, Ginv) → P_id(ψ) = Σ ψ_i (G⁻¹)_ij c_j`, `c_j = ⟨ψ_j, ψ⟩₀` (**signed**).
|
- `project(ψ, axes, Ginv) → P_id(ψ) = Σ ψ_i (G⁻¹)_ij c_j`, `c_j = ⟨ψ_j, ψ⟩₀` (**signed**).
|
||||||
- `leakage(ψ) = ψ − P_id(ψ)`; `leakage_norm = ‖·‖₂` (Euclidean coeff norm).
|
- `leakage(ψ) = ψ − P_id(ψ)`; `leakage_norm = ‖·‖₂` (Euclidean coeff norm).
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue