test(adr-0241): RED holographic vault — durable standing-wave spectrum, speculative writes, exact-recall reconstruction, restart lock-in

Stub HolographicVaultStore (NotImplemented) + behavioral contract for SPECULATIVE
seal, authorized COHERENT seal, empty-spectrum refuse, restart load/recall,
min_status filter, INV-21 allowlist discipline, no approx-neighbor imports.

core/physics/holographic_vault.py

@@ -0,0 +1,152 @@
+"""
+core/physics/holographic_vault.py
+
+ADR-0241 durable holographic standing-wave spectrum (issue D / vault store).
+
+Session-local WaveManifold modes are not enough for restart lock-in. This
+module is the **durable** standing-wave path:
+
+  * Writes go through ``VaultStore.store`` only (INV-21 one-mutation-path;
+    this module must be allowlisted when GREEN).
+  * Default epistemic status is SPECULATIVE (INV-22/23); COHERENT only via
+    explicit authorized seal (INV-29 transitions stay in vault/store.py).
+  * Recall is resonant lock-in over stored modes (reconstruction-over-storage),
+    using algebraic reverse-product energy only (no approximate neighbor search).
+  * Empty spectrum / cold start refuses confabulated recall.
+
+Status: RED stubs (#21-adjacent productization). GREEN implements seal/load/recall.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional, Sequence
+
+import numpy as np
+
+from algebra.cl41 import N_COMPONENTS
+from teaching.epistemic import EpistemicStatus
+from vault.store import VaultStore
+
+_SCHEMA = "holographic_mode_v1"
+_KIND = "standing_wave_mode"
+_CLOSURE_TOL = 1e-6
+
+
+class HolographicVaultError(ValueError):
+    """Fail-closed refusal from holographic vault operations."""
+
+    def __init__(self, reason: str, **disclosure: Any) -> None:
+        self.reason = reason
+        self.disclosure = dict(disclosure)
+        super().__init__(f"holographic_vault refused [{reason}]: {self.disclosure}")
+
+
+@dataclass(frozen=True, slots=True)
+class SealedMode:
+    """One durable standing-wave mode as reconstructed from the vault."""
+
+    mode: np.ndarray
+    vault_index: int
+    epistemic_status: EpistemicStatus
+    mode_id: str
+    metadata: dict[str, Any]
+
+
+class HolographicVaultStore:
+    """Durable standing-wave spectrum backed by VaultStore + WaveManifold recall.
+
+    Does not invent a parallel memory path: every durable write is
+    ``VaultStore.store``. Session manifold is a reconstruction cache.
+    """
+
+    def __init__(
+        self,
+        vault: Optional[VaultStore] = None,
+        *,
+        epsilon_drift: float = 1e-6,
+    ) -> None:
+        self._vault = vault if vault is not None else VaultStore()
+        self.epsilon_drift = float(epsilon_drift)
+        # Session reconstruction cache — never the sole source of truth.
+        self._mode_ids: list[str] = []
+
+    @property
+    def vault(self) -> VaultStore:
+        return self._vault
+
+    def seal_mode(
+        self,
+        psi: np.ndarray,
+        *,
+        mode_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> SealedMode:
+        """Persist a standing-wave mode as SPECULATIVE (default admission).
+
+        Refuses non-closed / high-drift states. Never writes COHERENT.
+        """
+        raise NotImplementedError(
+            "HolographicVaultStore.seal_mode: ADR-0241 holographic vault GREEN pending"
+        )
+
+    def seal_mode_reviewed(
+        self,
+        psi: np.ndarray,
+        *,
+        authorized: bool = False,
+        mode_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> SealedMode:
+        """Persist a mode as COHERENT — only with explicit authorization.
+
+        Unauthorized calls refuse (proposal-only; same discipline as GoldTether
+        promote). Does not self-authorize.
+        """
+        raise NotImplementedError(
+            "HolographicVaultStore.seal_mode_reviewed: ADR-0241 GREEN pending"
+        )
+
+    def load_spectrum(
+        self,
+        *,
+        min_status: EpistemicStatus | None = None,
+    ) -> tuple[SealedMode, ...]:
+        """Rebuild the standing-wave spectrum from the vault (restart path).
+
+        Reconstruction-over-storage: manifold cache is cleared and refilled
+        from vault entries tagged as standing-wave modes.
+        """
+        raise NotImplementedError(
+            "HolographicVaultStore.load_spectrum: ADR-0241 GREEN pending"
+        )
+
+    def resonant_recall(
+        self,
+        psi_query: np.ndarray,
+        *,
+        min_status: EpistemicStatus | None = None,
+    ) -> tuple[np.ndarray, float, int, SealedMode]:
+        """Resonant lock-in over the durable spectrum.
+
+        Empty spectrum / cold start without load → refuse (no confabulation).
+        Uses algebraic reverse-product energy, never cosine/ANN.
+        """
+        raise NotImplementedError(
+            "HolographicVaultStore.resonant_recall: ADR-0241 GREEN pending"
+        )
+
+    def spectrum_size(self) -> int:
+        """Number of standing-wave modes currently in the reconstruction cache."""
+        raise NotImplementedError(
+            "HolographicVaultStore.spectrum_size: ADR-0241 GREEN pending"
+        )
+
+
+__all__ = [
+    "HolographicVaultError",
+    "HolographicVaultStore",
+    "SealedMode",
+    "_SCHEMA",
+    "_KIND",
+]

tests/test_adr_0241_holographic_vault.py

@@ -0,0 +1,221 @@
+"""ADR-0241 durable holographic vault — RED behavioral contract.
+
+Durable standing-wave spectrum behind VaultStore (no parallel memory):
+  * SPECULATIVE writes by default; COHERENT only when authorized
+  * Exact-recall reconstruction-over-storage / restart lock-in
+  * WaveManifold resonant energy (no cosine / ANN / HNSW)
+  * Zero confabulation on empty / cold start
+  * Refuse non-closed / high-drift seals
+  * INV-21: durable path uses VaultStore.store (allowlist when GREEN)
+
+GREEN implements ``core.physics.holographic_vault.HolographicVaultStore``.
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+from algebra.rotor import make_rotor_from_angle
+from algebra.versor import versor_condition
+from teaching.epistemic import EpistemicStatus
+from vault.store import VaultStore
+
+# Hard-import — collection fails only if package broken; RED is behavioral NI.
+from core.physics.holographic_vault import (
+    HolographicVaultError,
+    HolographicVaultStore,
+    SealedMode,
+)
+
+
+def _id() -> np.ndarray:
+    v = np.zeros(32, dtype=np.float64)
+    v[0] = 1.0
+    return v
+
+
+def _closed(angle: float = 0.3, plane: int = 6) -> np.ndarray:
+    return make_rotor_from_angle(angle, bivector_idx=plane)
+
+
+def _dirty() -> np.ndarray:
+    v = np.zeros(32, dtype=np.float64)
+    v[0] = 0.5
+    v[1] = 0.5
+    return v
+
+
+# --- Seal / epistemic standing ------------------------------------------------
+
+
+def test_seal_mode_defaults_to_speculative():
+    hv = HolographicVaultStore(VaultStore())
+    sealed = hv.seal_mode(_closed(0.2), mode_id="m0")
+    assert isinstance(sealed, SealedMode)
+    assert sealed.epistemic_status is EpistemicStatus.SPECULATIVE
+    assert sealed.mode_id == "m0"
+    assert versor_condition(sealed.mode) < 1e-6
+
+
+def test_seal_mode_refuses_non_closed():
+    hv = HolographicVaultStore(VaultStore())
+    with pytest.raises((HolographicVaultError, ValueError), match="closed|versor|drift|residual"):
+        hv.seal_mode(_dirty(), mode_id="bad")
+
+
+def test_seal_mode_reviewed_refuses_without_authorization():
+    hv = HolographicVaultStore(VaultStore())
+    with pytest.raises((HolographicVaultError, ValueError), match="authoriz|ADR|gate"):
+        hv.seal_mode_reviewed(_closed(0.15), authorized=False, mode_id="m1")
+
+
+def test_seal_mode_reviewed_coherent_when_authorized():
+    hv = HolographicVaultStore(VaultStore())
+    sealed = hv.seal_mode_reviewed(_closed(0.15), authorized=True, mode_id="m1")
+    assert sealed.epistemic_status is EpistemicStatus.COHERENT
+
+
+# --- Zero confabulation / cold start -----------------------------------------
+
+
+def test_resonant_recall_refuses_empty_spectrum():
+    hv = HolographicVaultStore(VaultStore())
+    with pytest.raises((HolographicVaultError, ValueError), match="empty|confabul|cold|spectrum"):
+        hv.resonant_recall(_closed(0.1))
+
+
+def test_load_spectrum_empty_is_empty_tuple():
+    hv = HolographicVaultStore(VaultStore())
+    modes = hv.load_spectrum()
+    assert modes == ()
+    assert hv.spectrum_size() == 0
+
+
+# --- Durable spectrum + restart lock-in --------------------------------------
+
+
+def test_seal_then_new_instance_reload_and_recall():
+    """Restart path: new HolographicVaultStore on same VaultStore recovers mode."""
+    vault = VaultStore()
+    hv1 = HolographicVaultStore(vault)
+    psi = _closed(0.45, plane=7)
+    sealed = hv1.seal_mode(psi, mode_id="restart-me")
+    assert sealed.vault_index >= 0
+
+    # Cold reconstruction cache
+    hv2 = HolographicVaultStore(vault)
+    loaded = hv2.load_spectrum()
+    assert len(loaded) >= 1
+    assert any(m.mode_id == "restart-me" for m in loaded)
+
+    mode, energy, idx, sealed_hit = hv2.resonant_recall(psi)
+    assert energy > 0.0
+    assert sealed_hit.mode_id == "restart-me"
+    assert np.allclose(mode, psi, atol=1e-5)
+
+
+def test_recall_prefers_matching_mode_among_several():
+    vault = VaultStore()
+    hv = HolographicVaultStore(vault)
+    a = _closed(0.2, plane=6)
+    b = _closed(0.9, plane=7)
+    hv.seal_mode(a, mode_id="A")
+    hv.seal_mode(b, mode_id="B")
+    hv.load_spectrum()
+    _mode, _E, _i, hit = hv.resonant_recall(b)
+    assert hit.mode_id == "B"
+
+
+def test_min_status_coherent_excludes_speculative():
+    """INV-24 style: evidence-tier recall can require COHERENT."""
+    vault = VaultStore()
+    hv = HolographicVaultStore(vault)
+    psi = _closed(0.3)
+    hv.seal_mode(psi, mode_id="spec-only")  # SPECULATIVE
+    loaded = hv.load_spectrum(min_status=EpistemicStatus.COHERENT)
+    assert all(m.epistemic_status is EpistemicStatus.COHERENT for m in loaded)
+    # Speculative-only spectrum → coherent-filtered empty → no confabulation
+    with pytest.raises((HolographicVaultError, ValueError), match="empty|confabul|spectrum|status"):
+        hv.resonant_recall(psi, min_status=EpistemicStatus.COHERENT)
+
+
+def test_determinism_seal_and_recall():
+    vault = VaultStore()
+    hv = HolographicVaultStore(vault)
+    psi = _closed(0.55, plane=8)
+    hv.seal_mode(psi, mode_id="det")
+    hv.load_spectrum()
+    r1 = hv.resonant_recall(psi)
+    r2 = hv.resonant_recall(psi)
+    assert r1[1] == r2[1]
+    assert r1[2] == r2[2]
+    assert r1[3].mode_id == r2[3].mode_id
+
+
+# --- Mutation path / hygiene --------------------------------------------------
+
+
+def test_seal_uses_vault_store_not_parallel_memory():
+    """After seal, VaultStore holds the versor (same mutation path)."""
+    vault = VaultStore()
+    hv = HolographicVaultStore(vault)
+    psi = _closed(0.25)
+    sealed = hv.seal_mode(psi, mode_id="vpath")
+    assert len(vault) > 0 or sealed.vault_index >= 0
+    # VaultStore may expose __len__ via versor deque — prefer index check
+    assert sealed.vault_index == 0 or sealed.vault_index >= 0
+
+
+def test_module_has_no_teaching_import_except_epistemic_status():
+    """Physics holographic path may import EpistemicStatus only from teaching.epistemic."""
+    path = Path(__file__).resolve().parents[1] / "core/physics/holographic_vault.py"
+    tree = ast.parse(path.read_text())
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom) and node.module:
+            if node.module.startswith("teaching") and node.module != "teaching.epistemic":
+                raise AssertionError(f"unexpected teaching import: {node.module}")
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                assert not alias.name.startswith("teaching.")
+
+
+def test_module_source_forbids_approx_neighbor_stack():
+    """Implementation must not import approximate-neighbor tooling."""
+    src = Path(__file__).resolve().parents[1].joinpath(
+        "core/physics/holographic_vault.py"
+    ).read_text()
+    tree = ast.parse(src)
+    banned_mods = {"faiss", "hnswlib", "annoy", "sklearn.neighbors"}
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                assert alias.name.split(".")[0] not in banned_mods
+        if isinstance(node, ast.ImportFrom) and node.module:
+            root = node.module.split(".")[0]
+            assert node.module not in banned_mods and root not in banned_mods
+
+
+def test_inv21_writer_allowlist_mentions_holographic_or_no_store_call_yet():
+    """INV-21: either allowlisted, or (RED) no live .store() call outside NI.
+
+    GREEN must add ``core/physics/holographic_vault.py`` to ALLOWED_VAULT_WRITERS.
+    """
+    from tests.test_architectural_invariants import ALLOWED_VAULT_WRITERS
+
+    rel = "core/physics/holographic_vault.py"
+    src = Path(__file__).resolve().parents[1].joinpath(rel).read_text()
+    # Detect a real store call pattern (not in strings only is hard; use AST)
+    tree = ast.parse(src)
+    has_store_call = False
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute):
+            if node.func.attr == "store":
+                has_store_call = True
+    if has_store_call:
+        assert rel in ALLOWED_VAULT_WRITERS, (
+            "holographic_vault calls VaultStore.store but is not INV-21 allowlisted"
+        )