feat(reference): Multiverseal Twin substrate reference impl [E13/WS-C]

reference/multiverseal-twin/README.md

@@ -0,0 +1,35 @@
+# Multiverseal Twin — reference implementation (WS-C)
+
+Executable substrate for `schemas/{MultiversealTwin,TwinAttestation,InterferometricDiff}.json`
+(ADR-0014), Epoch E13 / WS-C. Instantiated on **FHRR** (Fourier Holographic Reduced
+Representations): the twin space is `V = C^D` of unit-modulus phasors, so *phase = provenance*
+is literal.
+
+```
+bind(o, r)   = o ⊙ r          record object against reference (reference-at-ingest)
+bundle(ts)   = Σ t_k          superpose into the opaque twin medium H
+unbind(H, r) = H ⊙ conj(r)    reconstruct — requires the reference
+```
+
+## Run the self-test
+
+```bash
+python3 test_mvtwin.py
+```
+
+It proves, with measured numbers, the four load-bearing properties:
+
+| Property | Measured (D=8192, N=8) |
+|---|---|
+| **Reference-gating** — authored reference reconstructs; un-authored/absent = noise | recover **0.348** vs wrong-ref **0.003**, opaque **−0.009** (~100× SNR) |
+| **ε-unlinkability** — distinct context references are near-orthogonal | cross-context leakage **L=0.004** |
+| **Fringe is the leading indicator** — a small drift barely moves the score but shows in the fringe | score move **0.00016** vs mean\|fringe\| **0.020** (~125×) |
+| **Holographic tamper-evidence** — one local write perturbs the fringe globally | **100%** of spectrum perturbed |
+
+## Scope
+
+This is the **linear substrate only**. Reference-at-ingest, the ε-budget, VRF mint/verify,
+and the impersonation wall are enforced at the contract/policy layer (ADR-0014); Sybil-
+resistance and nonlinear trust weighting live in a **separate** layer that must not leak back
+into this medium (twin spec §H / WS-F). Next increments: wire `bind` to a real VRF reference;
+QEC `[[n,k,d]]` sharing; the `InterferometricDiff` replay (Fresnel forward-propagation).

reference/multiverseal-twin/mvtwin.py

@@ -0,0 +1,76 @@
+"""Multiverseal Twin — reference implementation of the holographic substrate.
+
+Epoch E13 / WS-C. Executable substrate for the contracts in
+schemas/{MultiversealTwin,TwinAttestation,InterferometricDiff}.json (ADR-0014).
+
+Instantiated on FHRR (Fourier Holographic Reduced Representations, Plate): the twin space
+is V = C^D of unit-modulus phasors, so *phase = provenance* is literal. Three operators:
+
+    bind(o, r)   = o ⊙ r            record object o against reference r
+    bundle(ts)   = Σ t_k            superpose records into the opaque twin medium H
+    unbind(H, r) = H ⊙ conj(r)      correlate with the reference to reconstruct
+
+Reference-gating: without r_j, H is a sum of pseudo-random phasors — a hiding commitment;
+reconstruction requires the reference (the public-twin / private-reconstruction primitive).
+The primary read is the fringe (Δφ), not the score. This module is the linear substrate ONLY;
+Sybil-resistance and nonlinear trust policy live in a separate layer (twin spec §H / WS-F).
+"""
+from __future__ import annotations
+import numpy as np
+
+
+def reference(D: int, rng: np.random.Generator) -> np.ndarray:
+    """A near-orthogonal, high-entropy unit-modulus reference r_c.
+
+    Stands in for a VRF-derived context reference: VRF outputs are pseudorandom, hence the
+    near-orthogonal references §A/§1 of the spec assume. Mint/verify and the ε-budget share
+    this one primitive.
+    """
+    return np.exp(1j * rng.uniform(0.0, 2.0 * np.pi, size=D))
+
+
+def obj(D: int, rng: np.random.Generator) -> np.ndarray:
+    """An attestation's object beam o_k (a claim vector), as a unit-modulus phasor."""
+    return np.exp(1j * rng.uniform(0.0, 2.0 * np.pi, size=D))
+
+
+def bind(o: np.ndarray, r: np.ndarray) -> np.ndarray:
+    """t = bind(o, r). Reference-at-ingest: a foreign claim is admitted only bound."""
+    return o * r
+
+
+def bundle(ts: list[np.ndarray]) -> np.ndarray:
+    """H = Σ t_k. The superposed, opaque-without-a-reference twin medium."""
+    return np.sum(np.stack(ts, axis=0), axis=0)
+
+
+def unbind(H: np.ndarray, r: np.ndarray) -> np.ndarray:
+    """ô = unbind(H, r) = H ⊙ conj(r); returns o + crosstalk η."""
+    return H * np.conjugate(r)
+
+
+def similarity(a: np.ndarray, b: np.ndarray) -> float:
+    """Normalized real correlation in [-1, 1]; the 'magnitude' (raw score) read."""
+    na, nb = np.linalg.norm(a), np.linalg.norm(b)
+    if na == 0 or nb == 0:
+        return 0.0
+    return float(np.real(np.vdot(a, b)) / (na * nb))
+
+
+def interferometric_diff(H_live: np.ndarray, H_stored: np.ndarray) -> np.ndarray:
+    """The primary read: the fringe Δφ = arg(H_live ⊙ conj(H_stored)).
+
+    Phase moves below the magnitude at which a scalar score would move (leading indicator).
+    A local unauthorized write perturbs the fringe globally (tamper-evident for free).
+    """
+    return np.angle(H_live * np.conjugate(H_stored))
+
+
+def unlinkability_leakage(r_a: np.ndarray, r_b: np.ndarray) -> float:
+    """L(c,c') = |<r_c, r_c'>| / D. Two contexts are ε-unlinkable iff this ≤ ε.
+
+    The SAME ε bounds crosstalk, capacity, and unlinkability — and is the reversibility-
+    distance budget of the reidentification economy.
+    """
+    D = r_a.shape[0]
+    return float(np.abs(np.vdot(r_a, r_b)) / D)

reference/multiverseal-twin/test_mvtwin.py

@@ -0,0 +1,63 @@
+"""Self-test proving the twin substrate's load-bearing properties (WS-C).
+
+Run: python3 test_mvtwin.py   (asserts + prints the measured numbers)
+"""
+from __future__ import annotations
+import numpy as np
+import mvtwin as mv
+
+
+def build_twin(D, N, rng):
+    objs = [mv.obj(D, rng) for _ in range(N)]
+    refs = [mv.reference(D, rng) for _ in range(N)]
+    ts = [mv.bind(o, r) for o, r in zip(objs, refs)]
+    return objs, refs, ts, mv.bundle(ts)
+
+
+def main() -> int:
+    D, N = 8192, 8
+    rng = np.random.default_rng(0)
+    objs, refs, ts, H = build_twin(D, N, rng)
+
+    # 1) Recovery: unbind with the right reference recovers the object, far above baseline.
+    rec = mv.similarity(mv.unbind(H, refs[0]), objs[0])
+    wrong = mv.similarity(mv.unbind(H, mv.reference(D, rng)), objs[0])   # un-authored angle
+    opaque = mv.similarity(H, objs[0])                                    # no reference at all
+    print(f"[1] recover={rec:.3f}  wrong-ref={wrong:.3f}  opaque(no-ref)={opaque:.3f}")
+    assert rec > 0.20, "authored reference must reconstruct"
+    assert abs(wrong) < 0.05 and abs(opaque) < 0.05, "opaque/un-authored angles must be noise"
+    assert rec > 10 * max(abs(wrong), abs(opaque)), "recovery must dominate noise"
+
+    # 2) ε-unlinkability: two VRF-style references are near-orthogonal (small leakage).
+    leak = mv.unlinkability_leakage(refs[0], refs[1])
+    print(f"[2] cross-context leakage L={leak:.4f}  (ε-unlinkable for ε≳{leak:.3f})")
+    assert leak < 0.05, "distinct context references must be near-orthogonal"
+
+    # 3) Interferometric diff is a LEADING indicator: a small phase drift on ONE attestation
+    #    barely moves the scalar score, but shows clearly in the fringe.
+    delta = 0.05  # radians
+    ts2 = list(ts); ts2[0] = ts[0] * np.exp(1j * delta)
+    H_live = mv.bundle(ts2)
+    score_move = 1.0 - mv.similarity(H_live, H)
+    fringe = mv.interferometric_diff(H_live, H)
+    fringe_signal = float(np.mean(np.abs(fringe)))
+    print(f"[3] scalar-score move={score_move:.5f}   mean|fringe|={fringe_signal:.5f}")
+    assert score_move < 0.02, "scalar score should barely move (lagging)"
+    assert fringe_signal > 5 * score_move, "fringe must lead the scalar score"
+
+    # 4) Holographic tamper-evidence: a LOCAL write (one time-domain sample) perturbs the
+    #    fringe GLOBALLY across the spectrum — tamper detectable without knowing what changed.
+    H_time = np.fft.ifft(H)
+    H_time[123] += 0.5 + 0.5j          # single local unauthorized write
+    H_tampered = np.fft.fft(H_time)
+    tamper_fringe = np.abs(mv.interferometric_diff(H_tampered, H))
+    frac_global = float(np.mean(tamper_fringe > 1e-6))
+    print(f"[4] fraction of spectrum perturbed by ONE local write={frac_global:.3f}")
+    assert frac_global > 0.9, "a local write must perturb the fringe globally (holographic)"
+
+    print("\nALL PROPERTIES HOLD — reference-gating, ε-unlinkability, fringe-as-leading-indicator, holographic tamper-evidence.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())