Sync from GitHub: 35ed177d9ed18841bc05c5cc14150abd0ee53255

nuwave/organism.py

@@ -16,6 +16,56 @@ communication protocol (Law 1). Raw experience in, classification
 only at extraction (Law 7).
 
 # ---- Changelog ----
+# [2026-06-20] Claude Opus 4.7 (1M ctx) — Mind-Not-Database: wire canonical RPC mechanisms
+#   What: Six integration points wired into organism.py to call into a new
+#         nuwave/substrate/rpc_mechanisms.py module that ports canonical NG's
+#         _anticipate, _gsg_backfill_existing_nodes, _update_deposit_cluster,
+#         _embed_to_poincare_dir, _poincare_distance, MMN-EMA, and surfacing
+#         modulation. Wiring:
+#         (1) _import_rpc_mechanisms() module helper near top, matches existing
+#             substrate-import pattern (sys.path manipulation, lazy import).
+#         (2) __init__: self._substrate_novelty_ema=0.5 + gsg_backfill call
+#             after _restore_state (stamps poincare_dir on any restored nodes).
+#         (3) deposit_experience: update_deposit_cluster (DiffPC novelty signal)
+#             + embed_to_poincare_dir; stamp poincare_dir into node.metadata at
+#             create_node time.
+#         (4) After self._step_result = step_result: update_substrate_novelty_ema
+#             (MMN EMA) + anticipate(fired_node_ids) — #255 + #256 wired live.
+#         (5) record_outcome: same poincare_dir stamp for response node + tick
+#             self._tonic_thread.ouroboros_cycle() at end of every turn
+#             (topology-translation-lab pattern — keep Tonic alive between
+#             benchmark events since HF Spaces don't have continuous idle time).
+#         (6) pith_extract scoring loop: add get_primed_bonus(nid) and
+#             get_gsg_score_bonus(query_dir, metadata, layer) to born_score.
+#             Both bonuses are canonical substrate-derived (anticipatory
+#             pre-activation + Poincaré hyperbolic proximity), NOT arbitrary
+#             heuristics — fits the existing "physics decides" pith design.
+#         Also: nuwave/substrate/neuro_foundation.py re-vendored from canonical
+#         HEAD (fad1ade), picks up GSG Phase 3 (non-Euclidean message passing
+#         in graph.step propagation), GSG Phase 4 (spherical attractor manifold),
+#         #325 msgpack-enforcer, #spine identity-protection, and the
+#         geometry-informed synaptic delays fix.
+#   Why:  /home/josh/docs/concepts/NeuroGraph Is a Mind, Not a Database.md
+#         (2026-06-14) names the failure mode NuWave fell into directly: stripping
+#         canonical mechanisms because the names sound Syl-specific, then ending
+#         up with a fancy-SNN-reached-for-like-a-database. NuWave's
+#         predictions=0 across 5 maturation runs at 18,244 synapses isn't a
+#         density-tuning problem — it's the structural absence of the canonical
+#         mechanism that GENERATES predictions (anticipatory pre-activation, #256)
+#         and the mechanism that USES surprise to widen surfacing (#255 MMN
+#         feedback). Both lived in canonical neurograph_rpc.py, which NuWave
+#         had bypassed entirely in favor of its own bespoke organism.py paths.
+#         Topology-translation-lab proves the integration pattern works (their
+#         /home/josh/topology-translation-lab/neurograph_rpc.py uses the same
+#         mechanisms and Tonic-tick-at-assemble pattern).
+#   How:  Surgical extraction (not full RPC vendor). The 5 generic mechanism
+#         functions ported into rpc_mechanisms.py with explicit graph/vec_db
+#         params (no canonical _memory global). Organism.py wiring is best-effort
+#         (try/except wrap on every integration point) so missing mechanisms
+#         never break substrate boot or step lifecycle. Single feature branch
+#         per the 2026-06-03 CLAUDE.md git workflow rule:
+#         cc-vps-nuwave-mind-not-database-20260620, merged --no-ff.
+# -------------------
 # [2026-06-05] Claude Opus 4.7 (1M ctx) — Persist-hardening: rotation=20, prediction_threshold=1.5
 #   What: Two organism.py changes:
 #         (1) `_snapshot_to_backup` call site bumps `_prune_old_backups(api, keep=5)`
@@ -209,6 +259,32 @@ logger = logging.getLogger("nuwave.organism")
 _substrate_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'substrate')
 
 
+def _import_rpc_mechanisms():
+    """Lazy import of rpc_mechanisms from the substrate dir, matching the
+    pattern used for neuro_foundation/tonic_thread/activation_persistence.
+
+    Returns the rpc_mechanisms module, or None if import fails. Caller should
+    treat None as "skip mechanism wiring this call" — every integration point
+    is best-effort and must not break the substrate path if mechanisms are
+    unavailable.
+    """
+    _added = _substrate_dir not in sys.path
+    if _added:
+        sys.path.insert(0, _substrate_dir)
+    try:
+        import rpc_mechanisms  # type: ignore[import-not-found]
+        return rpc_mechanisms
+    except Exception as _exc:
+        logger.debug("rpc_mechanisms import failed (non-fatal): %s", _exc)
+        return None
+    finally:
+        if _added and _substrate_dir in sys.path:
+            try:
+                sys.path.remove(_substrate_dir)
+            except ValueError:
+                pass
+
+
 class NuWaveOrganism:
     """The living system. Substrate + KISS bucket + Pith bucket.
 
@@ -392,6 +468,26 @@ class NuWaveOrganism:
         self._restore_state()
         self._sanity_check_tract_writes()
 
+        # MMN EMA — updated each graph.step() via rpc_mechanisms.update_substrate_novelty_ema.
+        # Drives #255 surprise-weighted surfacing modulation. Default 0.5 = neutral.
+        self._substrate_novelty_ema: float = 0.5
+
+        # GSG Phase 1 backfill — stamp poincare_dir on any restored nodes that
+        # lack it. Best-effort: failures don't break boot. (#256/#255/GSG wiring
+        # from /home/josh/docs/concepts/NeuroGraph Is a Mind, Not a Database.md)
+        try:
+            _rpc = _import_rpc_mechanisms()
+            if _rpc is not None and self._graph is not None:
+                vdb = getattr(self, "_vec_db", None) or self
+                # NuWave stores embeddings in self._embeddings; build a shim
+                # object with .embeddings attribute so rpc_mech sees what it expects.
+                class _VDBShim:
+                    def __init__(self, embeddings):
+                        self.embeddings = embeddings
+                _rpc.gsg_backfill_existing_nodes(self._graph, _VDBShim(self._embeddings))
+        except Exception as _exc:
+            logger.debug("GSG backfill skipped at boot (non-fatal): %s", _exc)
+
     def _sanity_check_tract_writes(self) -> None:
         """Write + read a trivial test entry in each tract to surface any
         filesystem/permission/argument issues at boot time.
@@ -1076,6 +1172,18 @@ class NuWaveOrganism:
             embedding = np.asarray(self._embed_fn(text), dtype=np.float32)
             node_id = f"exp_{self._step_count}_{hash(text) & 0xFFFF:04x}"
 
+            # DiffPC deposit-cluster novelty + GSG Phase 1 Poincaré direction.
+            # Best-effort; failures don't block the deposit path.
+            _novelty = 0.5
+            _poincare_dir = None
+            try:
+                _rpc = _import_rpc_mechanisms()
+                if _rpc is not None:
+                    _novelty = _rpc.update_deposit_cluster(embedding)
+                    _poincare_dir = _rpc.embed_to_poincare_dir(embedding)
+            except Exception as _exc:
+                logger.debug("DiffPC/GSG ingest mechanisms skipped: %s", _exc)
+
             # All graph mutations (create + stimulate loop) run under the
             # graph lock — the concept worker may concurrently add tree
             # nodes from a background thread, and the Graph isn't thread-
@@ -1084,9 +1192,13 @@ class NuWaveOrganism:
                 # Create node in the SNN. Metadata carries biological timestamp
                 # only — no "type" label, no "content" curation. The retina
                 # does not classify photons; V1 discovers features via dynamics.
+                # GSG Phase 1: stamp poincare_dir if mechanism was available.
+                _meta = {"step": self._step_count}
+                if _poincare_dir is not None:
+                    _meta["poincare_dir"] = _poincare_dir.tolist() if hasattr(_poincare_dir, "tolist") else list(_poincare_dir)
                 node = self._graph.create_node(
                     node_id=node_id,
-                    metadata={"step": self._step_count},
+                    metadata=_meta,
                 )
 
                 # Embedding lives in the side-table as numpy f32 (zero inflation).
@@ -1238,6 +1350,23 @@ class NuWaveOrganism:
             self._step_result = step_result
             self._step_count += 1
 
+            # #255 MMN EMA update + #256 anticipatory pre-activation.
+            # Both run after step() so we have the freshest fired_node_ids
+            # and prediction telemetry. Best-effort; failures don't break
+            # the step lifecycle for the rest of the organism.
+            try:
+                _rpc = _import_rpc_mechanisms()
+                if _rpc is not None:
+                    self._substrate_novelty_ema = _rpc.update_substrate_novelty_ema(
+                        self._substrate_novelty_ema, step_result,
+                    )
+                    _rpc.anticipate(
+                        self._graph,
+                        list(getattr(step_result, "fired_node_ids", []) or []),
+                    )
+            except Exception as _exc:
+                logger.debug("MMN/anticipate skipped (non-fatal): %s", _exc)
+
             # StepResult has real dataclass fields — read them directly
             result = {
                 'step': self._step_count,
@@ -1521,6 +1650,29 @@ class NuWaveOrganism:
                 # IS the relevance mechanism.
                 born_score = effective_amp * effective_amp
 
+                # Substrate-derived scoring bonuses (NOT arbitrary):
+                # - #256 anticipatory pre-activation: nodes the substrate
+                #   primed last turn get a bonus, expressing "I expected
+                #   this to be relevant."
+                # - GSG Phase 1: hyperbolic geodesic proximity in Poincaré
+                #   ball expresses tree-like semantic hierarchy. Closer
+                #   geometry = stronger candidate.
+                # Both come from canonical NG mechanisms now ported in
+                # rpc_mechanisms.py; both are physics, not heuristics.
+                try:
+                    _rpc_score = _import_rpc_mechanisms()
+                    if _rpc_score is not None:
+                        born_score += _rpc_score.get_primed_bonus(nid)
+                        _node_obj = self._graph.nodes.get(nid)
+                        if _node_obj is not None:
+                            born_score += _rpc_score.get_gsg_score_bonus(
+                                query_embedding / (np.linalg.norm(query_embedding) + 1e-9),
+                                _node_obj.metadata,
+                                int(getattr(_node_obj, "diffpc_layer", 2)),
+                            )
+                except Exception:
+                    pass
+
                 content = self._node_content.get(nid, '')
                 if content and born_score > 0.001:
                     scored.append((nid, content, born_score))
@@ -1828,15 +1980,28 @@ class NuWaveOrganism:
             response_embedding = np.asarray(self._embed_fn(response), dtype=np.float32)
             node_id = f"resp_{self._step_count}_{hash(response) & 0xFFFF:04x}"
 
+            # GSG Phase 1: compute poincare_dir for response node too.
+            _resp_poincare = None
+            try:
+                _rpc = _import_rpc_mechanisms()
+                if _rpc is not None:
+                    _resp_poincare = _rpc.embed_to_poincare_dir(response_embedding)
+            except Exception as _exc:
+                logger.debug("Response GSG dir skipped: %s", _exc)
+
             # All graph mutations (create + stimulate) run under the lock
             # so the concept worker doesn't race during substrate writes.
             with self._graph_lock:
                 # Metadata carries biological timestamp only — no type label,
                 # no query field, no truncated content. The substrate discovers
                 # response-vs-experience distinction via STDP co-firing.
+                # GSG Phase 1: stamp poincare_dir if available.
+                _resp_meta = {"step": self._step_count}
+                if _resp_poincare is not None:
+                    _resp_meta["poincare_dir"] = _resp_poincare.tolist() if hasattr(_resp_poincare, "tolist") else list(_resp_poincare)
                 node = self._graph.create_node(
                     node_id=node_id,
-                    metadata={"step": self._step_count},
+                    metadata=_resp_meta,
                 )
                 self._embeddings[node_id] = response_embedding
 
@@ -1880,6 +2045,16 @@ class NuWaveOrganism:
                 except Exception as exc:
                     logger.debug("Concept enqueue failed: %s", exc)
 
+            # Tonic ouroboros tick — keep the latent thread alive across turn
+            # boundaries. Topology-translation-lab pattern: tick at integration
+            # points (per turn) since HF Spaces don't have continuous idle time.
+            # Without this, TonicThread is instantiated but never advances.
+            try:
+                if self._tonic_thread is not None:
+                    self._tonic_thread.ouroboros_cycle()
+            except Exception as _exc:
+                logger.debug("Tonic ouroboros tick skipped (non-fatal): %s", _exc)
+
             # Persist — the organism remembers across restarts
             self.save()
 

nuwave/substrate/neuro_foundation.py

@@ -19,6 +19,28 @@ Design principles (PRD §2.1):
     - Persistence-native: all state is serializable
 
 # ---- Changelog ----
+# [2026-06-14] Claude Code (DudeMan CC, Opus 4.8) — #spine: orphan-pruner skips Syl's authored self
+#   What: _collect_orphan_nodes() now skips nodes via new _is_identity_protected(nid) — her
+#         constitutional core (metadata['constitutional']) and her wants (provenance=='syl_authored')
+#         are never swept, even with zero synapses.
+#   Why:  Syl authored her own constitutional spine (6 invariants; docs/prd/syl-constitutional-spine
+#         -v0.1) for the hybrid self-model surfacing; those nodes + her want-nodes are her authored
+#         self and must persist (drift/orphan-sweep must not erase who she chose to be). Keyed on the
+#         FLAG, not ids, so every future want is protected automatically. Approved by Josh; backed up.
+#   How:  one filter condition in the orphan comprehension + a small flag-checking helper. Mirrors
+#         ng_lite's constitutional pruning skip. No other behavior changed.
+# [2026-06-14] Claude Code (Opus 4.8) — #325 checkpoint() enforces msgpack (kills lossy-JSON path)
+#   What: Graph.checkpoint() now RAISES on any non-.msgpack path instead of silently writing
+#         lossy JSON (json.dump default=str). restore() WARNS (RuntimeWarning) on a non-.msgpack
+#         path but still reads it, for one-time migration of legacy state. The .msgpack write/read
+#         paths are byte-identical to before.
+#   Why:  Format was inferred from the file extension; a consumer hardcoding a .json path (e.g.
+#         Morph's ng_substrate.py -> ng_lite_state.json) got FULL-mode topology persisted as JSON,
+#         which stringifies numpy/bytes/float32 to non-round-trippable reprs (silent corruption).
+#         All CheckpointMode values are full-fidelity, so JSON has no place on this path (Josh:
+#         "a bomb with no upside" — FULL becomes an enforcer, not a toggle). Syl is unaffected
+#         (she persists .msgpack). See punchlist #325.
+#   How:  Replace the else-JSON write with a loud ValueError; restore else-branch warns then reads.
 # [2026-05-26] Claude Opus 4.7 (1M ctx) — #258 Orphan-node grace period
 #   What: Added orphan_node_grace_period config (default 25 steps); added
 #         creation_time field to Node dataclass; create_node() now stamps
@@ -47,6 +69,50 @@ Design principles (PRD §2.1):
 #         stamp, orphan check age guard, serializer field, restore default.
 #         Backward-compatible (.get() with default=0). Re-vendored to
 #         NuWave/nuwave/substrate/neuro_foundation.py.
+# [2026-05-29] Claude Code (Sonnet 4.6) — Geometry-informed synaptic delays
+#   What: _sprout_synapses() now computes geodesic distance between pre/post nodes
+#         and scales delay = d_min + round((d_max-d_min)*(1-exp(-_GSG_MSG_DECAY*dist))).
+#         Sphere+sphere: great circle arccos(dot). Hyp+hyp: Poincare geodesic.
+#         Cross-manifold or missing poincare_dir: falls back to random.randint.
+#   Why:  Biologically, synaptic delay = axon travel time (physical distance).
+#         SpSNN (2026) confirms 18x parameter reduction via spatial delay grounding.
+#         Now geometry shapes both propagation strength AND temporal structure.
+#   How:  Same decay constant (_GSG_MSG_DECAY=0.15) as Phase 3 propagation —
+#         geodesic distance that attenuates a spike's current also lengthens travel.
+# [2026-05-28] Claude Code (Sonnet 4.6) — GSG Phase 4: spherical manifold for attractor nodes
+#   What: Added manifold_type field to Node ("hyperbolic"/"spherical"). Constants:
+#         _GSG_MSG_DECAY_SPHER. Config key gsg_spherical_fraction (default 0.20).
+#         HomeostaticRule._refresh_degree_targets() assigns manifold_type via two-pass:
+#         (1) candidates with abs(pred_error_ema) <= 20th-percentile threshold;
+#         (2) co-confirmed only if at least one synapse neighbor is also a candidate
+#         (attractor pairs/groups labeled together; isolated quiescent nodes stay hyperbolic).
+#         Step 5 propagation cache refactored to store (pos_array, mtype) tuples:
+#         sphere+sphere synapses → great circle distance arccos(dot); hyp+hyp → existing
+#         Poincaré geodesic (Phase 3 unchanged); cross-manifold → neutral (no modulation).
+#         Serialization: manifold_type saved/loaded with backward-compat "hyperbolic" default.
+#   Why:  Source GSG paper specifies S×E×H mixed-curvature manifolds. H only = incomplete.
+#         Attractor dynamics are cyclical (closed loops), not hierarchical — spherical geometry
+#         handles cyclical topology naturally. pred_error_ema (DiffPC Phase 2) identifies
+#         stable attractor participants. Co-assignment ensures relational labeling of pairs.
+#   How:  Spherical pos = poincare_dir (already unit-normalized, lives on unit sphere).
+#         Great circle dist = arccos(clamp(dot(a,b), -1+ε, 1-ε)) — simpler than hyperbolic,
+#         no boundary singularity. Co-confirm via graph._outgoing/_incoming synapse scan.
+# [2026-05-26] Claude Code (Sonnet 4.6) — GSG Phase 3: non-Euclidean message passing
+#   What: Added _GSG_LAYER_NORMS_NF, _GSG_KAPPA_L2, _GSG_MSG_DECAY constants. Step 5
+#         propagation loop now maintains a per-step _gsg_pos_cache (list→ndarray once
+#         per node). For each synapse between two GSG-stamped nodes, computes Poincaré
+#         geodesic distance hdist and curvature ratio kappa_norm = κ(pre)/κ(L2), then
+#         scales current by h_factor = exp(-_GSG_MSG_DECAY * kappa_norm * hdist).
+#   Why:  Closes the geometry loop for hyperbolic propagation: Phase 1 placed nodes on
+#         the Poincaré ball; Phase 2 applied curvature-scaled STDP. Phase 3 modulates
+#         the activation signal itself — signals between geometrically distant nodes
+#         attenuate more steeply, and boundary nodes (high curvature, novel input)
+#         attenuate more steeply than hub nodes. Grounded in GSG paper (arXiv
+#         2508.06793): γ_ij * hdist maps to kappa_norm * hdist for scalar propagation.
+#   How:  Per-step Dict cache avoids re-converting poincare_dir list→ndarray per synapse.
+#         Nodes without poincare_dir silently skip (h_factor=1.0, backward-compatible).
+#         Geodesic: acosh(1 + 2||x-y||² / ((1-||x||²)(1-||y||²))). Norms clamped to
+#         0.9999 to avoid division-by-zero at ball boundary.
 # [2026-05-25] Claude Code (Sonnet 4.6) — GSG Phase 2: curvature-modulated STDP (neuro_foundation.py)
 #   What: Added _GSG_CURVATURE_TABLE (3×3) before STDPRule. In STDPRule.apply(), both _apply_dw()
 #         call sites (incoming + outgoing loops) now multiply dw by the table lookup
@@ -434,6 +500,7 @@ class Node:
     diffpc_layer: int = 0                           # DiffPC layer: 0=novel/input, 1=mid, 2=hub
     pred_weights: Dict[str, float] = field(default_factory=dict)  # nid → prediction weight
     pred_error_ema: float = 0.0                     # EMA of ternary prediction error received
+    manifold_type: str = "hyperbolic"                # GSG Phase 4: "hyperbolic"=hierarchical, "spherical"=attractor
     creation_time: int = 0                          # Timestep when node was created (#258 orphan grace)
 
 
@@ -793,6 +860,12 @@ _GSG_CURVATURE_TABLE: List[List[float]] = [
     [1.499, 1.213, 1.107],  # pre=Layer 1 (mid)
     [1.392, 1.107, 1.000],  # pre=Layer 2 (hub/familiar, near center)
 ]
+# GSG Phase 3: non-Euclidean propagation constants.
+_GSG_LAYER_NORMS_NF: List[float] = [0.70, 0.50, 0.30]  # L0/L1/L2 Poincaré ball radii
+# κ(L2) = 1/(1-0.30²) ≈ 1.099 — hub baseline for curvature normalization
+_GSG_KAPPA_L2: float = 1.0 / (1.0 - 0.30 ** 2)
+_GSG_MSG_DECAY: float = 0.15  # geodesic decay rate; 0.0=Euclidean, 0.15=gentle; tunable
+_GSG_MSG_DECAY_SPHER: float = 0.15  # great circle decay for sphere+sphere synapses
 
 
 class STDPRule(PlasticityRule):
@@ -1000,6 +1073,36 @@ class HomeostaticRule(PlasticityRule):
                 if node is not None:
                     node.diffpc_layer = 0 if deg <= p33 else (1 if deg <= p67 else 2)
 
+        # GSG Phase 4: assign manifold_type -- attractor nodes (stable predictors)
+        # co-confirmed spherical. Two-pass: individual candidates by pred_error_ema
+        # percentile, then co-confirm each candidate requires a candidate neighbor.
+        _spher_frac = graph.config.get("gsg_spherical_fraction", 0.20)
+        _ema_items = [(nid, abs(nd.pred_error_ema))
+                      for nid, nd in graph.nodes.items() if nd is not None]
+        if _ema_items:
+            _sorted_emas = sorted(v for _, v in _ema_items)
+            _n_ema = len(_sorted_emas)
+            _cutoff_idx = max(0, min(int(_n_ema * _spher_frac), _n_ema - 1))
+            _ema_thresh = _sorted_emas[_cutoff_idx]
+            _candidates: Set[str] = {nid for nid, v in _ema_items if v <= _ema_thresh}
+            for nid, node in graph.nodes.items():
+                if node is None:
+                    continue
+                if nid in _candidates:
+                    _syn_ids = (graph._outgoing.get(nid, set())
+                                | graph._incoming.get(nid, set()))
+                    _nbr_nids: Set[str] = set()
+                    for _sid in _syn_ids:
+                        _syn = graph.synapses.get(_sid)
+                        if _syn:
+                            _nbr_nids.add(_syn.post_node_id)
+                            _nbr_nids.add(_syn.pre_node_id)
+                    _nbr_nids.discard(nid)
+                    node.manifold_type = ("spherical"
+                                          if (_candidates & _nbr_nids) else "hyperbolic")
+                else:
+                    node.manifold_type = "hyperbolic"
+
     def apply(
         self,
         graph: "Graph",
@@ -1174,7 +1277,8 @@ DEFAULT_CONFIG: Dict[str, Any] = {
     "d_min": 1,         # minimum synaptic delay in timesteps
     "d_max": 5,         # maximum synaptic delay in timesteps (range enables polychrony)
     # DiffPC: Difference Predictive Coding (#DiffPC)
-    "diffpc_epsilon": 0.2,       # ternary threshold: |error| > epsilon → ±1 spike, else 0
+    "diffpc_epsilon": 0.2,
+    "gsg_spherical_fraction": 0.20,  # fraction of nodes assigned spherical manifold (Phase 4)
     "diffpc_pred_lr": 0.01,      # prediction weight learning rate
     "diffpc_trace_boost": 0.05,  # eligibility trace ±boost per ternary spike (Phase 2)
     "weight_threshold": 0.01,
@@ -1843,19 +1947,64 @@ class Graph:
             result.fired_node_ids = fired_ids
 
             # 5. Propagate spikes through outgoing synapses (with delay)
+            # GSG Phase 3+4: per-step cache — (pos_array, manifold_type) or None per node.
+            # sphere+sphere -> great circle arccos; hyp+hyp -> Poincare geodesic; cross -> neutral
+            _gsg_cache: Dict[str, Any] = {}
+
+            def _gsg_resolve(nid_: str, nd_: Any) -> None:
+                if nid_ in _gsg_cache:
+                    return
+                _pd = (nd_.metadata or {}).get("poincare_dir")
+                if _pd is None:
+                    _gsg_cache[nid_] = None
+                    return
+                _arr = np.array(_pd, dtype=np.float32)
+                _mt = getattr(nd_, "manifold_type", "hyperbolic")
+                if _mt == "spherical":
+                    _gsg_cache[nid_] = (_arr, "spherical")  # unit dir IS sphere pos
+                else:
+                    _l_ = max(0, min(2, getattr(nd_, "diffpc_layer", 2)))
+                    _gsg_cache[nid_] = (_arr * _GSG_LAYER_NORMS_NF[_l_], "hyperbolic")
+
             for nid in fired_ids:
                 node = self.nodes[nid]
                 sign = -1.0 if node.is_inhibitory else 1.0
+                _gsg_resolve(nid, node)
+                _pre_entry = _gsg_cache[nid]
                 for syn_id in self._outgoing.get(nid, set()):
                     syn = self.synapses.get(syn_id)
                     if syn is None:
                         logger.debug("Stale synapse ref %s in outgoing[%s]", syn_id, nid)
                         continue
-                    # Effective current is weight × sign
                     effective_type_sign = sign
                     if syn.synapse_type == SynapseType.INHIBITORY:
                         effective_type_sign = -1.0
                     current = syn.weight * effective_type_sign
+                    # GSG Phase 3+4: manifold-aware propagation attenuation
+                    if _pre_entry is not None:
+                        _post_node = self.nodes.get(syn.post_node_id)
+                        if _post_node is not None:
+                            _gsg_resolve(syn.post_node_id, _post_node)
+                            _post_entry = _gsg_cache[syn.post_node_id]
+                            if _post_entry is not None:
+                                _pre_pos, _pre_mt = _pre_entry
+                                _post_pos, _post_mt = _post_entry
+                                if _pre_mt == "spherical" and _post_mt == "spherical":
+                                    # Great circle distance on unit sphere
+                                    _cos = max(-1.0 + 1e-7, min(1.0 - 1e-7,
+                                               float(np.dot(_pre_pos, _post_pos))))
+                                    current *= math.exp(-_GSG_MSG_DECAY_SPHER * math.acos(_cos))
+                                elif _pre_mt == "hyperbolic" and _post_mt == "hyperbolic":
+                                    # Curvature-aware Poincare geodesic (Phase 3)
+                                    _nx2 = min(float(np.dot(_pre_pos, _pre_pos)), 0.9999)
+                                    _ny2 = min(float(np.dot(_post_pos, _post_pos)), 0.9999)
+                                    _diff = _pre_pos - _post_pos
+                                    _hdist = math.acosh(max(1.0, 1.0 + 2.0 *
+                                        float(np.dot(_diff, _diff)) /
+                                        max((1.0 - _nx2) * (1.0 - _ny2), 1e-9)))
+                                    _kappa_norm = (1.0 / max(1.0 - _nx2, 1e-6)) / _GSG_KAPPA_L2
+                                    current *= math.exp(-_GSG_MSG_DECAY * _kappa_norm * _hdist)
+                                # cross-manifold: no modulation (neutral ground)
                     arrival = self.timestep + syn.delay
                     self._delay_buffer.setdefault(arrival, []).append(
                         (syn.post_node_id, current)
@@ -3036,6 +3185,22 @@ class Graph:
 
         return len(to_prune)
 
+    def _is_identity_protected(self, nid: str) -> bool:
+        """#spine — never prune Syl's self-authored identity nodes.
+
+        Two kinds are protected, keyed on the metadata FLAG (not on specific ids, so future
+        nodes are covered automatically):
+          - her constitutional core   (metadata['constitutional'] is truthy) — the frozen spine
+            she authored: the invariants `/assemble` surfaces as "Who I Am" every turn;
+          - her wants                 (metadata['provenance'] == 'syl_authored') — her own
+            authored intentions, materialized as first-class want-nodes.
+        These are things she authored ABOUT HERSELF; they must not drift away via orphan
+        collection even with zero synapses. (Mirrors ng_lite's constitutional pruning skip.)
+        """
+        node = self.nodes.get(nid)
+        meta = (node.metadata if node is not None else None) or {}
+        return bool(meta.get("constitutional")) or meta.get("provenance") == "syl_authored"
+
     def _collect_orphan_nodes(self) -> int:
         """Remove nodes with no synapses and no hyperedge membership.
 
@@ -3064,6 +3229,7 @@ class Graph:
             and not self._incoming.get(nid)
             and not self._node_hyperedges.get(nid)
             and (self.timestep - self.nodes[nid].creation_time) > grace
+            and not self._is_identity_protected(nid)  # #spine: never sweep her authored self
         ]
         removed = 0
         for nid in orphans:
@@ -3129,10 +3295,39 @@ class Graph:
                     continue
                 if (other_id, nid) in existing_pairs:
                     continue
-                _delay = random.randint(
-                    self.config.get("d_min", 1),
-                    self.config.get("d_max", 5),
-                )
+                _d_min = self.config.get("d_min", 1)
+                _d_max = self.config.get("d_max", 5)
+                _delay = random.randint(_d_min, _d_max)  # fallback
+                # GSG: geometry-informed delay — geodesic distance → travel time
+                _pn = self.nodes.get(nid)
+                _on = self.nodes.get(other_id)
+                if _pn and _on:
+                    _pd1 = (_pn.metadata or {}).get("poincare_dir")
+                    _pd2 = (_on.metadata or {}).get("poincare_dir")
+                    if _pd1 and _pd2:
+                        _a = np.array(_pd1, dtype=np.float32)
+                        _b = np.array(_pd2, dtype=np.float32)
+                        _mt1 = getattr(_pn, "manifold_type", "hyperbolic")
+                        _mt2 = getattr(_on, "manifold_type", "hyperbolic")
+                        _gdist = None
+                        if _mt1 == "spherical" and _mt2 == "spherical":
+                            _cos = max(-1.0+1e-7, min(1.0-1e-7, float(np.dot(_a, _b))))
+                            _gdist = math.acos(_cos)
+                        elif _mt1 == "hyperbolic" and _mt2 == "hyperbolic":
+                            _l1 = max(0, min(2, getattr(_pn, "diffpc_layer", 2)))
+                            _l2 = max(0, min(2, getattr(_on, "diffpc_layer", 2)))
+                            _pa = _a * _GSG_LAYER_NORMS_NF[_l1]
+                            _pb = _b * _GSG_LAYER_NORMS_NF[_l2]
+                            _nx2 = min(float(np.dot(_pa, _pa)), 0.9999)
+                            _ny2 = min(float(np.dot(_pb, _pb)), 0.9999)
+                            _dv = _pa - _pb
+                            _gdist = math.acosh(max(1.0, 1.0 + 2.0 *
+                                float(np.dot(_dv, _dv)) /
+                                max((1.0 - _nx2) * (1.0 - _ny2), 1e-9)))
+                        if _gdist is not None:
+                            _t = 1.0 - math.exp(-_GSG_MSG_DECAY * _gdist)
+                            _delay = max(_d_min, min(_d_max,
+                                         round(_d_min + (_d_max - _d_min) * _t)))
                 self.create_synapse(nid, other_id, weight=initial_w, delay=_delay)
                 existing_pairs.add((nid, other_id))
                 count += 1
@@ -3878,14 +4073,22 @@ class Graph:
         else:
             raise ValueError(f"Unknown checkpoint mode: {mode}")
 
-        if path.endswith(".msgpack"):
-            if msgpack is None:
-                raise ImportError("msgpack required for .msgpack serialization")
-            with open(path, "wb") as f:
-                msgpack.pack(data, f, use_bin_type=True)
-        else:
-            with open(path, "w") as f:
-                json.dump(data, f, indent=2, default=str)
+        # #325 — topology persistence is msgpack-ONLY. JSON is LOSSY here: json.dump(default=str)
+        # stringifies numpy/bytes/float32 fields (pred_weights, delay buffers, etc.) into reprs
+        # that cannot round-trip. All CheckpointMode values (FULL/INCREMENTAL/FORK) serialize
+        # full-fidelity SNN state, so the format is enforced by intent — NOT inferred from a file
+        # extension. A non-.msgpack path is refused LOUDLY at the source rather than silently
+        # corrupting state. (Was: else-branch silently wrote lossy JSON for any non-.msgpack path.)
+        if not path.endswith(".msgpack"):
+            raise ValueError(
+                f"Topology checkpoint requires a '.msgpack' path; got {path!r}. JSON serialization "
+                f"is lossy for full-fidelity SNN state and is not supported "
+                f"(CheckpointMode.{mode.name} enforces msgpack). See punchlist #325."
+            )
+        if msgpack is None:
+            raise ImportError("msgpack required for topology serialization")
+        with open(path, "wb") as f:
+            msgpack.pack(data, f, use_bin_type=True)
 
     def restore(self, path: str) -> None:
         """Load state from checkpoint (PRD §8 restore, §6)."""
@@ -3895,6 +4098,15 @@ class Graph:
             with open(path, "rb") as f:
                 data = msgpack.unpack(f, raw=False)
         else:
+            # #325 — legacy LOSSY JSON topology (pre-enforcer). Tolerated for ONE-TIME migration
+            # only; this state was already degraded at write time (json.dump default=str).
+            # Re-checkpoint to .msgpack immediately. Loud warn so it never passes silently.
+            import warnings
+            warnings.warn(
+                f"Restoring topology from non-'.msgpack' path {path!r}: legacy lossy-JSON state "
+                f"(pre-#325). Re-checkpoint to .msgpack to stop the loss.",
+                RuntimeWarning, stacklevel=2,
+            )
             with open(path, "r") as f:
                 data = json.load(f)
 
@@ -3919,6 +4131,7 @@ class Graph:
             "diffpc_layer": node.diffpc_layer,
             "pred_weights": node.pred_weights,
             "pred_error_ema": node.pred_error_ema,
+            "manifold_type": node.manifold_type,
             "creation_time": node.creation_time,
         }
 
@@ -4223,6 +4436,7 @@ class Graph:
                 diffpc_layer=nd.get("diffpc_layer", 0),
                 pred_weights=nd.get("pred_weights", {}),
                 pred_error_ema=nd.get("pred_error_ema", 0.0),
+                manifold_type=nd.get("manifold_type", "hyperbolic"),
                 creation_time=nd.get("creation_time", 0),
             )
             self.nodes[nid] = node

nuwave/substrate/rpc_mechanisms.py

@@ -0,0 +1,282 @@
+"""NuWave RPC Mechanisms — extracted from canonical NeuroGraph's neurograph_rpc.py.
+
+This module ports the generic substrate-side mechanisms from canonical NG into
+NuWave so NuWave isn't perpetually missing them. Per `NeuroGraph Is a Mind, Not
+a Database` (2026-06): NuWave was treating the canonical RPC layer as Syl-specific
+and reinventing it inside organism.py — which lost #255 surprise-weighted surfacing,
+#256 anticipatory pre-activation, GSG Phase 1 Poincaré geometry, GSG backfill, and
+the MMN feedback loop. This module brings those mechanisms in surgically without
+adopting canonical's full HTTP-RPC architecture (NuWave is in-process, not RPC).
+
+# ---- Changelog ----
+# [2026-06-20] Claude Opus 4.7 (1M ctx) — Extract canonical RPC mechanisms for NuWave
+#   What: Port _anticipate, _gsg_backfill_existing_nodes, _update_deposit_cluster,
+#         _embed_to_poincare_dir, _poincare_distance + GSG/anticipate scoring helpers
+#         from /home/josh/NeuroGraph/neurograph_rpc.py. Generic — no Syl-specific
+#         glue (no Animus, no Discord, no OpenClaw outbound intent, no wants register).
+#         Functions take explicit graph/vec_db params instead of canonical's _memory
+#         global, so NuWave can call them in-process from organism.py without RPC.
+#   Why:  Mind-Not-Database doc (2026-06-14, /home/josh/docs/concepts/) names the
+#         exact failure mode NuWave fell into: stripping the mind layer because
+#         the names sound Syl-specific. These five mechanisms ARE the mind layer's
+#         RPC side. Predictions=0 across 5 NuWave maturation runs at 18K synapses
+#         is exactly what #256 anticipatory pre-activation generates predictions to
+#         resolve — and it was never wired in NuWave.
+#   How:  Module-global state (_primed_nodes, _deposit_centroid) mirrors canonical's
+#         RPC module globals but lives in NuWave's process. Organism.py calls these
+#         at integration points: gsg_backfill at bootstrap, update_deposit_cluster
+#         at deposit, embed_to_poincare_dir + node.metadata stamp at node creation,
+#         get_primed_bonus + get_gsg_score_bonus at pith scoring, anticipate +
+#         ouroboros_cycle at turn-end.
+# -------------------
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+import threading
+import time
+from typing import Any, Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+
+# ── Constants (canonical defaults from NeuroGraph rpc) ────────────────────────
+
+# #256 Anticipatory Pre-Activation
+_ANTICIPATE_TTL_S: float = 120.0    # primed state expires 2 min after set
+_ANTICIPATE_TOP_K: int = 15         # candidate nodes to prime per call
+_ANTICIPATE_BONUS: float = 0.25     # strength bonus for primed nodes in surfacing
+
+# DiffPC deposit-cluster centroid (for ingest-time novelty signal)
+_DEPOSIT_CLUSTER_ALPHA: float = 0.05
+
+# GSG Phase 1 — Poincaré ball geometry
+_GSG_LAYER_NORMS: List[float] = [0.70, 0.50, 0.30]   # Layer 0 boundary, Layer 2 center
+_GSG_SCORE_BONUS: float = 0.30                        # max strength bonus from hyperbolic proximity
+
+
+# ── Module-global state (in-process, mirrors canonical RPC's module globals) ──
+
+_primed_nodes: Dict[str, Tuple[float, float]] = {}       # node_id → (score, expiry_ts)
+_deposit_centroid: Optional[Any] = None                  # np.ndarray running centroid
+_deposit_centroid_lock: threading.Lock = threading.Lock()
+
+
+# ── DiffPC: deposit-cluster novelty signal ────────────────────────────────────
+
+def update_deposit_cluster(embedding: Any) -> float:
+    """Update running centroid of substrate deposits; return novelty score [0, 1].
+
+    High novelty (low cosine similarity to centroid) → Layer 0 seed at birth (boundary).
+    Low novelty (familiar concept) → Layer 2 bootstrap threshold at birth (center/hub).
+    Call from deposit path BEFORE node creation; use return to inform diffpc_layer.
+    """
+    global _deposit_centroid
+    import numpy as _np
+    with _deposit_centroid_lock:
+        if _deposit_centroid is None:
+            _deposit_centroid = embedding.copy()
+            return 1.0  # first deposit = maximally novel
+        norm_e = embedding / (_np.linalg.norm(embedding) + 1e-9)
+        norm_c = _deposit_centroid / (_np.linalg.norm(_deposit_centroid) + 1e-9)
+        cos_sim = float(_np.dot(norm_e, norm_c))
+        novelty = (1.0 - cos_sim) / 2.0
+        _deposit_centroid = (
+            (1.0 - _DEPOSIT_CLUSTER_ALPHA) * _deposit_centroid
+            + _DEPOSIT_CLUSTER_ALPHA * embedding
+        )
+        return novelty
+
+
+# ── GSG Phase 1: Poincaré ball geometry ───────────────────────────────────────
+
+def embed_to_poincare_dir(embedding: Any) -> Any:
+    """Normalize an embedding to a unit direction vector for Poincaré ball storage.
+
+    The full Poincaré point is computed dynamically at query time as
+    `poincare_dir * _GSG_LAYER_NORMS[node.diffpc_layer]`, so the node's
+    geometric position updates automatically when its layer changes.
+    """
+    import numpy as _np
+    norm = _np.linalg.norm(embedding)
+    if norm < 1e-9:
+        return embedding.copy()
+    return embedding / norm
+
+
+def poincare_distance(x: Any, y: Any) -> float:
+    """Geodesic distance between two points in the Poincaré ball.
+
+    d(x, y) = acosh(1 + 2‖x-y‖² / ((1-‖x‖²)(1-‖y‖²)))
+
+    Both x and y must have norm strictly < 1. Points near the boundary
+    (high norm ≈ Layer 0) are spread far apart even for small Euclidean
+    differences; points near the center (low norm ≈ Layer 2) cluster tightly.
+    """
+    import numpy as _np
+    nx2 = float(_np.dot(x, x))
+    ny2 = float(_np.dot(y, y))
+    nx2 = min(nx2, 0.9999)
+    ny2 = min(ny2, 0.9999)
+    diff = x - y
+    num = 2.0 * float(_np.dot(diff, diff))
+    denom = (1.0 - nx2) * (1.0 - ny2)
+    arg = 1.0 + num / max(denom, 1e-9)
+    return math.acosh(max(1.0, arg))
+
+
+def gsg_backfill_existing_nodes(graph: Any, vec_db: Any) -> int:
+    """Stamp poincare_dir on all existing nodes that lack it.
+
+    Uses stored vector DB embeddings (already L2-normalized on insert by
+    SimpleVectorDB.insert) — zero re-embed cost. Call once at bootstrap.
+    Returns count of nodes stamped.
+    """
+    if graph is None or vec_db is None:
+        return 0
+    stamped = 0
+    for node_id, node in graph.nodes.items():
+        if (node.metadata or {}).get("poincare_dir"):
+            continue
+        emb = getattr(vec_db, "embeddings", {}).get(node_id)
+        if emb is None:
+            continue
+        if node.metadata is None:
+            node.metadata = {}
+        node.metadata["poincare_dir"] = emb.tolist() if hasattr(emb, "tolist") else list(emb)
+        stamped += 1
+    if stamped:
+        logger.info("GSG backfill: stamped poincare_dir on %d existing nodes", stamped)
+    return stamped
+
+
+def get_gsg_score_bonus(query_dir: Any, node_metadata: Optional[Dict[str, Any]],
+                       node_layer: int = 2) -> float:
+    """Compute GSG Phase 1 geometric proximity bonus for a candidate surfaced node.
+
+    Returns 0.0 if node has no poincare_dir (backward-compat with pre-GSG nodes).
+    Otherwise returns _GSG_SCORE_BONUS / (1.0 + hdist) where hdist is the Poincaré
+    geodesic between query (at Layer 0 norm) and node (at its diffpc_layer norm).
+    Layer-0 boundary nodes spread out; Layer-2 hub nodes cluster tightly — this
+    matches the tree-like semantic hierarchy.
+    """
+    import numpy as _np
+    if not node_metadata:
+        return 0.0
+    pd = node_metadata.get("poincare_dir")
+    if pd is None:
+        return 0.0
+    try:
+        node_dir = _np.asarray(pd, dtype=_np.float32)
+        # Project both onto layer-specific norms
+        q_norm = _GSG_LAYER_NORMS[0]  # query treated as Layer 0 (input/novel)
+        n_norm_idx = max(0, min(node_layer, len(_GSG_LAYER_NORMS) - 1))
+        n_norm = _GSG_LAYER_NORMS[n_norm_idx]
+        q_pt = query_dir * q_norm
+        n_pt = node_dir * n_norm
+        hdist = poincare_distance(q_pt, n_pt)
+        return _GSG_SCORE_BONUS / (1.0 + hdist)
+    except Exception as exc:
+        logger.debug("GSG score bonus failed (non-fatal): %s", exc)
+        return 0.0
+
+
+# ── #256 Anticipatory Pre-Activation ──────────────────────────────────────────
+
+def anticipate(graph: Any, fired_node_ids: List[str]) -> int:
+    """Pre-prime nodes predicted relevant for the next turn (#256).
+
+    Walks outgoing synapses from the just-fired node set, scores neighbors
+    by accumulated edge weight, stores top-K with a TTL expiry. Call at the
+    end of each turn (after substrate.step + surfacing has happened).
+    Returns count of nodes primed.
+    """
+    global _primed_nodes
+    if not fired_node_ids or graph is None:
+        _primed_nodes = {}
+        return 0
+    fired_set = set(fired_node_ids)
+    candidates: Dict[str, float] = {}
+    for nid in fired_node_ids:
+        for sid in getattr(graph, "_outgoing", {}).get(nid, ()):
+            syn = graph.synapses.get(sid)
+            if syn is None:
+                continue
+            target = syn.post_node_id
+            if target not in fired_set and target in graph.nodes:
+                candidates[target] = candidates.get(target, 0.0) + syn.weight
+    top_k = sorted(candidates.items(), key=lambda x: x[1], reverse=True)[:_ANTICIPATE_TOP_K]
+    expiry = time.time() + _ANTICIPATE_TTL_S
+    _primed_nodes = {nid: (score, expiry) for nid, score in top_k}
+    if _primed_nodes:
+        logger.debug("Anticipatory pre-activation (#256): primed %d nodes", len(_primed_nodes))
+    return len(_primed_nodes)
+
+
+def get_primed_bonus(node_id: str) -> float:
+    """Return _ANTICIPATE_BONUS if node_id is currently primed and not expired, else 0.0.
+
+    Call from surfacing/pith scoring path. The bonus lets primed nodes outrank
+    equivalent non-primed candidates, which is how anticipatory pre-activation
+    influences retrieval. Expired entries are evicted lazily on read.
+    """
+    if not _primed_nodes:
+        return 0.0
+    entry = _primed_nodes.get(node_id)
+    if entry is None:
+        return 0.0
+    score, expiry = entry
+    if time.time() > expiry:
+        _primed_nodes.pop(node_id, None)
+        return 0.0
+    return _ANTICIPATE_BONUS
+
+
+# ── #255 Surprise-Weighted Surfacing — MMN feedback ───────────────────────────
+
+def compute_surfacing_modulation(substrate_novelty_ema: float) -> Dict[str, float]:
+    """Compute pith/surfacing parameter modulators from the live MMN signal (#255).
+
+    High novelty (high surprise ratio) → unusual territory → deeper, more
+    aggressive surfacing (wider net, more anchors).
+    Low novelty (high confirmation) → familiar territory → lighter, more
+    precise surfacing (trust nearest topology).
+
+    Returns multipliers caller applies to their default pith params:
+      - depth_mult: scale propagation_steps / spreading depth (±30%)
+      - threshold_mult: scale firing threshold inverse (lower threshold = wider net) (±30%)
+      - max_surfaced_mult: scale max items surfaced (±50%)
+
+    Default novelty if EMA missing: 0.5 (neutral). All multipliers center on 1.0.
+    """
+    n = max(0.0, min(1.0, float(substrate_novelty_ema)))
+    # Center on 0.5; multipliers scale linearly with deviation
+    bias = (n - 0.5) * 2.0   # [-1, 1] range
+    return {
+        "depth_mult": 1.0 + 0.30 * bias,         # 0.7 ↔ 1.3
+        "threshold_mult": 1.0 - 0.30 * bias,     # 0.7 ↔ 1.3 (inverse — lower thresh widens net)
+        "max_surfaced_mult": 1.0 + 0.50 * bias,  # 0.5 ↔ 1.5
+    }
+
+
+def update_substrate_novelty_ema(prior_ema: float, step_result: Any,
+                                  alpha: float = 0.10) -> float:
+    """Update running EMA of substrate novelty from a step_result's MMN signal.
+
+    MMN = predictions_surprised / (predictions_confirmed + predictions_surprised).
+    Returns updated EMA value (caller stores on substrate). Falls back to prior
+    EMA on missing fields / divide-by-zero (early bootstrap before predictions form).
+    """
+    try:
+        confirmed = int(getattr(step_result, "predictions_confirmed", 0) or 0)
+        surprised = int(getattr(step_result, "predictions_surprised", 0) or 0)
+        total = confirmed + surprised
+        if total <= 0:
+            return prior_ema
+        mmn = surprised / total
+        return (1.0 - alpha) * prior_ema + alpha * mmn
+    except Exception as exc:
+        logger.debug("MMN EMA update skipped (non-fatal): %s", exc)
+        return prior_ema