From ad37d03b19409928d08c38a6a7a967988ae29db9 Mon Sep 17 00:00:00 2001 From: Shay Date: Fri, 17 Jul 2026 15:32:09 -0700 Subject: [PATCH] =?UTF-8?q?docs(adr-0244,adr-0245):=20D4=20Phase=200=20?= =?UTF-8?q?=E2=80=94=20governance=20reconciliation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- ...old-and-inalienable-geometric-alignment.md | 114 ++++++++++++- ...-mechanical-sympathy-and-semantic-rigor.md | 160 ++++++++++++++++++ ...244-cohesion-directive-audit-2026-07-17.md | 6 +- .../ADR-0244-D4-IMPLEMENTATION-PLAN.md | 2 +- 4 files changed, 273 insertions(+), 9 deletions(-) create mode 100644 docs/adr/ADR-0245-cga-unification-mechanical-sympathy-and-semantic-rigor.md diff --git a/docs/adr/ADR-0244-wave-field-identity-manifold-and-inalienable-geometric-alignment.md b/docs/adr/ADR-0244-wave-field-identity-manifold-and-inalienable-geometric-alignment.md index 6bcf78f6..b7f0e441 100644 --- a/docs/adr/ADR-0244-wave-field-identity-manifold-and-inalienable-geometric-alignment.md +++ b/docs/adr/ADR-0244-wave-field-identity-manifold-and-inalienable-geometric-alignment.md @@ -4,16 +4,27 @@ **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-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. -> 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. +> 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" 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 * _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 _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 1. `algebra/cl41.py` — Precomputed geometric product table. 2. `core/physics/wave_manifold.py` — Continuous wave-field substrate. 3. `core/physics/goldtether.py` — GoldTether residual monitoring. 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. diff --git a/docs/adr/ADR-0245-cga-unification-mechanical-sympathy-and-semantic-rigor.md b/docs/adr/ADR-0245-cga-unification-mechanical-sympathy-and-semantic-rigor.md new file mode 100644 index 00000000..6b8f209d --- /dev/null +++ b/docs/adr/ADR-0245-cga-unification-mechanical-sympathy-and-semantic-rigor.md @@ -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. diff --git a/docs/analysis/adr-0244-cohesion-directive-audit-2026-07-17.md b/docs/analysis/adr-0244-cohesion-directive-audit-2026-07-17.md index c7e20812..87c468fb 100644 --- a/docs/analysis/adr-0244-cohesion-directive-audit-2026-07-17.md +++ b/docs/analysis/adr-0244-cohesion-directive-audit-2026-07-17.md @@ -28,8 +28,8 @@ The directive is directionally sound but was drafted against a **pre-Phase-3 sna ## 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.) -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.) +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 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**. 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. @@ -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. - **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. -- **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. diff --git a/docs/handoff/ADR-0244-D4-IMPLEMENTATION-PLAN.md b/docs/handoff/ADR-0244-D4-IMPLEMENTATION-PLAN.md index fc94a237..3b8c194b 100644 --- a/docs/handoff/ADR-0244-D4-IMPLEMENTATION-PLAN.md +++ b/docs/handoff/ADR-0244-D4-IMPLEMENTATION-PLAN.md @@ -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. **Files:** new `core/physics/identity_manifold.py` (keep `identity.py` as compat shell + dual-mode host); `tests/test_adr_0244_identity_manifold.py`. **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). - `project(ψ, axes, Ginv) → P_id(ψ) = Σ ψ_i (G⁻¹)_ij c_j`, `c_j = ⟨ψ_j, ψ⟩₀` (**signed**). - `leakage(ψ) = ψ − P_id(ψ)`; `leakage_norm = ‖·‖₂` (Euclidean coeff norm).