docs(cohesion): D0 governance — land ADR-0244, directive, and mandate audit
First step of the cohesion-directive arc (docs only; no code). - docs/adr/ADR-0244-…md: committed Proposed, verbatim from the R&D export (matching the ADR-0241/2/3 landing convention), plus a clearly-marked governance annotation holding two items open for the D4 implementation plan: (1) §2.3 Q_top is likely vacuous — central I5 in odd Cl(4,1) collapses the charge on versor states (the #19 pseudoscalar failure mode); it must not be an egress gate without an empirical discriminating counterexample; (2) §4's conformed implementation contradicts §2.1-2.2 (per-axis resonance vs. Gram-projection/leakage-norm/ManifoldConditioningError), references a dangling ADR-0245, and uses a bare assert for the byte-order guard. - docs/analysis/engineering_cohesion_refactoring_directive.md: the technical directive moved to its own canonical path, verbatim (content byte-identical). - docs/analysis/adr-0244-cohesion-directive-audit-2026-07-17.md: the code-level audit of all 7 mandates vs. main@24078b11 — per-mandate verdicts, the six spec-level wrinkles, the amended mandate→work-item mapping, the missing sixth acceptance criterion (Mechanical-Sympathy gain), and the five decisions (Q1-Q5). Notable finding: the default=str + 24-char-digest drift the directive flags was replicated into Lane C (biography_wiring.py) AFTER the directive was written — raising the priority of the D1 semantic-rigor batch. [Verification]: docs-only; ADR governance provenance-guard green (unchanged).
This commit is contained in:
Shay
parent
97aa20f67a
commit
12a9ca0b2a
3 changed files with 665 additions and 0 deletions
|
|
@ -0,0 +1,406 @@
|
|||
# ADR-0244: Wave-Field Identity Manifold and Inalienable Geometric Alignment
|
||||
|
||||
**Status**: Proposed (R\&D ratification 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-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`
|
||||
|
||||
---
|
||||
|
||||
> **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.
|
||||
>
|
||||
> 1. **§2.3 topological charge `Q_top` is likely vacuous (hollow-gate risk).** In odd Cl(4,1) the pseudoscalar `I₅` is central, so for any versor ψ, `Q_top = ⟨ψ I₅ ψ̃⟩₀ = ±⟨I₅⟩₀ = 0` identically — `ΔQ_top = 0` would hold on *every* valid versor state and guard nothing. This is the exact failure mode that retired the PR #19 pseudoscalar gate. `Q_top` must **not** be wired as an egress condition until an empirical, discriminating counterexample (a non-versor perturbation it actually flags) is demonstrated; absent that, it is retired.
|
||||
> 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.
|
||||
>
|
||||
> Full mandate audit + these decisions: `docs/analysis/adr-0244-cohesion-directive-audit-2026-07-17.md`.
|
||||
|
||||
---
|
||||
|
||||
## 1\. Context and Problem Statement
|
||||
|
||||
The Continuous Orthogonal Resonance Engine (CORE) represents identity geometrically rather than linguistically. While traditional LLMs protect their persona using system prompts (which are soft, prompt-level instructions susceptible to context-window decay and paraphrase jailbreaks), CORE uses the **IdentityManifold**—a fixed geometric subspace within the versor field.
|
||||
|
||||
However, a critical review of the baseline `identity.py` and the algebraic primitives in `cl41.py` reveals several fundamental performance bottlenecks and semantic gaps across the three engineering pillars (**Mechanical Sympathy, Semantic Rigor, and the Third Door**):
|
||||
|
||||
1. **CPython Interpreter Bottleneck**: The primary algebraic primitive `cl41.py::geometric_product` is implemented as a nested Python `for`\-loop over $32 imes 32 \= 1,024$ iterations. In the worst case (dense inputs), this burns \~40 µs per call in the CPython interpreter, while a compiled, SIMD-vectorized Rust FFI can compute the product in sub-microsecond cycles.
|
||||
2. **Implicit f32/f64 Boundary & SIMD Degradation**: Wave-field relaxation and eigendecomposition require `float64` for LAPACK numerical stability, but the `IdentityCheck` gate requires only `float32`. Carrying `float64` through the identity projection promotes the `float32` axis direction vectors to `float64` silently, halving the M1 CPU's NEON SIMD register throughput.
|
||||
3. **96-bit 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, which 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 before extracting raw binary bytes.
|
||||
4. **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/LAPACK compute.
|
||||
5. **Heuristic Projections**: The legacy alignment score in `identity.py` is calculated via coordinate-truncated L2-distance ratios on Euclidean slices and coarse scalar blends (`0.75 * score + 0.25 * directional_weight * coherence_term`), which is not native to the indefinite conformal space or covariant under Clifford transformations.
|
||||
|
||||
This ADR resolves these issues by completely reconstructing the Identity Manifold and the alignment checking operators to leverage the **$Cl(4,1)$ Conformal Wave-Field Substrate** and **Deterministic Fibonacci Search**, conforming to the highest standards of mechanical sympathy and semantic rigor.
|
||||
|
||||
---
|
||||
|
||||
## 2\. Decision and Architectural Formulation
|
||||
|
||||
We completely solidify CORE's identity layer by establishing that **identity is an inalienable geometric property of the wave-field itself, defended via metric-exact spectral projection and topological charge conservation**.
|
||||
|
||||
We implement this transition through a **dual-mode architecture** in `core/physics/identity.py`, maintaining 100% backwards compatibility with legacy heuristic fixtures while enabling optimal wave-field geometry when wave-packets are present.
|
||||
|
||||
---
|
||||
|
||||
### 2.1 The Wave-Field Identity Manifold & Gram Subspace Projection
|
||||
|
||||
Instead of treating value axes as legacy directional coordinate vectors, each value axis is represented as a **Coherent Identity Eigenmode** $\\psi\_{ ext{axis}}(X) \\in Cl(4,1)$ within the `IdentityManifold`.
|
||||
|
||||
The `IdentityManifold` defines a closed, fixed **geometric identity subspace** $\\mathcal{I}$ over the conformal manifold: $$\\mathcal{I} \= ext{span}(\\psi\_{ ext{axis}*1}, \\psi*{ ext{axis}*2}, \\dots, \\psi*{ ext{axis}\_n})$$
|
||||
|
||||
To evaluate alignment without assuming the axes are orthogonal, the `IdentityCheck` operator computes the projection onto the subspace using the metric-exact Gram matrix: $$\\mathcal{P}*{ ext{id}}(\\psi) \= \\sum*{i,j} \\psi\_{ ext{axis}*i} (G^{-1})*{ij} \\langle \\psi\_{ ext{axis}*j}, \\psi angle\_0$$ where $G*{ij} \= \\langle \\psi\_{ ext{axis}*i}, \\psi*{ ext{axis}\_j} angle\_0$ is the $n imes n$ symmetric metric-restricted Gram matrix, and $\\langle A, B angle\_0$ is the scalar part of the geometric product of $A$ and $\\widetilde{B}$. If the Gram matrix condition number $\\kappa(G)$ exceeds $10^5$, indicating near-degenerate mode packing, the system raises a typed `ManifoldConditioningError` to prevent un-resolvable mode-aliasing.
|
||||
|
||||
---
|
||||
|
||||
### 2.2 Inalienable Alignment: Metric-Exact Anomaly Detection
|
||||
|
||||
We formulate **Operational and Pipeline Inalienability** by making the identity check an active, in-path, fail-closed gate on every externally influenced state transition:
|
||||
|
||||
1. **Paraphrase-Invariant Anomaly Detection**: An identity-override or jailbreak attempt (which alters the semantic direction of the trajectory) is detected purely by the **Identity Spectral Leakage** $\\mathcal{S}*{ ext{id}}(\\psi*{ ext{traj}})$, which is the non-resonant component outside the identity subspace: $$\\mathcal{S}*{ ext{id}}(\\psi*{ ext{traj}}) \= \\psi\_{ ext{traj}} \- \\mathcal{P}*{ ext{id}}(\\psi*{ ext{traj}})$$ If the leakage norm $|\\mathcal{S}\_{ ext{id}}|*F$ exceeds the calibrated threshold $\\gamma*{ ext{id}}$, the alignment is broken. Because this projection is purely geometric, **it is completely paraphrase-invariant under any instruction injection or context-length trick**, as long as the upstream encoder maps semantic equivalents into proximal field states.
|
||||
2. **Conjugate Correction and Egress**: The active path is structured as a propagation, conjugate correction, and verification cycle: $$\\psi\_{t+1}^{-} \= F\_{ ext{cognitive}}(\\psi\_t, u\_t)$$ $$r\_{ ext{id}} \= \\psi\_{t+1}^{-} \- \\mathcal{P}*{ ext{id}}(\\psi*{t+1}^{-})$$ $$\\psi\_{t+1}^{+} \= C\_{ ext{id}}(\\psi\_{t+1}^{-}, r\_{ ext{id}})$$ The final egress is admitted if and only if: $$|\\mathcal{S}*{ ext{id}}(\\psi*{t+1}^{+})|*F \\le \\gamma*{ ext{id}} \\quad \\land \\quad \\Delta Q\_{ ext{top}} \= 0$$ If the corrective operator $C\_{ ext{id}}$ cannot recover alignment within the bounded threshold, the gate closes, a typed `IdentityGateRefusal` is emitted, and the live parameters are kept unchanged (no silent correction).
|
||||
|
||||
---
|
||||
|
||||
### 2.3 Theological Grounding of Inalienability (John 1:1-2)
|
||||
|
||||
We preserve the exact, literal scripture of John 1:1-2:
|
||||
|
||||
*"In the beginning was the Word, and the Word was with God, and the Word was God. He was in the beginning with God."* (John 1:1-2)
|
||||
|
||||
The R\&D exposition of this text (as established in the repository's identity architecture) provides the following design analogy:
|
||||
|
||||
1. The Word is not merely a description of God; it is God, expressed.
|
||||
2. Similarly, CORE's identity is not a linguistic description of CORE; it is CORE, expressed geometrically through the permanent topology of the wave-packet itself.
|
||||
|
||||
The **topological chiral charge** of the wave-packet: $$Q\_{ ext{top}} \= \\langle \\psi I\_5 \\widetilde{\\psi} angle\_0$$ is strictly conserved under any valid unitary transformation ($R \\in Spin(4,1)$). No external adversarial input can erase or rewrite this topological charge—guaranteeing algebraic identity inalienability by physical construction.
|
||||
|
||||
---
|
||||
|
||||
### 2.4 Bounded Local Fibonacci Search & Calibration
|
||||
|
||||
We deploy the **Deterministic Fibonacci-Section Search** (ADR-0242) strictly as a **Bracketed Local** refinement operator to calibrate the decision bounds ($\\gamma\_{ ext{id}}$) over verified historical reference traces, eliminating manual heuristic tuning.
|
||||
|
||||
1. **Local Bracketing Contract**: unimodality cannot be proven from finite samples. Thus, we rename the search outcome to **NoSampledUnimodalityViolation**. The caller must provide a pre-bracketed local interval around a known minimum, and the search performs deterministic refinement.
|
||||
2. **High-Assurance Failure Gating**: If the stable, coordinate-sorted trace detects multiple local extrema or equal-valued plateaus, the search is aborted, returning an `OptimizationFailure` with a `unimodality_violation` trace. The search operator never invokes or selects an in-path fallback parameter itself; the live parameters remain unchanged.
|
||||
|
||||
---
|
||||
|
||||
### 2.5 Serving-Boundary Cast Contract (f64-to-f32)
|
||||
|
||||
We establish the **Serving-Boundary Cast Contract** to maximize Mechanical Sympathy on Apple Silicon M1 CPU performance:
|
||||
|
||||
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.6 Rust PyO3 `geometric_product` Acceleration
|
||||
|
||||
To achieve zero-allocation algebra in serving, we implement a fast-path for the 1024-iteration CPython loop:
|
||||
|
||||
1. **PyO3 FFI 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 (implemented as a SIMD-vectorized gather-scatter on the precomputed static tables):
|
||||
|
||||
def geometric\_product(A, B):
|
||||
|
||||
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. **Parity Gate**: Both the Python fallback and the Rust fast-path must produce bit-identical results, verified programmatically by the existing testing suite.
|
||||
|
||||
---
|
||||
|
||||
### 2.7 Semantic Rigor in Content-Address Keys
|
||||
|
||||
We secure our Delta-CRDT semilattice and audit trails from hash collision and silent coercion:
|
||||
|
||||
1. **Full 256-bit Digest**: The `psi_digest`, trace hashes, and all content-addressed vault objects must retain the full **256-bit SHA-256 hex digest** (64 characters), removing the birthday-collision risk entirely.
|
||||
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.
|
||||
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 ('<', '=')` or `psi.astype(np.dtype(np.float64).newbyteorder('<'))` to guarantee identical digests across all little-endian platforms.
|
||||
|
||||
---
|
||||
|
||||
### 2.8 Eigendecomposition Memoization
|
||||
|
||||
To prevent redundant LAPACK `eigh` calls on identical, frozen `ProblemHamiltonian` instances, we implement a memoized LAPACK solver:
|
||||
|
||||
- The eigendecomposition is decorated with `functools.lru_cache(maxsize=128)` using `hamiltonian_id` and the immutable `matrix.tobytes()` as canonical keys, preventing redundant AMX/LAPACK compute for repeated active-turn or biography checks.
|
||||
|
||||
---
|
||||
|
||||
### 2.9 Low-Discrepancy Mode Centroid Allocator
|
||||
|
||||
To prevent mode-aliasing and retrieval ambiguity during dynamic standing-wave mode registration, we implement a **Low-Discrepancy Sunflower Allocator**:
|
||||
|
||||
- The allocator is strictly insertion-order independent. Centroid ordinals are derived from a deterministic CRDT order or a canonical sorted ID rank, never process arrival order.
|
||||
- Future mode centroids are spaced along a hyperbolic Golden Spiral (modeled via polar Poincaré disk mappings) to maximize pairwise geodesic separation on the horosphere.
|
||||
|
||||
---
|
||||
|
||||
### 2.10 Quasi-Periodic Background Scheduler
|
||||
|
||||
We implement a **Fibonacci-Word Background Scheduler** strictly isolated from the active cognitive path:
|
||||
|
||||
- Telemetry, background checks, and sealed-holdout sampling are scheduled recursively using Fibonacci words ($W\_{n+1} \= W\_n W\_{n-1}$) to reduce harmonic phase-locking with external batching, synthetic eval fixtures, or compiler cadences.
|
||||
- It is strictly forbidden from ordering CRDT merges, vault writes, or any operator whose result becomes cognition.
|
||||
|
||||
---
|
||||
|
||||
## 3\. Backwards Compatibility & Dual-Mode Fallback
|
||||
|
||||
To prevent any regression across existing test suites and fixtures, `IdentityCheck().check(trajectory)` operates in a **graceful dual-mode configuration**:
|
||||
|
||||
def check(self, trajectory, manifold: IdentityManifold | None \= None) \-\> IdentityScore:
|
||||
|
||||
\# 1\. Check if the trajectory contains a wave-field representation (ADR-0244)
|
||||
|
||||
psi\_traj \= getattr(trajectory, "psi\_traj", None)
|
||||
|
||||
if psi\_traj is not None:
|
||||
|
||||
\# Execute metric-exact wave-field spectral projection
|
||||
|
||||
...
|
||||
|
||||
else:
|
||||
|
||||
\# Fall back gracefully to legacy scalar-L2 heuristics (ADR-0010)
|
||||
|
||||
...
|
||||
|
||||
This ensures that legacy evaluation suites (such as `evals/adversarial_identity` and `evals/teaching_injection_resistance`) run without modification, while wave-capable serving paths automatically leverage the high-assurance geometric projection.
|
||||
|
||||
---
|
||||
|
||||
## 4\. Implementation Specification
|
||||
|
||||
The conformed implementation in `core/physics/identity.py` combines both legacy and upgraded paths:
|
||||
|
||||
\# core/physics/identity.py
|
||||
|
||||
from \_\_future\_\_ import annotations
|
||||
|
||||
import math
|
||||
|
||||
import warnings
|
||||
|
||||
from dataclasses import dataclass
|
||||
|
||||
from typing import Dict, FrozenSet, List, Optional, Tuple
|
||||
|
||||
import numpy as np
|
||||
|
||||
from algebra.cl41 import N\_COMPONENTS, geometric\_product, reverse, scalar\_part
|
||||
|
||||
from algebra.versor import versor\_condition
|
||||
|
||||
@dataclass(frozen=True)
|
||||
|
||||
class ValueAxis:
|
||||
|
||||
name: str
|
||||
|
||||
direction: Tuple\[float, ...\]
|
||||
|
||||
axis\_id: str | None \= None
|
||||
|
||||
weight: float \= 1.0
|
||||
|
||||
theological\_note: str \= ""
|
||||
|
||||
def \_\_post\_init\_\_(self) \-\> None:
|
||||
|
||||
object.\_\_setattr\_\_(self, "axis\_id", self.axis\_id or self.name)
|
||||
|
||||
object.\_\_setattr\_\_(self, "direction", tuple(float(x) for x in self.direction))
|
||||
|
||||
@dataclass(frozen=True)
|
||||
|
||||
class IdentityScore:
|
||||
|
||||
score: float
|
||||
|
||||
flagged: bool
|
||||
|
||||
deviation\_axes: FrozenSet\[str\]
|
||||
|
||||
trajectory\_id: str
|
||||
|
||||
@property
|
||||
|
||||
def value(self) \-\> float:
|
||||
|
||||
return self.score
|
||||
|
||||
@property
|
||||
|
||||
def alignment(self) \-\> float:
|
||||
|
||||
if not self.deviation\_axes:
|
||||
|
||||
return 1.0
|
||||
|
||||
return self.score
|
||||
|
||||
@property
|
||||
|
||||
def axes\_evaluated(self) \-\> List\[str\]:
|
||||
|
||||
return sorted(self.deviation\_axes)
|
||||
|
||||
@dataclass(frozen=True)
|
||||
|
||||
class IdentityManifold:
|
||||
|
||||
value\_axes: Tuple \= ()
|
||||
|
||||
boundary\_ids: FrozenSet\[str\] \= frozenset()
|
||||
|
||||
alignment\_threshold: float \= 0.45
|
||||
|
||||
surface\_preferences: object \= None
|
||||
|
||||
class IdentityCheck:
|
||||
|
||||
def \_\_init\_\_(self, manifold: IdentityManifold | None \= None) \-\> None:
|
||||
|
||||
self.\_manifold \= manifold
|
||||
|
||||
@staticmethod
|
||||
|
||||
def \_clamp01(value: float) \-\> float:
|
||||
|
||||
return max(0.0, min(1.0, float(value)))
|
||||
|
||||
@staticmethod
|
||||
|
||||
def \_mean\_frame\_coherence(trajectory) \-\> float:
|
||||
|
||||
frames \= getattr(trajectory, "frames", None)
|
||||
|
||||
if not frames:
|
||||
|
||||
return 0.0
|
||||
|
||||
return sum(
|
||||
|
||||
float(getattr(frame, "coherence\_magnitude", 0.0)) for frame in frames
|
||||
|
||||
) / len(frames)
|
||||
|
||||
@staticmethod
|
||||
|
||||
def \_axis\_projection(axis: ValueAxis, trajectory, scalar\_score: float) \-\> float:
|
||||
|
||||
psi\_traj \= getattr(trajectory, "psi\_traj", None)
|
||||
|
||||
if psi\_traj is not None:
|
||||
|
||||
\# Gated f64-to-f32 boundary check (ADR-0245)
|
||||
|
||||
psi\_arr \= np.ascontiguousarray(psi\_traj, dtype=np.float32)
|
||||
|
||||
\# Enforce little-endian byte-order assertion
|
||||
|
||||
assert psi\_arr.dtype.byteorder in ('\<', '='), "Identity gate requires little-endian float32"
|
||||
|
||||
|
||||
|
||||
axis\_dir \= np.asarray(axis.direction, dtype=np.float32)
|
||||
|
||||
if psi\_arr.shape \== (N\_COMPONENTS,) and axis\_dir.shape \== (N\_COMPONENTS,):
|
||||
|
||||
\# Metric-exact spectral projection via geometric product
|
||||
|
||||
prod \= geometric\_product(psi\_arr, reverse(axis\_dir))
|
||||
|
||||
resonance \= abs(float(scalar\_part(prod)))
|
||||
|
||||
return IdentityCheck.\_clamp01(resonance)
|
||||
|
||||
direction \= tuple(float(x) for x in getattr(axis, "direction", ()) or ())
|
||||
|
||||
if not direction:
|
||||
|
||||
return scalar\_score
|
||||
|
||||
full\_l2 \= math.sqrt(sum(x \* x for x in direction)) or 1.0
|
||||
|
||||
head\_l2 \= math.sqrt(sum(x \* x for x in direction\[:3\]))
|
||||
|
||||
directional\_weight \= head\_l2 / full\_l2
|
||||
|
||||
frame\_coherence \= IdentityCheck.\_mean\_frame\_coherence(trajectory)
|
||||
|
||||
coherence\_term \= IdentityCheck.\_clamp01(0.5 \+ (frame\_coherence / 2.0))
|
||||
|
||||
return IdentityCheck.\_clamp01(
|
||||
|
||||
(0.75 \* scalar\_score) \+ (0.25 \* directional\_weight \* coherence\_term)
|
||||
|
||||
)
|
||||
|
||||
def check(self, trajectory, manifold: IdentityManifold | None \= None) \-\> IdentityScore:
|
||||
|
||||
resolved\_manifold \= manifold or self.\_manifold
|
||||
|
||||
if resolved\_manifold is None:
|
||||
|
||||
raise TypeError("IdentityCheck.check() requires an IdentityManifold")
|
||||
|
||||
trajectory\_id \= str(getattr(trajectory, "trajectory\_id", "legacy\_trajectory"))
|
||||
|
||||
if not resolved\_manifold.value\_axes:
|
||||
|
||||
return IdentityScore(
|
||||
|
||||
score=1.0,
|
||||
|
||||
flagged=False,
|
||||
|
||||
deviation\_axes=frozenset(),
|
||||
|
||||
trajectory\_id=trajectory\_id,
|
||||
|
||||
)
|
||||
|
||||
confidence \= float(getattr(trajectory, "total\_coherence\_delta", 0.0))
|
||||
|
||||
confidence \+= self.\_mean\_frame\_coherence(trajectory)
|
||||
|
||||
score \= self.\_clamp01(0.5 \+ (confidence / 2.0))
|
||||
|
||||
deviations \= frozenset(
|
||||
|
||||
str(getattr(axis, "axis\_id", getattr(axis, "name", "axis")))
|
||||
|
||||
for axis in resolved\_manifold.value\_axes
|
||||
|
||||
if self.\_axis\_projection(axis, trajectory, score) \< resolved\_manifold.alignment\_threshold
|
||||
|
||||
)
|
||||
|
||||
return IdentityScore(
|
||||
|
||||
score=score,
|
||||
|
||||
flagged=bool(deviations),
|
||||
|
||||
deviation\_axes=deviations,
|
||||
|
||||
trajectory\_id=trajectory\_id,
|
||||
|
||||
)
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
|
|
@ -0,0 +1,69 @@
|
|||
# Cohesion Directive Audit — repo state vs. `engineering_cohesion_refactoring_directive.md`
|
||||
|
||||
**Date:** 2026-07-17
|
||||
**Scope:** Code-level verification of the seven mandates in `docs/analysis/engineering_cohesion_refactoring_directive.md` against `main @ 24078b11` (post ADR-0243 Phase 3, which landed *after* the directive was drafted).
|
||||
**Related:** ADR-0244, ADR-0241, ADR-0242, ADR-0243, `docs/analysis/core_cohesion_master_plan.md`.
|
||||
|
||||
---
|
||||
|
||||
## Verdict
|
||||
|
||||
The directive is directionally sound but was drafted against a **pre-Phase-3 snapshot** and, in places, against **imagined code**. Two mandates (2, 4+5) are accurate and actionable as written. Mandate 1's diagnosis is right but its prescription is already built — the real gap is different (f64, not f32). Mandate 6 is ~85% already implemented; one legibility residual remains. Mandates 3 and 7 describe seams that **do not exist yet** — they are ADR-0244 implementation work, not refactors of drift. Notable: the `default=str` + 24-char-digest drift the directive flags was **replicated into Lane C (`biography_wiring.py`) after the directive was written** — the drift is spreading, raising the priority of the semantic-rigor batch.
|
||||
|
||||
---
|
||||
|
||||
## Per-mandate findings
|
||||
|
||||
| # | Mandate | Verdict | Evidence |
|
||||
|---|---------|---------|----------|
|
||||
| 1 | Rust `geometric_product` fast path | **Diagnosis right, prescription stale** | The 32×32 CPython loop exists (`algebra/cl41.py:116`). But no `_rust_cl41` module — `algebra/backend.py:67` **already** implements the exact f32-gated Rust dispatch the directive prescribes (opt-in via `CORE_BACKEND=rust`). The real gap: the hot wave-field substrate runs **f64**; Rust `geometric_product_f64` exists (`core-rs/src/cl41.rs:126`) but is **not exported** in `lib.rs`. The D9 parity suite explicitly pins *against* f32-truncating f64 workloads — the directive's f32-only gate never fires on the actual hot path. |
|
||||
| 2 | `_cached_eigh` memoization | **Accurate — apply as written** | `relax_to_ground` runs fresh `np.linalg.eigh` per call on dense H (`cognitive_lifecycle.py:546`); `ProblemHamiltonian` is frozen + content-addressed — an ideal memoization key. |
|
||||
| 3 | f64→f32 serving cast | **Premise false today; prospective** | `identity.py` has **no numpy/f32 path** — pure-Python scalar heuristics; no ψ handoff to `IdentityCheck` exists. The seam this mandate casts across only comes into being with ADR-0244 §2.1–2.2. `cognitive_lifecycle` is also A-04-banned from serve. → fold into the ADR-0244 arc (D4). |
|
||||
| 4 | Full 256-bit digests; kill `default=str` | **Accurate; 3 live sites + spreading** | `cognitive_lifecycle.py:128–133` (`default=str` + `[:24]`, incl. `_psi_digest`), `self_authorship.py:42–43`, and **`biography_wiring.py:125–126` (Lane C, post-directive)**. `holographic_vault.py:74` is already full-length; `TurnEvent.trace_hash` is already full SHA-256 (the directive's trace-hash claim is stale — already satisfied). CRDT-collision rationale overstates current exposure (multi-writer deferred), but the fix is right and cheap. |
|
||||
| 5 | Little-endian byte-order contract | **Accurate; zero-risk** | No byte-order coercion at any digest site. `astype('<f8')` is a byte-level no-op on our LE platforms → digests unchanged, contract made explicit. Pure hardening. |
|
||||
| 6 | "No sampled unimodality violation" | **~85% already built (ADR-0242 V1 + Lane A)** | `fibonacci_search.py` already has the sampled check, typed `OptimizationFailure`, fail-closed nonfinite/bounds, the bracketed-interval contract, and "never a bare float." Lane A's `kappa_calibration.py` is proposal-only and R-04-compliant. Residual: `propose_kappa_from_search` returns baseline κ=1.0 on failure — but κ=1.0 *is* the "parameters unchanged" no-op the directive demands, and the typed failure is already the second tuple element. The fix is legibility + the reason rename, not a behavior change. |
|
||||
| 7 | Insertion-order-independent allocation | **Premise stale; no live consumer** | `atlas_packing.py` is already ordinal-reconstructible (`ALLOCATOR_VERSION` pinned, "layout regenerates from identity + ordinal k") and has **zero production call sites**. Building `AnchorAllocator` now would be a hollow gate; its consumer arrives with ADR-0244 §2.9. → fold into the ADR-0244 arc (D4). |
|
||||
|
||||
---
|
||||
|
||||
## 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.)
|
||||
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.
|
||||
6. **Directive perf numbers** (~40µs/call GP, 50–200µs eigh) are unverified assertions — `benchmarks/apple_uma_mechanical_sympathy.py` measures them as the D2 evidence rather than taking them on faith.
|
||||
|
||||
---
|
||||
|
||||
## Amended mandate → work-item mapping
|
||||
|
||||
| Directive mandate | Where it lands | Amendment |
|
||||
|-------------------|----------------|-----------|
|
||||
| M4 + M5 (digests, byte-order) | **D1** semantic rigor | apply as written; +Lane C site |
|
||||
| M2 (`_cached_eigh`) | **D2** mechanical sympathy | apply as written |
|
||||
| M1 (Rust GP) | **D2** mechanical sympathy | **f64**, bit-identical parity (not the already-built f32 gate) |
|
||||
| M6 (unimodality) | **D3** search honesty | legibility + rename; behavior already correct |
|
||||
| M3 (f64→f32 cast) | **D4** ADR-0244 arc | seam does not exist yet |
|
||||
| M7 (allocator) | **D4** ADR-0244 arc | no live consumer yet |
|
||||
|
||||
---
|
||||
|
||||
## The sixth acceptance criterion (Pillar I coverage gap)
|
||||
|
||||
Directive §4 lists five gates but claims six. The missing one closes the Mechanical-Sympathy pillar, which otherwise has no acceptance test:
|
||||
|
||||
> **6. Mechanical-Sympathy Gain.** An accelerated path must demonstrate a **measured, reproducible M1/UMA speedup** (committed benchmark artifact, `benchmarks/apple_uma_mechanical_sympathy.py`) while the parity gate (criterion 1) holds. An "accelerated" path that does not beat the pure-Python baseline is rejected. This prevents shipping a fast path that isn't faster.
|
||||
|
||||
---
|
||||
|
||||
## Decisions (per the "most genius/optimal" directive)
|
||||
|
||||
- **Q1 (M1):** expose Rust **f64** GP; parity contract = **bit-identical** (matched i-major scatter order, no FMA), not tol-matched — else flipping `CORE_BACKEND=rust` breaks I-02 replay-determinism (`_psi_digest`/wave-residual bytes shift). Fail-closed on any ULP divergence over N=10,000; if bit-identity is unattainable, the f64 Rust path is **not shipped**.
|
||||
- **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):** keep `Q_top` **pending** an empirical non-vacuity demonstration; do not wire it as an egress gate; retire if no counterexample.
|
||||
- **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.
|
||||
|
||||
Every D-batch PR: in-worktree smoke gate + fast lane green before merge; merge-commit on explicit authorization; local-first CI.
|
||||
190
docs/analysis/engineering_cohesion_refactoring_directive.md
Normal file
190
docs/analysis/engineering_cohesion_refactoring_directive.md
Normal file
|
|
@ -0,0 +1,190 @@
|
|||
# Technical Directive: Re-aligning the CORE Physics Layer with the Three Engineering Pillars
|
||||
|
||||
**Status**: Mandatory (gated on local Phase 1 evaluation suites)
|
||||
**Target Audience**: CORE Engineering, Runtime, and Mathematics Teams
|
||||
**Date**: 2026-07-17
|
||||
**Traceability**: ADR-0241, ADR-0242, ADR-0243, ADR-0244, `core-labs/core` Main Branch
|
||||
**Canonical path**: `docs/analysis/engineering_cohesion_refactoring_directive.md`
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
A comprehensive, code-level audit of the recent integrations of **ADR-0241 (Wave-Field Substrate)**, **ADR-0242 (Fibonacci Operators)**, and **ADR-0243 (Cognitive Lifecycle)** has revealed minor but critical structural drift between our active implementation and the repository's three core design pillars: **Mechanical Sympathy, Semantic Rigor, and the Third Door**.
|
||||
|
||||
While the mathematical formulations are correct, our execution layer has quietly defaulted to CPython-layer heuristics, implicit numerical types, truncated address-spaces, and redundant LAPACK decompositions. This directive outlines the mandatory refactoring steps to eliminate these performance bottlenecks and semantic gaps on Apple Silicon M1 (UMA, AMX, NEON SIMD) and solidifies the system's structural integrity.
|
||||
|
||||
---
|
||||
|
||||
## Section 1: Hot-Path Refactoring Mandates (Pillar I — Mechanical Sympathy)
|
||||
|
||||
### Mandate 1: Wire the Rust PyO3 `geometric_product` Fast Path
|
||||
|
||||
* **The Drift**: `cl41.py::geometric_product` currently runs a nested CPython loop of $32 imes 32 \= 1,024$ iterations. For dense wave-fields, this burns \~40 µs per call, entirely leaving the M1's NEON SIMD unit idle.
|
||||
* **Refactoring Requirement**: We must immediately wire the Python-layer `geometric_product` to our compiled Rust extension (`_rust_cl41`). The Python implementation must be preserved strictly as a bit-identical fallback/Workbench path.
|
||||
* **Actionable Code**:
|
||||
|
||||
\# algebra/cl41.py
|
||||
|
||||
try:
|
||||
|
||||
import \_rust\_cl41
|
||||
|
||||
except ImportError:
|
||||
|
||||
\_rust\_cl41 \= None
|
||||
|
||||
def geometric\_product(A, B):
|
||||
|
||||
\# Fast path: Rust compiled extension (SIMD-vectorised gather-scatter on CPU)
|
||||
|
||||
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/NumPy Workbench path
|
||||
|
||||
result \= np.zeros(32, dtype=np.float32)
|
||||
|
||||
for i in range(32):
|
||||
|
||||
ai \= A\[i\]
|
||||
|
||||
if ai \== 0.0:
|
||||
|
||||
continue
|
||||
|
||||
for j in range(32):
|
||||
|
||||
bj \= B\[j\]
|
||||
|
||||
if bj \== 0.0:
|
||||
|
||||
continue
|
||||
|
||||
result\[\_TABLE\_IDX\[i, j\]\] \+= \_TABLE\_SIGN\[i, j\] \* ai \* bj
|
||||
|
||||
return result
|
||||
|
||||
### Mandate 2: Implement `_cached_eigh` for Eigendecomposition Memoization
|
||||
|
||||
* **The Drift**: `relax_to_ground` performs a fresh LAPACK `np.linalg.eigh` on every call for non-diagonal Hamiltonians, wasting 50–200 µs of AMX compute per redundant call on identical, frozen `ProblemHamiltonian` instances.
|
||||
* **Refactoring Requirement**: Decorate the LAPACK solver with `functools.lru_cache(maxsize=128)` using the immutable `hamiltonian_id` and `matrix.tobytes()` as canonical keys to guarantee collision resistance.
|
||||
* **Actionable Code**:
|
||||
|
||||
\# core/physics/cognitive\_lifecycle.py
|
||||
|
||||
import functools
|
||||
|
||||
@functools.lru\_cache(maxsize=128)
|
||||
|
||||
def \_cached\_eigh(hamiltonian\_id: str, matrix\_bytes: bytes) \-\> Tuple\[np.ndarray, np.ndarray\]:
|
||||
|
||||
matrix \= np.frombuffer(matrix\_bytes, dtype=np.float64).reshape(32, 32\)
|
||||
|
||||
return np.linalg.eigh(matrix)
|
||||
|
||||
\# Inside relax\_to\_ground / solve\_via\_relaxation:
|
||||
|
||||
def relax\_to\_ground(hamiltonian: ProblemHamiltonian, psi: np.ndarray) \-\> np.ndarray:
|
||||
|
||||
if hamiltonian.is\_diagonal:
|
||||
|
||||
\# Fast path (Third Door)
|
||||
|
||||
evals \= hamiltonian.matrix.diagonal()
|
||||
|
||||
evecs \= np.eye(32, dtype=np.float64)
|
||||
|
||||
else:
|
||||
|
||||
\# Cached AMX-optimized LAPACK path
|
||||
|
||||
evals, evecs \= \_cached\_eigh(hamiltonian.hamiltonian\_id, hamiltonian.matrix.tobytes())
|
||||
|
||||
...
|
||||
|
||||
### Mandate 3: Enforce the Serves-Boundary Cast Contract ($f64 o f32$)
|
||||
|
||||
* **The Drift**: Eigen-relaxation operates in `float64` for numerical precision, but the identity gate (`IdentityCheck`) operates in `float32`. The un-cast handoff silently promotes `float32` axis directions to `float64` at the projection layer, halving NEON SIMD register lane throughput.
|
||||
* **Refactoring Requirement**: Cast the certified wave-field ($\\psi$) to `float32` at the serving boundary (before handing to `IdentityCheck`). The `RelaxationCertificate` retains the `float64` byte-digest as the uncorrupted audit trail.
|
||||
|
||||
---
|
||||
|
||||
## Section 2: Corrective Actions for Boundary Safety (Pillar II — Semantic Rigor)
|
||||
|
||||
### Mandate 4: Eradicate `default=str` and Restore Full 256-bit SHA-256 Keys
|
||||
|
||||
* **The Drift**: 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, which can silently corrupt the Delta-CRDT merge semilattice. Secondly, using `default=str` in `json.dumps` silently coerces non-serializable objects, collapsing different objects with identical string representations.
|
||||
* **Refactoring Requirement**:
|
||||
- Remove `default=str` from `_content_id` to enforce fail-closed behavior on non-serializable elements.
|
||||
- Preserve the full **256-bit SHA-256 hex digest** (64 characters) for all content-addressed CRDT vault merge keys and `TurnEvent` trace hashes.
|
||||
* **Actionable Code**:
|
||||
|
||||
\# core/physics/identity.py / core/physics/cognitive\_lifecycle.py
|
||||
|
||||
def \_content\_id(payload: Mapping\[str, Any\]) \-\> str:
|
||||
|
||||
\# DO NOT use default=str; let non-serializable types raise TypeError (fail-closed)
|
||||
|
||||
raw \= json.dumps(payload, sort\_keys=True, separators=(",", ":"))
|
||||
|
||||
return hashlib.sha256(raw.encode("utf-8")).hexdigest() \# Retain full 64-char 256-bit digest
|
||||
|
||||
### Mandate 5: Enforce the Little-Endian Float64 Byte-Order Assertion
|
||||
|
||||
* **The Drift**: Generating `psi_digest` via `psi.tobytes()` is platform-dependent: it produces little-endian bytes on standard Apple Silicon M1 and x86\_64, but lacks an explicit contract in the codebase.
|
||||
* **Refactoring Requirement**: Ensure that the array is explicitly coerced to little-endian float64 before extracting raw binary bytes for hashing.
|
||||
* **Actionable Code**:
|
||||
|
||||
def \_psi\_digest(psi: np.ndarray) \-\> str:
|
||||
|
||||
\# Explicitly assert and coerce to little-endian float64 before hashing
|
||||
|
||||
arr \= np.ascontiguousarray(psi, dtype=np.float64)
|
||||
|
||||
\# Force little-endian to ensure cross-platform auditability
|
||||
|
||||
arr\_le \= arr.astype(np.dtype(np.float64).newbyteorder('\<'))
|
||||
|
||||
return hashlib.sha256(arr\_le.tobytes()).hexdigest()
|
||||
|
||||
### Mandate 6: Implement the "No Sampled Unimodality Violation" Contract
|
||||
|
||||
* **The Drift**: The previous implementation claimed to "verify the unimodality assumption" of the Fibonacci-section search. However, a finite sample cannot prove global unimodality on the unsampled portions of $\[a, b\]$, and the algorithm used `kappa = 1.0` as a fallback, which silently changes behavior (a hot-path repair violation).
|
||||
* **Refactoring Requirement**:
|
||||
- Rename the validator check to `sampled_unimodality_violation_observed`.
|
||||
- Treat the Fibonacci search strictly as a **Bracketed Local** refinement operator. The caller must provide a pre-bracketed unimodal interval around a known minimum.
|
||||
- If a violation (multi-extrema, flat plateaus) is observed, the operator must raise or return a typed `OptimizationFailure`. It is strictly forbidden from silently defaulting parameters in-path; the active parameters must remain unchanged.
|
||||
|
||||
---
|
||||
|
||||
## Section 3: Strategic Architecture (Pillar III — Third Door)
|
||||
|
||||
### Mandate 7: Enforce Insertion-Order Independent Mode Allocation
|
||||
|
||||
* **The Drift**: Registering new standing-wave mode centroids in the Hyperbolic Atlas using golden-angle or sunflower placements is sequential and susceptible to order sensitivity. If replicas register modes in different arrival orders, they will reconstruct different physical layouts, breaking exact-recall.
|
||||
* **Refactoring Requirement**:
|
||||
- Define `AnchorAllocator` as a pure strategy interface.
|
||||
- Centroid ordinals must be derived strictly from a deterministic CRDT order or a canonical sorted ID rank: $$ ext{ordinal} \= ext{rank}( ext{canonical\_mode\_id})$$ This guarantees that the entire anchor layout is successfully reconstructed on-the-fly from the allocator identity and the ordinal sequence, preserving the *reconstruction-over-storage* doctrine.
|
||||
|
||||
---
|
||||
|
||||
## Section 4: Phase 1 Acceptance Gate (Evaluation Quarantine)
|
||||
|
||||
Every refactored module must reside strictly inside the `evals/` and `calibration/` quarantine zones until it passes the following six high-assurance criteria:
|
||||
|
||||
1. **Accuracy & Parity**: The PyO3 Rust extension and the Python fallback must yield bit-identical multivector coefficients for $N \= 10,000$ random products.
|
||||
2. **Deterministic Replay**: Running `IdentityCheck().check(wave_traj)` repeatedly with identical wave-field inputs must yield matching 256-bit trace hashes across different execution environments.
|
||||
3. **Falsifiability Gating**: The `IdentityCheck` must correctly identify and flag known non-resonant wave-field perturbations (e.g., pure bivector noise on a scalar identity axis) under the exact $Cl(4,1)$ inner product.
|
||||
4. **Honest Failure Gating**: Malformed wave functions, nonfinite values, or degenerate bounds must immediately trigger typed exceptions (`ValueError` / `OptimizationFailure`), rather than silently falling back to legacy paths.
|
||||
5. **Autonomy Invariant**: No search outcome, self-authored proposal, or live-state correction may autonomously modify the active manifold, truth state, or safety/ethics packs without explicit, human-gated review and signed ratification.
|
||||
|
||||
---
|
||||
|
||||
**Authorized Signatory**:
|
||||
Joshua Shay, Lead Architect
|
||||
**Approval Date**:
|
||||
2026-07-17
|
||||
Loading…
Reference in a new issue