Initial commit

.gitignore

@@ -0,0 +1,7 @@
+rust_lenia/target/
+__pycache__/
+*.pyc
+*.pyo
+*.so
+*.whl
+tests/

README.md

@@ -0,0 +1,31 @@
+---
+title: NuWave
+emoji: 🧠
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+sdk_version: "5.29.0"
+app_file: app.py
+pinned: false
+license: agpl-3.0
+---
+
+# NuWave — Your Model Gets Smarter Over Time
+
+CPU-native AI through compound context optimization.
+
+Powered by **BitNet b1.58-2B-4T** — Microsoft's ternary weight model (1.58 bits per weight, addition-only inference, 0.4GB memory). No GPU needed.
+
+## How It Works
+
+- **KISS** (Keep Input Simple, Substrate) — filters redundant context. System prompt skipped when unchanged. Old conversation history compressed to summaries.
+- **Pith** (The Living Context Lens) — manages the context window as a cache hierarchy. Strips clutter, evicts cold entries, promotes what's relevant.
+- **BitNet** — ternary weights {-1, 0, +1} replace floating-point multiplication with addition. CPU-native by design.
+
+Together they compound: cleaner input → less processing → better context → sharper reasoning → both improve.
+
+## Demo
+
+Two tabs:
+1. **Live Chat** — talk to the model, see KISS/Pith metrics in real time (tokens saved, system skipped, clutter stripped)
+2. **A/B Benchmark** — same conversation through baseline vs NuWave. Watch tokens drop and time decrease as KISS learns what's redundant.

app.py

@@ -0,0 +1,484 @@
+"""
+NuWave — HuggingFace Spaces Demo
+
+The organism. NeuroGraph substrate + KISS bucket + Pith bucket +
+Splat-Lenia + BitNet model. On CPU. Gets smarter over time.
+
+# ---- Changelog ----
+# [2026-04-06] Claude Code (Opus 4.6) — Full NeuroGraph organism integration
+# [2026-03-31] Claude Code (Opus 4.6) — Switch to BitNet 2B for CPU-native inference
+# [2026-03-29] Claude Code (Opus 4.6) — ZeroGPU compatible, model at startup
+# [2026-03-28] Claude Code (Opus 4.6) — Initial Gradio demo
+# -------------------
+"""
+
+# Install ng_tract wheel before any imports that need it
+import subprocess, sys, os
+_whl = os.path.join(os.path.dirname(__file__), "ng_tract-0.1.0-cp312-abi3-manylinux_2_34_x86_64.whl")
+if os.path.exists(_whl):
+    try:
+        import ng_tract
+    except ImportError:
+        subprocess.check_call([sys.executable, "-m", "pip", "install", _whl, "--quiet"])
+
+import gradio as gr
+import json
+import logging
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+try:
+    import spaces
+except ImportError:
+    class _FakeSpaces:
+        @staticmethod
+        def GPU(fn=None, **kwargs):
+            return fn if fn else lambda f: f
+    spaces = _FakeSpaces()
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("nuwave")
+
+# ── Load Model at Startup (guard against Gradio double-import) ────
+
+MODEL_NAME = "microsoft/bitnet-b1.58-2B-4T-bf16"
+HF_TOKEN = os.environ.get("HF_TOKEN", None)
+
+logger.info("Loading model: %s (token: %s)", MODEL_NAME, "present" if HF_TOKEN else "MISSING")
+tokenizer = AutoTokenizer.from_pretrained(MODEL_NAME, token=HF_TOKEN)
+if tokenizer.pad_token is None:
+    tokenizer.pad_token = tokenizer.eos_token
+
+model = AutoModelForCausalLM.from_pretrained(
+    MODEL_NAME,
+    torch_dtype=torch.bfloat16,
+    device_map="cpu",
+    low_cpu_mem_usage=True,
+    token=HF_TOKEN,
+)
+model.eval()
+logger.info("Model loaded: %d params", sum(p.numel() for p in model.parameters()))
+
+# ── NuWave Components ─────────────────────────────────────────────
+
+from nuwave.organism import NuWaveOrganism
+from nuwave.kiss import KISSFilter, KISSConfig
+from nuwave.pith import PithPipeline, PithConfig
+from nuwave.splat_engine import decompose_layer, SplatConfig, GaussianSplats
+from nuwave.lenia_splat import LeniaSplatEngine, LeniaSplatConfig
+
+# The organism — substrate + KISS bucket + Pith bucket
+# Use /data/ for persistence if available (HF persistent storage), else /tmp/
+_persist_dir = "/data/nuwave_substrate" if os.path.isdir("/data") else "/tmp/nuwave_substrate"
+organism = NuWaveOrganism(state_path=_persist_dir)
+
+# String-level KISS still runs alongside for comparison
+kiss_nw = KISSFilter()
+pith_nw = PithPipeline()
+
+messages_nw = []
+messages_bl = []
+system_prompt = "You are a helpful assistant. Be concise and clear."
+
+# ── Splat-Lenia Setup ────────────────────────────────────────────
+# Decompose a few attention layers to splats at startup.
+# Lenia evolves them between turns. The compression is alive.
+
+splat_config = SplatConfig(
+    splat_ratio=0.02,       # 50x compression — aggressive but fast to fit
+    max_splats=256,         # small enough for CPU-basic startup
+    init_sigma=2.0,
+    fit_iterations=50,      # fewer iterations — speed over precision at startup
+    fit_lr=0.02,
+)
+
+lenia_config = LeniaSplatConfig(
+    growth_mu=0.15,
+    growth_sigma=0.015,
+    growth_scale=0.0003,    # small dt — proven stable
+    interaction_radius=5.0,
+    activation_coupling=2.0,
+    conserve_mass=True,
+)
+
+lenia_engine = LeniaSplatEngine(lenia_config)
+splat_layers = {}
+splat_metrics_history = []
+
+# Splat decomposition deferred to first use — avoids memory spike during startup
+# Splat state persists to disk so Lenia evolution survives restarts
+_splats_initialized = False
+_splat_save_path = os.path.join(_persist_dir, "splat_state.pt")
+
+def _init_splats_if_needed():
+    """Load persisted splats or decompose from scratch on first use."""
+    global _splats_initialized
+    if _splats_initialized:
+        return
+    _splats_initialized = True
+
+    import gc
+    gc.collect()
+
+    # Try to restore persisted splat state first
+    if os.path.exists(_splat_save_path):
+        try:
+            saved = torch.load(_splat_save_path, weights_only=False)
+            for name, sd in saved.get('layers', {}).items():
+                splats = GaussianSplats.from_state_dict(sd)
+                splat_layers[name] = splats
+                lenia_engine.register_layer(name, splats)
+            lenia_step_count = saved.get('lenia_steps', 0)
+            logger.info(
+                f"Splats restored: {len(splat_layers)} layers, "
+                f"{sum(s.n_splats for s in splat_layers.values())} splats, "
+                f"{lenia_step_count} Lenia steps evolved"
+            )
+            return
+        except Exception as exc:
+            logger.warning(f"Splat restore failed (redecomposing): {exc}")
+
+    # Fresh decomposition
+    logger.info("Decomposing attention layers to Gaussian splats (first use)...")
+    try:
+        for name, param in model.named_parameters():
+            if any(k in name for k in ['layers.0.self_attn.k_proj', 'layers.0.self_attn.v_proj']):
+                if param.dim() >= 2:
+                    w = param.data.float()
+                    if w.dim() > 2:
+                        w = w.reshape(w.shape[0], -1)
+                    logger.info(f"  Decomposing {name} ({w.shape[0]}x{w.shape[1]})...")
+                    splats, metrics = decompose_layer(w, splat_config)
+                    splat_layers[name] = splats
+                    lenia_engine.register_layer(name, splats)
+                    logger.info(f"    {metrics['n_splats']} splats, {metrics['compression_ratio']:.1f}x, MSE={metrics['final_mse']:.4f}")
+                    del w
+                    gc.collect()
+
+        logger.info(f"Splat decomposition complete: {len(splat_layers)} layers")
+    except Exception as exc:
+        logger.warning(f"Splat decomposition failed (non-fatal): {exc}")
+
+
+def _save_splat_state():
+    """Persist evolved splat parameters to disk."""
+    if not splat_layers:
+        return
+    try:
+        os.makedirs(os.path.dirname(_splat_save_path), exist_ok=True)
+        state = {
+            'layers': {name: splats.state_dict() for name, splats in splat_layers.items()},
+            'lenia_steps': lenia_engine.state.step_count,
+        }
+        torch.save(state, _splat_save_path)
+    except Exception as exc:
+        logger.debug(f"Splat save failed: {exc}")
+
+
+# ── Inference ─────────────────────────────────────────────────────
+
+def do_generate(prompt_text: str, max_new_tokens: int = 256) -> tuple:
+    """Run inference on CPU with Lenia step after generation."""
+    _init_splats_if_needed()
+    import time
+    t0 = time.time()
+
+    inputs = tokenizer(prompt_text, return_tensors="pt", truncation=True, max_length=4096)
+    input_ids = inputs["input_ids"]
+    in_count = input_ids.shape[1]
+
+    with torch.no_grad():
+        outputs = model.generate(
+            input_ids,
+            max_new_tokens=max_new_tokens,
+            do_sample=False,
+            pad_token_id=tokenizer.pad_token_id,
+        )
+
+    new_tokens = outputs[0][input_ids.shape[1]:]
+    response = tokenizer.decode(new_tokens, skip_special_tokens=True)
+
+    # Run Lenia step on splats after inference
+    lenia_result = {}
+    if splat_layers:
+        try:
+            lenia_result = lenia_engine.step()
+            splat_metrics_history.append(lenia_result)
+            _save_splat_state()
+        except Exception as exc:
+            logger.warning(f"Lenia step failed: {exc}")
+
+    elapsed = time.time() - t0
+    out_count = len(new_tokens)
+    tok_per_sec = out_count / elapsed if elapsed > 0 else 0
+
+    return response, in_count, out_count, round(elapsed, 2), round(tok_per_sec, 1), lenia_result
+
+
+# ── Chat Handler ──────────────────────────────────────────────────
+
+def on_send(message, history):
+    if not message:
+        return "", history, ""
+
+    global messages_nw
+    messages_nw.append({"role": "user", "content": message})
+
+    # ── 1. Deposit raw experience into substrate (Law 7) ──
+    organism.deposit_experience(message)
+
+    # ── 2. Substrate processes ──
+    step_result = organism.step()
+
+    # ── 3. KISS bucket — extract what changed from the River ──
+    kiss_extract = organism.kiss_extract(step_result)
+
+    # Also run string-level KISS for comparison metrics
+    kiss_string_result = kiss_nw.filter_context(messages_nw, system_prompt)
+    sys_ctx = kiss_string_result.get("system_context", system_prompt)
+
+    # ── 4. Pith bucket — extract relevant context from the River ──
+    pith_context = organism.pith_extract(message, max_context=5)
+
+    # Pith context REPLACES old message history, not adds to it.
+    # The substrate carries what the older messages contained — the model
+    # doesn't need both. Recent messages pass verbatim (the model needs
+    # immediate context). Older messages are replaced by substrate context.
+    if pith_context:
+        substrate_ctx = "\n".join(pith_context)
+        if sys_ctx:
+            sys_ctx = substrate_ctx + "\n\n" + sys_ctx
+        else:
+            sys_ctx = substrate_ctx
+
+    # Build prompt — Pith context replaces old history
+    # Only send recent messages. The substrate carries the rest.
+    recent_window = 6  # 3 turns of user+assistant
+    if len(messages_nw) > recent_window and pith_context:
+        # Substrate has the older context — trim messages to recent only
+        recent_msgs = messages_nw[-recent_window:]
+    else:
+        recent_msgs = messages_nw
+
+    prompt_msgs = []
+    if sys_ctx:
+        prompt_msgs.append({"role": "system", "content": sys_ctx})
+    prompt_msgs.extend(recent_msgs)
+
+    prompt = tokenizer.apply_chat_template(
+        prompt_msgs, tokenize=False, add_generation_prompt=True,
+    )
+
+    # ── 5. Model generates ──
+    response, in_tok, out_tok, elapsed, tok_s, lenia_result = do_generate(prompt)
+
+    messages_nw.append({"role": "assistant", "content": response})
+
+    # ── 6. Outcome feeds back into substrate (Law 7) ──
+    organism.record_outcome(message, response, success=True)
+
+    # Stats — both substrate and string-level
+    kiss_stats = kiss_nw.stats.to_dict()
+    org_stats = organism.get_stats()
+
+    lenia_info = ""
+    if lenia_result:
+        lenia_info = (
+            f" | Lenia step {lenia_result.get('step', 0)}: "
+            f"Δα={lenia_result.get('total_alpha_delta', 0):.6f} "
+            f"Δμ={lenia_result.get('total_position_delta', 0):.6f} "
+            f"({lenia_result.get('time_ms', 0):.0f}ms)"
+        )
+
+    substrate_info = (
+        f" | Substrate: {org_stats.get('nodes', 0)} nodes, "
+        f"{org_stats.get('synapses', 0)} syn, "
+        f"{org_stats.get('fired_nodes', 0)} fired"
+    )
+
+    kiss_bucket_info = (
+        f" | KISS bucket: {kiss_extract.get('action', '?')} "
+        f"({kiss_extract.get('reason', '')})"
+    )
+    if kiss_extract.get('surprise_ratio', 0) > 0:
+        kiss_bucket_info += f" surprise={kiss_extract['surprise_ratio']}"
+
+    stats_text = (
+        f"**Turn {len(messages_nw)//2}** | "
+        f"{out_tok} tokens in {elapsed}s ({tok_s} tok/s) | "
+        f"Input: {in_tok} tokens | "
+        f"String KISS: {kiss_stats.get('tokens_saved', 0)} saved ({kiss_stats.get('efficiency', 0):.1%})"
+        f"{substrate_info}"
+        f"{kiss_bucket_info}"
+        f" | Pith river: {len(pith_context)} contexts"
+        f"{lenia_info}"
+    )
+
+    history = history + [
+        {"role": "user", "content": message},
+        {"role": "assistant", "content": response},
+    ]
+
+    return "", history, stats_text
+
+
+def on_reset():
+    global messages_nw, kiss_nw, pith_nw
+    messages_nw = []
+    kiss_nw = KISSFilter()
+    pith_nw = PithPipeline()
+    return [], "Chat reset."
+
+
+# ── Benchmark ─────────────────────────────────────────────────────
+
+SAMPLE_CONVERSATIONS = [
+    "What is machine learning?",
+    "How does it differ from traditional programming?",
+    "Can you give me a simple example of supervised learning?",
+    "What about unsupervised learning?",
+    "How would I choose between them for a new project?",
+    "What are neural networks?",
+    "How deep is 'deep learning'?",
+    "What's the relationship between AI, ML, and deep learning?",
+    "What are transformers in the context of AI?",
+    "How does attention work in a transformer?",
+    "Why are transformers better than RNNs for many tasks?",
+    "What is transfer learning and why does it matter?",
+    "How do I fine-tune a pre-trained model?",
+    "What are the ethical considerations in AI?",
+    "Where do you see AI heading in the next 5 years?",
+]
+
+
+def on_benchmark(num_turns):
+    turns = min(int(num_turns), len(SAMPLE_CONVERSATIONS))
+    conversation = SAMPLE_CONVERSATIONS[:turns]
+
+    # Fresh state for clean test
+    bl_msgs = []
+    nw_kiss = KISSFilter()
+    nw_pith = PithPipeline()
+    nw_msgs = []
+
+    results = []
+
+    for i, prompt_text in enumerate(conversation):
+        # Baseline — no KISS/Pith
+        bl_msgs.append({"role": "user", "content": prompt_text})
+        prompt_bl = tokenizer.apply_chat_template(
+            [{"role": "system", "content": system_prompt}] + bl_msgs,
+            tokenize=False, add_generation_prompt=True,
+        )
+        resp_bl, in_bl, out_bl, time_bl, tps_bl, _ = do_generate(prompt_bl, max_new_tokens=128)
+        bl_msgs.append({"role": "assistant", "content": resp_bl})
+
+        # NuWave — KISS + Pith
+        nw_msgs.append({"role": "user", "content": prompt_text})
+        kiss_r = nw_kiss.filter_context(nw_msgs, system_prompt)
+        sys_ctx = kiss_r.get("system_context", system_prompt)
+        if sys_ctx:
+            chunks = [c.strip() for c in sys_ctx.split("\n\n") if c.strip()]
+            if chunks:
+                optimized = nw_pith.extract(chunks, query=prompt_text)
+                sys_ctx = "\n\n".join(optimized)
+        prompt_nw = tokenizer.apply_chat_template(
+            [{"role": "system", "content": sys_ctx}] + nw_msgs if sys_ctx else nw_msgs,
+            tokenize=False, add_generation_prompt=True,
+        )
+        resp_nw, in_nw, out_nw, time_nw, tps_nw, lenia_r = do_generate(prompt_nw, max_new_tokens=128)
+        nw_msgs.append({"role": "assistant", "content": resp_nw})
+
+        ks = nw_kiss.stats.to_dict()
+        ps = nw_pith.stats.to_dict()
+
+        results.append({
+            "turn": i + 1,
+            "baseline": {"tokens": in_bl, "time": time_bl, "tok_s": tps_bl},
+            "nuwave": {"tokens": in_nw, "time": time_nw, "tok_s": tps_nw},
+            "tokens_saved": max(0, in_bl - in_nw),
+            "time_saved": round(max(0, time_bl - time_nw), 2),
+            "kiss_efficiency": ks.get("efficiency", 0),
+            "pith_l1_size": ps.get("l1_current_size", 0),
+            "pith_clutter": ps.get("clutter_stripped", 0),
+        })
+
+    # Summary
+    total_time_bl = sum(r["baseline"]["time"] for r in results)
+    total_time_nw = sum(r["nuwave"]["time"] for r in results)
+    total_tok_bl = sum(r["baseline"]["tokens"] for r in results)
+    total_tok_nw = sum(r["nuwave"]["tokens"] for r in results)
+
+    summary = {
+        "model": MODEL_NAME,
+        "turns": turns,
+        "baseline_total_tokens": total_tok_bl,
+        "nuwave_total_tokens": total_tok_nw,
+        "tokens_saved": total_tok_bl - total_tok_nw,
+        "baseline_total_time": round(total_time_bl, 2),
+        "nuwave_total_time": round(total_time_nw, 2),
+        "time_saved": round(total_time_bl - total_time_nw, 2),
+        "final_kiss_efficiency": results[-1]["kiss_efficiency"] if results else 0,
+        "final_pith_l1": results[-1]["pith_l1_size"] if results else 0,
+    }
+
+    return json.dumps(summary, indent=2), json.dumps(results, indent=2)
+
+
+# ── Gradio App ────────────────────────────────────────────────────
+
+with gr.Blocks(
+    title="NuWave — Your Model Gets Smarter Over Time",
+    theme=gr.themes.Soft(),
+) as demo:
+    gr.Markdown(
+        f"""
+        # NuWave — Your Model Gets Smarter Over Time
+
+        **Context optimization through compound substrate dynamics.**
+
+        - **KISS** filters redundant context — system prompt skipped when unchanged, old history compressed to summary
+        - **Pith** manages context as a cache hierarchy — clutter stripped, cold entries evicted, relevant context promoted
+        - **Splat-Lenia** — weight layers decomposed to Gaussian splats, Lenia dynamics evolve them between turns
+
+        Model: `{MODEL_NAME}` | Inference: CPU | Splat layers: {len(splat_layers)} | Total splats: {sum(s.n_splats for s in splat_layers.values()) if splat_layers else 0}
+        """
+    )
+
+    with gr.Tabs():
+        with gr.Tab("Live Chat"):
+            chatbot = gr.Chatbot(height=400, type="messages")
+            stats_display = gr.Markdown("*Send a message to see NuWave metrics*")
+
+            with gr.Row():
+                msg = gr.Textbox(placeholder="Type a message...", show_label=False, scale=4)
+                send_btn = gr.Button("Send", scale=1)
+                reset_btn = gr.Button("Reset", scale=1)
+
+            send_btn.click(on_send, [msg, chatbot], [msg, chatbot, stats_display])
+            msg.submit(on_send, [msg, chatbot], [msg, chatbot, stats_display])
+            reset_btn.click(on_reset, outputs=[chatbot, stats_display])
+
+        with gr.Tab("A/B Benchmark"):
+            gr.Markdown(
+                """
+                ### Baseline vs NuWave
+
+                Same conversation, same model, same CPU. Baseline sends full context every turn.
+                NuWave compresses history and skips redundant system context.
+
+                Watch: tokens decrease, time decreases, KISS efficiency climbs.
+                """
+            )
+
+            with gr.Row():
+                num_turns = gr.Slider(minimum=3, maximum=15, value=8, step=1, label="Turns")
+                run_btn = gr.Button("Run Benchmark", variant="primary")
+
+            summary_output = gr.Code(label="Summary", language="json")
+            curve_output = gr.Code(label="Per-Turn Data", language="json")
+
+            run_btn.click(on_benchmark, [num_turns], [summary_output, curve_output])
+
+if __name__ == "__main__":
+    demo.launch(server_name="0.0.0.0", ssr_mode=False)

baseline_results.json

@@ -0,0 +1,44 @@
+{
+  "test": "NuWave Phase 1 Baseline — KISS only (crude string compression)",
+  "model": "microsoft/bitnet-b1.58-2B-4T-bf16",
+  "hardware": "HuggingFace CPU-basic (2 vCPU, 16GB RAM)",
+  "date": "2026-04-06",
+  "kiss_version": "string hash + history summarization (operations 1+5 only)",
+  "pith_version": "minimal (clutter strip on system context chunks only)",
+  "splat_lenia": "2 attention layers, 256 splats each, Lenia stepping each turn",
+  "neuro_graph": "NOT CONNECTED — this is the before picture",
+  "turns": [
+    {"turn": 1, "input_tokens": 43, "output_tokens": 42, "time_s": 90.91, "tok_s": 0.5, "tokens_saved": 0, "efficiency": 0.0, "kiss_sys_skipped": 0, "pith_l1": 1, "clutter_stripped": 0},
+    {"turn": 2, "input_tokens": 121, "output_tokens": 88, "time_s": 127.21, "tok_s": 0.7, "tokens_saved": 0, "efficiency": 0.0, "kiss_sys_skipped": 0, "pith_l1": 1, "clutter_stripped": 1},
+    {"turn": 4, "input_tokens": 534, "output_tokens": 123, "time_s": 332.85, "tok_s": 0.4, "tokens_saved": 13, "efficiency": 1.9, "kiss_sys_skipped": 1, "pith_l1": 2, "clutter_stripped": 2},
+    {"turn": 5, "input_tokens": 732, "output_tokens": 104, "time_s": 287.12, "tok_s": 0.4, "tokens_saved": 58, "efficiency": 4.9, "kiss_sys_skipped": 2, "pith_l1": 3, "clutter_stripped": 2},
+    {"turn": 6, "input_tokens": 948, "output_tokens": 149, "time_s": 404.98, "tok_s": 0.4, "tokens_saved": 172, "efficiency": 9.6, "kiss_sys_skipped": 3, "pith_l1": 4, "clutter_stripped": 2},
+    {"turn": 7, "input_tokens": 1118, "output_tokens": 147, "time_s": 417.50, "tok_s": 0.4, "tokens_saved": 490, "efficiency": 19.3, "kiss_sys_skipped": 4, "pith_l1": 4, "clutter_stripped": 3},
+    {"turn": 8, "input_tokens": 1426, "output_tokens": 256, "time_s": 468.51, "tok_s": 0.5, "tokens_saved": 893, "efficiency": 26.1, "kiss_sys_skipped": 5, "pith_l1": 5, "clutter_stripped": 3},
+    {"turn": 9, "input_tokens": 1727, "output_tokens": 240, "time_s": 483.56, "tok_s": 0.5, "tokens_saved": 1368, "efficiency": 30.1, "kiss_sys_skipped": 6, "pith_l1": 5, "clutter_stripped": 4},
+    {"turn": 10, "input_tokens": 2222, "output_tokens": 93, "time_s": 301.35, "tok_s": 0.3, "tokens_saved": 1953, "efficiency": 33.1, "kiss_sys_skipped": 7, "pith_l1": 6, "clutter_stripped": 4},
+    {"turn": 11, "input_tokens": 2364, "output_tokens": 256, "time_s": 554.52, "tok_s": 0.5, "tokens_saved": 2648, "efficiency": 35.9, "kiss_sys_skipped": 8, "pith_l1": 6, "clutter_stripped": 5},
+    {"turn": 12, "input_tokens": 2918, "output_tokens": 256, "time_s": 608.90, "tok_s": 0.4, "tokens_saved": 3552, "efficiency": 39.2, "kiss_sys_skipped": 9, "pith_l1": 7, "clutter_stripped": 5},
+    {"turn": 13, "input_tokens": 3198, "output_tokens": 256, "time_s": 664.85, "tok_s": 0.4, "tokens_saved": 4682, "efficiency": 42.7, "kiss_sys_skipped": 10, "pith_l1": 7, "clutter_stripped": 6},
+    {"turn": 14, "input_tokens": 3477, "output_tokens": 256, "time_s": 748.87, "tok_s": 0.3, "tokens_saved": 5897, "efficiency": 45.0, "kiss_sys_skipped": 11, "pith_l1": 7, "clutter_stripped": 7},
+    {"turn": 15, "input_tokens": 4096, "output_tokens": 35, "time_s": 375.36, "tok_s": 0.1, "tokens_saved": 7306, "efficiency": 47.2, "kiss_sys_skipped": 12, "pith_l1": 8, "clutter_stripped": 7}
+  ],
+  "summary": {
+    "peak_efficiency": 47.2,
+    "total_tokens_saved": 7306,
+    "ceiling_hit": "BitNet 4096 context window at turn 15",
+    "savings_outpaced_growth_at": "turn 11",
+    "lenia_step_time_avg_ms": 9,
+    "lenia_delta_alpha": 0.000599,
+    "lenia_delta_mu": 0.000007
+  },
+  "notes": [
+    "KISS using only operations 1 (delta gate) and 5 (temporal compress)",
+    "Operations 2, 3, 4, 6 not implemented — room for significant improvement",
+    "Pith doing minimal clutter strip only — not managing conversation as cache hierarchy",
+    "No NeuroGraph substrate — KISS computing own metrics instead of reading topology",
+    "No binary tract format — string-level operations only",
+    "Splat-Lenia running but not yet integrated into inference path",
+    "THIS IS THE BEFORE PICTURE — everything improves from here"
+  ]
+}

nuwave/__init__.py

@@ -0,0 +1,16 @@
+"""
+NuWave — CPU-First AI Through Compound Substrate Optimization
+
+Ship a model. Let it run. It gets more efficient over time.
+
+Phase 1: KISS + Pith on the context window (frozen model)
+Phase 2: Lenia dynamics on unfrozen weights (compound optimization)
+
+Usage:
+    from nuwave import NuWave
+    nw = NuWave(model_name="microsoft/Phi-4-mini")
+    response = nw.chat("Hello, how are you?")
+    print(nw.stats())  # KISS skip rate, Pith cache hits, compound curve
+"""
+
+__version__ = "0.1.0"

nuwave/adapters/__init__.py

@@ -0,0 +1,2 @@
+"""Model adapters for wrapping HuggingFace models with NuWave."""
+from nuwave.adapters.huggingface import HuggingFaceAdapter

nuwave/adapters/huggingface.py

@@ -0,0 +1,251 @@
+"""
+HuggingFace Adapter — Wrap any HF model with NuWave
+
+KISS manages what goes into the context (CPU).
+Pith manages what the model actually sees (CPU).
+The model does the thinking (GPU via ZeroGPU).
+NuWave makes the thinking efficient.
+
+ZeroGPU compatible: GPU allocated only during model.generate().
+KISS and Pith run on CPU always.
+
+# ---- Changelog ----
+# [2026-03-29] Claude Code (Opus 4.6) — ZeroGPU compatible
+#   What: Separated CPU (KISS/Pith) from GPU (inference) paths
+#   Why:  HF ZeroGPU allocates GPU only during @spaces.GPU calls.
+#         KISS/Pith are CPU. Only model inference needs GPU.
+#   How:  _generate() is the GPU-only path. chat() orchestrates
+#         CPU context optimization around the GPU call.
+# [2026-03-28] Claude Code (Opus 4.6) — Initial implementation
+# -------------------
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger("nuwave.adapter.hf")
+
+# Global model + tokenizer — loaded once, shared across calls.
+# ZeroGPU moves them to GPU only during @spaces.GPU decorated calls.
+_model = None
+_tokenizer = None
+
+
+def _ensure_model(model_name: str):
+    """Load model and tokenizer once globally."""
+    global _model, _tokenizer
+    if _model is not None:
+        return
+
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+    import torch
+
+    logger.info("Loading %s...", model_name)
+
+    _tokenizer = AutoTokenizer.from_pretrained(model_name)
+    if _tokenizer.pad_token is None:
+        _tokenizer.pad_token = _tokenizer.eos_token
+
+    _model = AutoModelForCausalLM.from_pretrained(
+        model_name,
+        dtype=torch.float16 if torch.cuda.is_available() else torch.float32,
+        device_map="auto",
+    )
+    _model.eval()
+
+    logger.info(
+        "Loaded %s (%d params, device=%s)",
+        model_name,
+        sum(p.numel() for p in _model.parameters()),
+        next(_model.parameters()).device,
+    )
+
+
+def generate(
+    prompt: str,
+    max_new_tokens: int = 512,
+    temperature: float = 0.7,
+    do_sample: bool = True,
+) -> tuple:
+    """GPU-only inference. Called inside @spaces.GPU context.
+
+    Args:
+        prompt: Fully formatted prompt string (already KISS/Pith optimized)
+        max_new_tokens: Max tokens to generate
+        temperature: Sampling temperature
+        do_sample: Whether to sample
+
+    Returns:
+        (response_text, input_token_count, output_token_count)
+    """
+    import torch
+
+    inputs = _tokenizer(prompt, return_tensors="pt", truncation=True)
+    input_ids = inputs["input_ids"].to(_model.device)
+    input_count = input_ids.shape[1]
+
+    with torch.no_grad():
+        outputs = _model.generate(
+            input_ids,
+            max_new_tokens=max_new_tokens,
+            temperature=temperature,
+            do_sample=do_sample,
+            pad_token_id=_tokenizer.pad_token_id,
+        )
+
+    new_tokens = outputs[0][input_ids.shape[1]:]
+    response = _tokenizer.decode(new_tokens, skip_special_tokens=True)
+    output_count = len(new_tokens)
+
+    return response, input_count, output_count
+
+
+class HuggingFaceAdapter:
+    """Wraps a HuggingFace model with NuWave context optimization.
+
+    KISS and Pith run on CPU. Model inference uses ZeroGPU.
+    The generate() function is called separately so it can be
+    wrapped with @spaces.GPU in the Gradio app.
+
+    Usage:
+        adapter = HuggingFaceAdapter("microsoft/Phi-4-mini-instruct")
+        prompt = adapter.prepare("Hello!")  # CPU: KISS + Pith
+        response = generate(prompt)         # GPU: model inference
+        adapter.record(response)            # CPU: update state
+    """
+
+    def __init__(
+        self,
+        model_name: str,
+        nuwave_enabled: bool = True,
+        kiss_config=None,
+        pith_config=None,
+        system_prompt: str = "",
+    ):
+        self.model_name = model_name
+        self.nuwave_enabled = nuwave_enabled
+        self.system_prompt = system_prompt
+
+        self._kiss = None
+        self._pith = None
+        if nuwave_enabled:
+            from nuwave.kiss import KISSFilter, KISSConfig
+            from nuwave.pith import PithPipeline, PithConfig
+            self._kiss = KISSFilter(kiss_config or KISSConfig())
+            self._pith = PithPipeline(pith_config or PithConfig())
+
+        self._messages: List[Dict[str, str]] = []
+        self._turn_count = 0
+        self._total_input_tokens = 0
+        self._total_output_tokens = 0
+        self._total_time = 0.0
+        self._nuwave_time = 0.0
+
+    def prepare(self, user_message: str) -> str:
+        """CPU side: KISS + Pith context optimization → formatted prompt.
+
+        Call this BEFORE the GPU inference. Returns the full prompt
+        string ready for generate().
+        """
+        _ensure_model(self.model_name)
+
+        self._turn_count += 1
+        self._messages.append({"role": "user", "content": user_message})
+
+        # KISS + Pith (CPU only)
+        nuwave_start = time.time()
+        system_context = self.system_prompt
+        self._kiss_mode = "disabled"
+
+        if self.nuwave_enabled and self._kiss and self._pith:
+            kiss_result = self._kiss.filter_context(
+                self._messages,
+                system_context,
+            )
+            system_context = kiss_result.get("system_context", system_context)
+            self._kiss_mode = kiss_result.get("kiss_mode", "full")
+
+            if system_context:
+                context_chunks = [
+                    chunk.strip()
+                    for chunk in system_context.split("\n\n")
+                    if chunk.strip()
+                ]
+                if context_chunks:
+                    optimized = self._pith.extract(
+                        context_chunks,
+                        query=user_message,
+                    )
+                    system_context = "\n\n".join(optimized)
+
+        self._nuwave_time += time.time() - nuwave_start
+
+        # Build prompt
+        prompt_messages = []
+        if system_context:
+            prompt_messages.append({"role": "system", "content": system_context})
+        prompt_messages.extend(self._messages)
+
+        prompt = _tokenizer.apply_chat_template(
+            prompt_messages,
+            tokenize=False,
+            add_generation_prompt=True,
+        )
+        return prompt
+
+    def record(self, response: str, input_tokens: int, output_tokens: int):
+        """CPU side: record response and update state.
+
+        Call this AFTER GPU inference.
+        """
+        self._messages.append({"role": "assistant", "content": response})
+        self._total_input_tokens += input_tokens
+        self._total_output_tokens += output_tokens
+
+    def chat(self, user_message: str, max_new_tokens: int = 512) -> str:
+        """Convenience: prepare + generate + record in one call.
+
+        For non-ZeroGPU use (local testing, dedicated GPU).
+        For ZeroGPU, use prepare()/generate()/record() separately.
+        """
+        prompt = self.prepare(user_message)
+        start = time.time()
+        response, in_tok, out_tok = generate(prompt, max_new_tokens=max_new_tokens)
+        self._total_time += time.time() - start
+        self.record(response, in_tok, out_tok)
+        return response
+
+    def reset(self):
+        """Reset conversation state. Model stays loaded."""
+        self._messages = []
+        self._turn_count = 0
+        self._total_input_tokens = 0
+        self._total_output_tokens = 0
+        self._total_time = 0.0
+        self._nuwave_time = 0.0
+        if self._kiss:
+            from nuwave.kiss import KISSFilter
+            self._kiss = KISSFilter(self._kiss._config)
+        if self._pith:
+            from nuwave.pith import PithPipeline
+            self._pith = PithPipeline(self._pith._config)
+
+    def stats(self) -> Dict[str, Any]:
+        result = {
+            "model": self.model_name,
+            "nuwave_enabled": self.nuwave_enabled,
+            "turns": self._turn_count,
+            "total_input_tokens": self._total_input_tokens,
+            "total_output_tokens": self._total_output_tokens,
+            "total_time": round(self._total_time, 3),
+            "nuwave_overhead": round(self._nuwave_time, 3),
+            "avg_tokens_per_turn": self._total_input_tokens // max(self._turn_count, 1),
+        }
+        if self._kiss:
+            result["kiss"] = self._kiss.stats.to_dict()
+        if self._pith:
+            result["pith"] = self._pith.stats.to_dict()
+        return result

nuwave/benchmarks/__init__.py

@@ -0,0 +1,2 @@
+"""NuWave benchmarks — A/B testing and compound curve measurement."""
+from nuwave.benchmarks.harness import BenchmarkHarness

nuwave/benchmarks/harness.py

@@ -0,0 +1,221 @@
+"""
+Benchmark Harness — A/B Testing NuWave vs Baseline
+
+Runs the same conversation through two adapters:
+  A: Stock model (no NuWave)
+  B: Same model + NuWave (KISS + Pith)
+
+Measures context efficiency, token usage, and quality over N turns.
+Produces the compound curve — NuWave's efficiency improving over time.
+
+# ---- Changelog ----
+# [2026-03-28] Claude Code (Opus 4.6) — Initial harness
+#   What: A/B benchmark for HuggingFace demo
+#   Why:  Demonstrate NuWave compound returns empirically
+#   How:  Run same conversation through both adapters, compare metrics per turn
+# -------------------
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Callable
+
+logger = logging.getLogger("nuwave.benchmark")
+
+
+@dataclass
+class TurnResult:
+    """Result from a single conversation turn."""
+    turn: int
+    prompt: str
+    response_a: str  # baseline
+    response_b: str  # nuwave
+    tokens_a: int
+    tokens_b: int
+    time_a: float
+    time_b: float
+    kiss_mode: str = ""
+    kiss_skip_rate: float = 0.0
+    pith_l1_size: int = 0
+    pith_avg_heat: float = 0.0
+    tokens_saved: int = 0
+
+
+@dataclass
+class BenchmarkResult:
+    """Complete benchmark result."""
+    model_name: str
+    total_turns: int
+    turns: List[TurnResult]
+    stats_a: Dict[str, Any]  # baseline stats
+    stats_b: Dict[str, Any]  # nuwave stats
+
+    def summary(self) -> Dict[str, Any]:
+        total_tokens_a = sum(t.tokens_a for t in self.turns)
+        total_tokens_b = sum(t.tokens_b for t in self.turns)
+        total_time_a = sum(t.time_a for t in self.turns)
+        total_time_b = sum(t.time_b for t in self.turns)
+        total_saved = sum(t.tokens_saved for t in self.turns)
+
+        return {
+            "model": self.model_name,
+            "turns": self.total_turns,
+            "baseline_tokens": total_tokens_a,
+            "nuwave_tokens": total_tokens_b,
+            "tokens_saved": total_saved,
+            "token_efficiency": round(total_saved / max(total_tokens_a, 1), 4),
+            "baseline_time": round(total_time_a, 3),
+            "nuwave_time": round(total_time_b, 3),
+            "time_overhead": round((total_time_b - total_time_a) / max(total_time_a, 1), 4),
+            "final_kiss_skip_rate": self.turns[-1].kiss_skip_rate if self.turns else 0,
+            "final_pith_l1_size": self.turns[-1].pith_l1_size if self.turns else 0,
+        }
+
+    def compound_curve(self) -> List[Dict[str, Any]]:
+        """Per-turn efficiency data for plotting the compound curve."""
+        curve = []
+        cumulative_saved = 0
+        cumulative_total = 0
+        for t in self.turns:
+            cumulative_saved += t.tokens_saved
+            cumulative_total += t.tokens_a
+            curve.append({
+                "turn": t.turn,
+                "kiss_skip_rate": t.kiss_skip_rate,
+                "pith_l1_size": t.pith_l1_size,
+                "pith_avg_heat": t.pith_avg_heat,
+                "tokens_saved_this_turn": t.tokens_saved,
+                "cumulative_efficiency": round(
+                    cumulative_saved / max(cumulative_total, 1), 4
+                ),
+                "tokens_a": t.tokens_a,
+                "tokens_b": t.tokens_b,
+            })
+        return curve
+
+    def to_json(self, path: str):
+        """Save full results to JSON."""
+        data = {
+            "summary": self.summary(),
+            "compound_curve": self.compound_curve(),
+            "stats_baseline": self.stats_a,
+            "stats_nuwave": self.stats_b,
+        }
+        with open(path, "w") as f:
+            json.dump(data, f, indent=2)
+
+
+class BenchmarkHarness:
+    """A/B benchmark harness for NuWave vs baseline.
+
+    Usage:
+        harness = BenchmarkHarness("microsoft/Phi-4-mini")
+        result = harness.run(conversations)
+        print(result.summary())
+        result.to_json("benchmark_results.json")
+    """
+
+    def __init__(
+        self,
+        model_name: str,
+        system_prompt: str = "",
+        device: str = "auto",
+    ):
+        self.model_name = model_name
+        self.system_prompt = system_prompt
+        self.device = device
+
+    def run(
+        self,
+        conversations: List[str],
+        max_new_tokens: int = 256,
+    ) -> BenchmarkResult:
+        """Run A/B benchmark.
+
+        Args:
+            conversations: List of user messages to send sequentially
+            max_new_tokens: Max tokens per response
+
+        Returns:
+            BenchmarkResult with per-turn data and compound curve
+        """
+        from nuwave.adapters.huggingface import HuggingFaceAdapter
+
+        logger.info("Starting A/B benchmark: %s (%d turns)", self.model_name, len(conversations))
+
+        # A: Baseline (no NuWave)
+        adapter_a = HuggingFaceAdapter(
+            self.model_name,
+            nuwave_enabled=False,
+            device=self.device,
+            system_prompt=self.system_prompt,
+        )
+
+        # B: NuWave enabled
+        adapter_b = HuggingFaceAdapter(
+            self.model_name,
+            nuwave_enabled=True,
+            device=self.device,
+            system_prompt=self.system_prompt,
+        )
+
+        turns = []
+
+        for i, prompt in enumerate(conversations):
+            turn_num = i + 1
+            logger.info("Turn %d/%d: %s...", turn_num, len(conversations), prompt[:50])
+
+            # Baseline
+            t0 = time.time()
+            response_a = adapter_a.chat(prompt, max_new_tokens=max_new_tokens)
+            time_a = time.time() - t0
+            stats_a_now = adapter_a.stats()
+
+            # NuWave
+            t0 = time.time()
+            response_b = adapter_b.chat(prompt, max_new_tokens=max_new_tokens)
+            time_b = time.time() - t0
+            stats_b_now = adapter_b.stats()
+
+            # Extract KISS/Pith metrics
+            kiss_stats = stats_b_now.get("kiss", {})
+            pith_stats = stats_b_now.get("pith", {})
+
+            turn = TurnResult(
+                turn=turn_num,
+                prompt=prompt,
+                response_a=response_a,
+                response_b=response_b,
+                tokens_a=stats_a_now.get("total_input_tokens", 0),
+                tokens_b=stats_b_now.get("total_input_tokens", 0),
+                time_a=time_a,
+                time_b=time_b,
+                kiss_mode=kiss_stats.get("kiss_mode", ""),
+                kiss_skip_rate=kiss_stats.get("skip_rate", 0),
+                pith_l1_size=pith_stats.get("l1_current_size", 0),
+                pith_avg_heat=pith_stats.get("l1_avg_heat", 0),
+                tokens_saved=kiss_stats.get("tokens_saved", 0),
+            )
+            turns.append(turn)
+
+            logger.info(
+                "  A: %d tokens, %.2fs | B: %d tokens, %.2fs (KISS skip: %.1f%%)",
+                turn.tokens_a, time_a,
+                turn.tokens_b, time_b,
+                turn.kiss_skip_rate * 100,
+            )
+
+        result = BenchmarkResult(
+            model_name=self.model_name,
+            total_turns=len(conversations),
+            turns=turns,
+            stats_a=adapter_a.stats(),
+            stats_b=adapter_b.stats(),
+        )
+
+        logger.info("Benchmark complete: %s", result.summary())
+        return result

nuwave/demo/__init__.py

@@ -0,0 +1 @@
+"""NuWave Gradio demo for HuggingFace Spaces."""

nuwave/kiss/__init__.py

@@ -0,0 +1,2 @@
+"""KISS — Keep Input Simple, Substrate. NuWave Layer 1."""
+from nuwave.kiss.filter import KISSFilter, KISSConfig

nuwave/kiss/filter.py

@@ -0,0 +1,222 @@
+"""
+KISS Filter — Keep Input Simple, Substrate
+
+Manages what reaches the model's context window. Tracks conversation
+history and determines what context the model actually needs.
+
+KISS does NOT classify input (Law 7). It removes redundancy, not meaning.
+
+Key insight: in multi-turn conversation, the system context is the same
+every turn (redundant), early conversation history has already been
+processed (redundant), and only the recent messages + new context are
+genuinely novel. KISS separates these and compresses accordingly.
+
+# ---- Changelog ----
+# [2026-03-29] Claude Code (Opus 4.6) — Fixed delta detection
+#   What: Separate system context delta from message delta. Compress
+#         old conversation history. Only pass genuinely novel context.
+#   Why:  Hashing full message history meant every turn was "different"
+#         because new messages got added. KISS never triggered.
+#   How:  Track system context hash separately. Compress old messages
+#         into summary. Recent window passes verbatim. System context
+#         skipped when unchanged.
+# [2026-03-28] Claude Code (Opus 4.6) — Initial implementation
+# -------------------
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger("nuwave.kiss")
+
+
+@dataclass
+class KISSConfig:
+    """KISS filter configuration."""
+    # Warmup: pass everything raw
+    warmup_turns: int = 3
+
+    # Recent window: how many recent messages to always pass verbatim
+    recent_window: int = 6  # 3 user + 3 assistant turns
+
+    # Force full context refresh every N turns (GOP boundary)
+    force_full_every: int = 20
+
+    # System context: skip if unchanged from last turn
+    skip_unchanged_system: bool = True
+
+
+@dataclass
+class KISSStats:
+    """Running statistics for KISS filtering."""
+    total_turns: int = 0
+    system_skipped: int = 0
+    history_compressed: int = 0
+    full_passed: int = 0
+    warmup_passed: int = 0
+    tokens_saved: int = 0
+    tokens_total: int = 0
+    messages_compressed: int = 0  # how many old messages were summarized
+
+    @property
+    def skip_rate(self) -> float:
+        if self.total_turns <= 0:
+            return 0.0
+        return self.system_skipped / max(self.total_turns, 1)
+
+    @property
+    def efficiency(self) -> float:
+        return self.tokens_saved / max(self.tokens_total, 1)
+
+    @property
+    def compression_rate(self) -> float:
+        return self.messages_compressed / max(self.total_turns, 1)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "total_turns": self.total_turns,
+            "system_skipped": self.system_skipped,
+            "history_compressed": self.history_compressed,
+            "full_passed": self.full_passed,
+            "warmup_passed": self.warmup_passed,
+            "skip_rate": round(self.skip_rate, 4),
+            "efficiency": round(self.efficiency, 4),
+            "tokens_saved": self.tokens_saved,
+            "tokens_total": self.tokens_total,
+            "messages_compressed": self.messages_compressed,
+            "compression_rate": round(self.compression_rate, 4),
+        }
+
+
+class KISSFilter:
+    """KISS filter for context window optimization.
+
+    Three things happen every turn:
+    1. System context: same as last turn? Skip it (delta gate).
+    2. Old messages: beyond the recent window? Compress to summary.
+    3. Recent messages: pass verbatim — the model needs these.
+
+    The result: the model sees a summary of old conversation + recent
+    messages in full + system context only when it changes. Token usage
+    grows logarithmically, not linearly.
+    """
+
+    def __init__(self, config: KISSConfig = None):
+        self._config = config or KISSConfig()
+        self._last_system_hash: Optional[str] = None
+        self._since_full: int = 0
+        self._turn_count: int = 0
+        self.stats = KISSStats()
+
+    def filter_context(
+        self,
+        messages: List[Dict[str, str]],
+        system_context: str = "",
+    ) -> Dict[str, Any]:
+        """Filter context for the next model call.
+
+        Args:
+            messages: Full conversation history
+            system_context: System prompt / substrate context
+
+        Returns:
+            Dict with 'system_context' (filtered), 'kiss_mode', 'kiss_meta'
+        """
+        self._turn_count += 1
+        self.stats.total_turns += 1
+        total_tokens = sum(len(m.get("content", "").split()) for m in messages)
+        total_tokens += len(system_context.split()) if system_context else 0
+        self.stats.tokens_total += total_tokens
+
+        # Warmup — pass everything raw
+        if self._turn_count <= self._config.warmup_turns:
+            self._last_system_hash = self._hash(system_context)
+            self.stats.warmup_passed += 1
+            self.stats.full_passed += 1
+            return {
+                "system_context": system_context,
+                "kiss_mode": "full",
+                "kiss_meta": {"reason": "warmup", "turn": self._turn_count},
+            }
+
+        # Forced full refresh (GOP boundary)
+        self._since_full += 1
+        if self._since_full >= self._config.force_full_every:
+            self._since_full = 0
+            self._last_system_hash = self._hash(system_context)
+            self.stats.full_passed += 1
+            return {
+                "system_context": system_context,
+                "kiss_mode": "full",
+                "kiss_meta": {"reason": "gop_refresh"},
+            }
+
+        # 1. System context delta gate
+        current_sys_hash = self._hash(system_context)
+        system_changed = current_sys_hash != self._last_system_hash
+        self._last_system_hash = current_sys_hash
+
+        filtered_system = system_context if system_changed else ""
+        if not system_changed:
+            self.stats.system_skipped += 1
+            sys_tokens = len(system_context.split()) if system_context else 0
+            self.stats.tokens_saved += sys_tokens
+
+        # 2. History compression — summarize old messages
+        n_messages = len(messages)
+        recent_window = self._config.recent_window
+        compressed_count = 0
+
+        if n_messages > recent_window:
+            old_messages = messages[:n_messages - recent_window]
+            old_token_count = sum(len(m.get("content", "").split()) for m in old_messages)
+
+            # Build compact summary of old conversation
+            summary_parts = []
+            for m in old_messages:
+                role = m.get("role", "unknown")
+                content = m.get("content", "")
+                # First sentence or first 60 chars
+                short = content.split(".")[0][:60]
+                if len(content) > 60:
+                    short += "..."
+                summary_parts.append(f"{role}: {short}")
+
+            summary = "[Earlier conversation: " + " | ".join(summary_parts) + "]"
+            summary_tokens = len(summary.split())
+            tokens_saved = max(0, old_token_count - summary_tokens)
+            compressed_count = len(old_messages)
+
+            self.stats.tokens_saved += tokens_saved
+            self.stats.history_compressed += 1
+            self.stats.messages_compressed += compressed_count
+
+            # Prepend summary to system context
+            if filtered_system:
+                filtered_system = summary + "\n\n" + filtered_system
+            else:
+                filtered_system = summary
+
+            kiss_mode = "compressed"
+        else:
+            kiss_mode = "sparse" if not system_changed else "full"
+
+        return {
+            "system_context": filtered_system,
+            "kiss_mode": kiss_mode,
+            "kiss_meta": {
+                "system_changed": system_changed,
+                "messages_total": n_messages,
+                "messages_compressed": compressed_count,
+                "recent_window": min(recent_window, n_messages),
+            },
+        }
+
+    @staticmethod
+    def _hash(content: str) -> str:
+        return hashlib.sha256(content.encode()).hexdigest()[:16]

nuwave/lenia_splat.py

@@ -0,0 +1,328 @@
+"""
+Lenia Dynamics on Gaussian Splats
+=================================
+Adapted from UniAI's LeniaEngine to operate on splat parameters
+(mu, sigma, alpha) instead of raw weight values.
+
+Key insight: Gaussian splats ARE Lenia kernels. The same structure
+serves as both weight representation and dynamics engine. A splat's
+sigma IS its neighborhood, its alpha IS its state, and its mu IS
+its position in weight space.
+
+Lenia growth function operates on the neighborhood potential
+between splats. Splats that are near each other interact:
+- Their amplitudes modulate based on the growth function
+- Their positions drift based on gradient of the potential field
+- Their spreads adapt based on local reconstruction error
+
+This means the "compression" is alive — it reshapes itself
+continuously based on what the model is processing.
+
+# ---- Changelog ----
+# [2026-04-05] Claude Code (Opus 4.6) — Initial implementation
+#   What: Lenia dynamics adapted for Gaussian splat parameters
+#   Why:  Prove splats can evolve via continuous dynamics
+# -------------------
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+import torch
+import torch.nn.functional as F
+
+from nuwave.splat_engine import GaussianSplats
+
+logger = logging.getLogger("uniai.lenia_splat")
+
+
+@dataclass
+class LeniaSplatConfig:
+    """Configuration for Lenia dynamics on splats."""
+
+    # Growth function parameters (from proven VPS config)
+    growth_mu: float = 0.15         # target neighborhood potential
+    growth_sigma: float = 0.015     # growth function width
+    growth_scale: float = 0.001     # dt — how fast splats change per step
+
+    # Splat interaction radius (in weight-space units)
+    interaction_radius: float = 5.0
+
+    # Position dynamics
+    position_lr: float = 0.0003     # how fast splats drift
+    sigma_lr: float = 0.0001        # how fast spreads adapt
+
+    # Activation coupling — the resource (from ProtoUniBrain pattern)
+    # Higher activation through a weight region = stronger Lenia dynamics there
+    activation_coupling: float = 2.0
+
+    # Safety
+    max_alpha_delta: float = 0.02   # max amplitude change per step
+    max_position_delta: float = 0.3 # max position drift per step
+    min_sigma: float = 0.1          # don't let splats collapse to points
+    max_sigma: float = 10.0         # don't let splats blow up
+
+    # Mass conservation
+    conserve_mass: bool = True      # preserve total |alpha| per layer
+
+
+@dataclass
+class SplatDynamicsState:
+    """Runtime state of splat Lenia dynamics."""
+    step_count: int = 0
+    total_time_ms: float = 0.0
+    alpha_deltas: Dict[str, float] = field(default_factory=dict)
+    position_deltas: Dict[str, float] = field(default_factory=dict)
+
+
+class LeniaSplatEngine:
+    """
+    Applies Lenia dynamics to Gaussian splat parameters.
+
+    Instead of convolving over a weight grid, we compute
+    splat-to-splat interactions directly. Each splat's neighborhood
+    potential is the weighted sum of nearby splats' contributions.
+
+    Usage:
+        engine = LeniaSplatEngine(config)
+        engine.register_layer("layer_0", splats)
+        metrics = engine.step()  # evolve all registered splat layers
+    """
+
+    def __init__(self, config: LeniaSplatConfig = None):
+        self.config = config or LeniaSplatConfig()
+        self.state = SplatDynamicsState()
+        self.layers: Dict[str, GaussianSplats] = {}
+        self._initial_mass: Dict[str, float] = {}
+
+    def register_layer(self, name: str, splats: GaussianSplats):
+        """Register a splat layer for Lenia dynamics."""
+        self.layers[name] = splats
+        self._initial_mass[name] = splats.alpha.abs().sum().item()
+        self._activation_maps: Dict[str, torch.Tensor] = {}
+
+    def feed_activations(self, name: str, input_vec: torch.Tensor, output_vec: torch.Tensor):
+        """Feed activation flow from a forward pass through this weight layer.
+
+        Given the input and output vectors of a matmul through the weight matrix,
+        compute per-splat activation magnitude: how much signal flowed through
+        each splat's region of weight space.
+
+        This is the resource that modulates Lenia growth — used pathways evolve
+        faster, unused pathways decay. Same principle as ProtoUniBrain.
+        """
+        splats = self.layers.get(name)
+        if splats is None:
+            return
+
+        # Input activations tell us which COLUMNS were active
+        # Output activations tell us which ROWS were active
+        # A splat at position (r, c) gets activation proportional to
+        # how active its row AND column were
+
+        # Normalize to [0, 1]
+        in_mag = input_vec.abs().float()
+        out_mag = output_vec.abs().float()
+        in_mag = in_mag / (in_mag.max() + 1e-8)
+        out_mag = out_mag / (out_mag.max() + 1e-8)
+
+        # Per-splat activation: how active is the region each splat covers?
+        # Splat at (mu_r, mu_c) — sample activation at its position
+        mu_r = splats.mu[:, 0].long().clamp(0, len(out_mag) - 1)
+        mu_c = splats.mu[:, 1].long().clamp(0, len(in_mag) - 1)
+
+        splat_activation = out_mag[mu_r] * in_mag[mu_c]  # (n_splats,)
+        self._activation_maps[name] = splat_activation
+
+    # -----------------------------------------------------------------
+    # Growth function (same as proven LeniaEngine)
+    # -----------------------------------------------------------------
+
+    def _growth_function(self, potential: torch.Tensor) -> torch.Tensor:
+        """Lenia growth function: bell curve centered on growth_mu.
+
+        G(u) = 2 * exp(-((u - mu) / sigma)^2 / 2) - 1
+
+        Returns [-1, 1]: positive near mu, negative far from mu.
+        This IS the learning rule.
+        """
+        mu = self.config.growth_mu
+        sigma = self.config.growth_sigma
+        return 2.0 * torch.exp(-((potential - mu) / sigma) ** 2 / 2) - 1.0
+
+    # -----------------------------------------------------------------
+    # Splat-to-splat interaction
+    # -----------------------------------------------------------------
+
+    def _compute_neighborhood_potential(self, splats: GaussianSplats) -> torch.Tensor:
+        """Compute neighborhood potential for each splat.
+
+        For each splat i, the potential is the weighted sum of contributions
+        from all other splats within interaction_radius:
+
+          U(i) = sum_{j != i} |alpha_j| * exp(-||mu_i - mu_j||^2 / (2 * R^2))
+
+        This tells us "how much weight activity is in my neighborhood."
+        """
+        n = splats.n_splats
+        R = self.config.interaction_radius
+
+        # Pairwise distances between splat centers
+        # mu: (N, 2)
+        diff = splats.mu.unsqueeze(0) - splats.mu.unsqueeze(1)  # (N, N, 2)
+        dist_sq = (diff ** 2).sum(dim=2)  # (N, N)
+
+        # Gaussian interaction kernel (not self-interaction)
+        interaction = torch.exp(-dist_sq / (2 * R ** 2))
+        interaction.fill_diagonal_(0.0)  # no self-interaction
+
+        # Potential = weighted by neighbor amplitudes
+        potential = (interaction * splats.alpha.abs().unsqueeze(0)).sum(dim=1)  # (N,)
+
+        return potential
+
+    def _compute_position_gradient(self, splats: GaussianSplats, growth: torch.Tensor) -> torch.Tensor:
+        """Compute position drift for each splat based on growth gradients.
+
+        Splats drift toward regions where their growth would be more positive.
+        This is how the compression adapts — splats migrate to where they're needed.
+
+        Uses the gradient of the potential field: splats with negative growth
+        move toward regions with potential closer to growth_mu.
+        """
+        n = splats.n_splats
+        R = self.config.interaction_radius
+
+        diff = splats.mu.unsqueeze(0) - splats.mu.unsqueeze(1)  # (N, N, 2)
+        dist_sq = (diff ** 2).sum(dim=2)  # (N, N)
+
+        interaction = torch.exp(-dist_sq / (2 * R ** 2))
+        interaction.fill_diagonal_(0.0)
+
+        # Gradient of potential w.r.t. position
+        # d/d(mu_i) of exp(-||mu_i - mu_j||^2 / 2R^2) = -(mu_i - mu_j)/R^2 * exp(...)
+        grad_interaction = -diff / (R ** 2) * interaction.unsqueeze(2)  # (N, N, 2)
+
+        # Weight by neighbor amplitudes and own growth signal
+        weighted_grad = (grad_interaction * splats.alpha.abs().unsqueeze(0).unsqueeze(2)).sum(dim=1)  # (N, 2)
+
+        # Modulate by growth: negative growth = move more, positive growth = stay
+        move_strength = torch.clamp(-growth, min=0).unsqueeze(1)  # (N, 1)
+        position_delta = weighted_grad * move_strength * self.config.position_lr
+
+        return position_delta
+
+    # -----------------------------------------------------------------
+    # Dynamics step
+    # -----------------------------------------------------------------
+
+    @torch.no_grad()
+    def step(self) -> Dict[str, Any]:
+        """Apply one Lenia dynamics step to all registered splat layers."""
+        start = time.time()
+        metrics = {
+            'step': self.state.step_count + 1,
+            'layers': {},
+            'total_alpha_delta': 0.0,
+            'total_position_delta': 0.0,
+        }
+
+        for name, splats in self.layers.items():
+            layer_metrics = self._step_layer(name, splats)
+            metrics['layers'][name] = layer_metrics
+            metrics['total_alpha_delta'] += layer_metrics['alpha_delta_mean']
+            metrics['total_position_delta'] += layer_metrics['position_delta_mean']
+
+        elapsed = (time.time() - start) * 1000
+        metrics['time_ms'] = elapsed
+        self.state.step_count += 1
+        self.state.total_time_ms += elapsed
+
+        return metrics
+
+    def _step_layer(self, name: str, splats: GaussianSplats) -> Dict[str, float]:
+        """Apply Lenia dynamics to a single splat layer."""
+        cfg = self.config
+
+        # 1. Compute neighborhood potential
+        potential = self._compute_neighborhood_potential(splats)
+
+        # 2. Growth function — THIS IS the learning rule
+        # Near growth_mu: positive (reinforce). Far from growth_mu: negative (weaken).
+        # Stability emerges from the dynamics themselves. Myelination observes it.
+        growth = self._growth_function(potential)
+
+        # 3. Modulate by activation flow (the resource)
+        # Base dynamics always run. Activation BOOSTS used regions.
+        # A splat with zero activation still evolves at base rate.
+        # A splat with high activation evolves up to (1 + coupling) faster.
+        if name in self._activation_maps and cfg.activation_coupling > 0:
+            act = self._activation_maps[name]
+            boost = torch.tanh(act * cfg.activation_coupling)  # [0, ~1]
+            growth = growth * (1.0 + boost)  # base rate * [1.0, 2.0]
+
+        # 4. Update amplitudes — direct growth, no artificial damping
+        alpha_delta = cfg.growth_scale * growth
+        alpha_delta = alpha_delta.clamp(-cfg.max_alpha_delta, cfg.max_alpha_delta)
+        splats.alpha += alpha_delta
+
+        # 5. Update positions — splats drift toward better neighborhoods
+        position_delta = self._compute_position_gradient(splats, growth)
+        position_delta = position_delta.clamp(-cfg.max_position_delta, cfg.max_position_delta)
+        splats.mu += position_delta
+
+        # 6. Adapt sigma based on local density
+        # Dense regions → tighter splats (more precision)
+        # Sparse regions → wider splats (more coverage)
+        density = potential / (potential.max() + 1e-8)  # normalized [0, 1]
+        sigma_delta = cfg.sigma_lr * (0.5 - density)  # dense = shrink, sparse = grow
+        splats.sigma += sigma_delta
+        splats.sigma.clamp_(cfg.min_sigma, cfg.max_sigma)
+
+        # 7. Keep positions in bounds
+        splats.mu[:, 0].clamp_(0, splats.rows - 1)
+        splats.mu[:, 1].clamp_(0, splats.cols - 1)
+
+        # 8. Mass conservation
+        if cfg.conserve_mass and name in self._initial_mass:
+            current_mass = splats.alpha.abs().sum().item()
+            target_mass = self._initial_mass[name]
+            if current_mass > 0:
+                splats.alpha *= (target_mass / current_mass)
+
+        # Metrics
+        alpha_delta_mean = alpha_delta.abs().mean().item()
+        position_delta_mean = position_delta.abs().mean().item()
+
+        self.state.alpha_deltas[name] = alpha_delta_mean
+        self.state.position_deltas[name] = position_delta_mean
+
+        return {
+            'alpha_delta_mean': alpha_delta_mean,
+            'position_delta_mean': position_delta_mean,
+            'sigma_mean': splats.sigma.mean().item(),
+            'sigma_std': splats.sigma.std().item(),
+            'potential_mean': potential.mean().item(),
+            'growth_mean': growth.mean().item(),
+        }
+
+    # -----------------------------------------------------------------
+    # Diagnostics
+    # -----------------------------------------------------------------
+
+    def get_summary(self) -> Dict[str, Any]:
+        """Get dynamics state summary."""
+        return {
+            'steps': self.state.step_count,
+            'total_time_ms': self.state.total_time_ms,
+            'avg_step_ms': (
+                self.state.total_time_ms / self.state.step_count
+                if self.state.step_count > 0 else 0
+            ),
+            'num_layers': len(self.layers),
+            'total_splats': sum(s.n_splats for s in self.layers.values()),
+        }

nuwave/organism.py

@@ -0,0 +1,662 @@
+"""
+NuWave Organism — The Living System
+
+Wires the full loop:
+  User message → substrate (raw experience, Law 7)
+  → graph.step() (substrate processes)
+  → KISS bucket extracts from River (what changed?)
+  → Pith bucket extracts from River (what's relevant?)
+  → Model generates with focused context
+  → Outcome feeds back into substrate (raw experience, Law 7)
+  → Substrate learns → topology reshapes → next cycle's buckets extract differently
+
+KISS and Pith don't read the substrate directly. They extract from
+the River through their own shaped buckets. The substrate is the
+communication protocol (Law 1). Raw experience in, classification
+only at extraction (Law 7).
+
+# ---- Changelog ----
+# [2026-04-06] Claude Code (Opus 4.6) — Initial organism wiring
+#   What: Full substrate loop for HuggingFace NuWave demo
+#   Why:  Baseline proved 47.2% with crude string KISS. Real substrate
+#         + real KISS/Pith buckets should exceed that significantly.
+#   How:  ng_lite substrate, ng_embed for embeddings, ng_tract for
+#         binary topology. KISS reads StepResult. Pith extracts via
+#         spreading activation. Outcomes close the loop.
+# -------------------
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+import time
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+
+logger = logging.getLogger("nuwave.organism")
+
+# Substrate path — added temporarily during import, not permanently
+_substrate_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'substrate')
+
+
+class NuWaveOrganism:
+    """The living system. Substrate + KISS bucket + Pith bucket.
+
+    Usage:
+        organism = NuWaveOrganism()
+        kiss_context, pith_context = organism.process_input(user_message)
+        # ... model generates with pith_context ...
+        organism.record_outcome(user_message, response, success=True)
+    """
+
+    # Hub persistence — survives container rebuilds, sleeps, everything
+    HUB_REPO = "Executor-Tyrant-Framework/nuwave-substrate-state"
+    HUB_FILENAME = "organism_state.pt"
+
+    def __init__(self, state_path: str = "/tmp/nuwave_substrate"):
+        self._state_path = state_path
+        os.makedirs(state_path, exist_ok=True)
+        self._local_state_path = os.path.join(state_path, "organism_state.pt")
+        self._hf_token = os.environ.get("HF_TOKEN", None)
+
+        # Initialize substrate
+        self._graph = None
+        self._embed_fn = None
+        self._step_result = None
+        self._step_count = 0
+        self._node_content: Dict[str, str] = {}  # node_id → content for Pith
+
+        # Amplitude field — per-node complex amplitude for interference dynamics
+        # amplitude: how strongly this node contributes (grown by use, decayed by time)
+        # phase: oscillation angle (advanced each step, interference depends on alignment)
+        self._amplitudes: Dict[str, float] = {}   # node_id → |a| in [0, 1]
+        self._phases: Dict[str, float] = {}       # node_id → θ in [0, 2π]
+        self._amplitude_decay: float = 0.05       # per step — halves in ~14 steps
+        self._interference_rate: float = 0.15     # how strongly neighbors interfere
+        self._amplitude_coupling: float = 0.4     # how strongly activation grows amplitude
+
+        # Stats
+        self.stats = {
+            'steps': 0,
+            'nodes': 0,
+            'synapses': 0,
+            'hyperedges': 0,
+            'fired_nodes': 0,
+            'fired_hyperedges': 0,
+            'predictions_confirmed': 0,
+            'predictions_surprised': 0,
+            'kiss_skips': 0,
+            'kiss_passes': 0,
+            'pith_l1_size': 0,
+            'pith_promotions': 0,
+        }
+
+        self._init_substrate()
+        self._restore_state()
+
+    def _restore_state(self):
+        """Restore persisted state — local first, then hub.
+
+        Hub persistence survives container rebuilds, sleeps, code pushes.
+        Local is faster on warm restart. Hub is the permanent backup.
+        """
+        import json
+
+        # Try local first (warm restart)
+        restored = self._try_restore_local()
+        if restored:
+            return
+
+        # Try hub (cold restart after rebuild)
+        restored = self._try_restore_hub()
+        if restored:
+            return
+
+        logger.info("No saved state found — starting fresh organism")
+
+    def _try_restore_local(self) -> bool:
+        """Restore from local state file."""
+        if not os.path.exists(self._local_state_path):
+            return False
+        try:
+            import torch
+            state = torch.load(self._local_state_path, map_location="cpu", weights_only=False)
+            return self._apply_state(state, source="local")
+        except Exception as exc:
+            logger.warning("Local restore failed: %s", exc)
+            return False
+
+    def _try_restore_hub(self) -> bool:
+        """Pull state from HuggingFace dataset repo."""
+        if not self._hf_token:
+            return False
+        try:
+            from huggingface_hub import hf_hub_download
+            local = hf_hub_download(
+                self.HUB_REPO, self.HUB_FILENAME,
+                repo_type="dataset", local_dir=self._state_path,
+                token=self._hf_token,
+            )
+            import torch
+            state = torch.load(local, map_location="cpu", weights_only=False)
+            return self._apply_state(state, source="hub")
+        except Exception as exc:
+            logger.info("No hub state: %s", exc)
+            return False
+
+    def _apply_state(self, state: dict, source: str) -> bool:
+        """Apply a loaded state dict to the organism."""
+        try:
+            # Graph checkpoint — stored as JSON string
+            graph_json = state.get('graph_checkpoint_json')
+            if graph_json and self._graph:
+                tmp = os.path.join(self._state_path, "_tmp_restore.ckpt")
+                with open(tmp, 'w') as f:
+                    f.write(graph_json)
+                self._graph.restore(tmp)
+                os.remove(tmp)
+
+            # Content map
+            self._node_content = state.get('node_content', {})
+
+            # Stats
+            saved_stats = state.get('stats', {})
+            self.stats.update(saved_stats)
+            self._step_count = self.stats.get('steps', 0)
+
+            # Amplitudes
+            self._amplitudes = state.get('amplitudes', {})
+            self._phases = state.get('phases', {})
+
+            logger.info(
+                "Organism restored from %s: %d nodes, %d syn, %d content, step %d, %d amplitudes",
+                source,
+                len(self._graph.nodes) if self._graph else 0,
+                len(self._graph.synapses) if self._graph else 0,
+                len(self._node_content),
+                self._step_count,
+                len(self._amplitudes),
+            )
+            return True
+        except Exception as exc:
+            logger.warning("State apply failed (%s): %s", source, exc)
+            return False
+
+    def _init_substrate(self):
+        """Initialize the full NeuroGraph SNN substrate.
+
+        This is the real Graph — firing, Hebbian learning, hyperedges,
+        predictions, StepResult. Not NGLite (the Tier 1 notepad).
+        KISS and Pith read from this through their buckets.
+
+        Adds substrate dir to sys.path during import, removes after.
+        No permanent path pollution.
+        """
+        try:
+            # Temporarily add substrate dir for import resolution
+            _added = _substrate_dir not in sys.path
+            if _added:
+                sys.path.insert(0, _substrate_dir)
+
+            from neuro_foundation import Graph
+
+            # Remove path after import — no permanent pollution
+            if _added and _substrate_dir in sys.path:
+                sys.path.remove(_substrate_dir)
+
+            self._graph = Graph(config={
+                "default_threshold": 0.85,
+                "decay_rate": 0.97,
+                "prime_strength": 1.0,
+                "learning_rate": 0.08,
+                "surprise_reward_scaling": 1.5,
+            })
+            logger.info("Substrate initialized: full NeuroGraph SNN")
+        except Exception as exc:
+            logger.error("NeuroGraph init failed: %s", exc)
+            if _substrate_dir in sys.path:
+                sys.path.remove(_substrate_dir)
+            self._graph = None
+
+        # Initialize embedding function
+        try:
+            _added = _substrate_dir not in sys.path
+            if _added:
+                sys.path.insert(0, _substrate_dir)
+
+            from ng_embed import embed
+            self._embed_fn = embed
+
+            if _added and _substrate_dir in sys.path:
+                sys.path.remove(_substrate_dir)
+
+            logger.info("Embedding function loaded (ng_embed)")
+        except Exception as exc:
+            if _substrate_dir in sys.path:
+                sys.path.remove(_substrate_dir)
+            logger.warning("ng_embed not available, using hash fallback: %s", exc)
+            self._embed_fn = self._hash_embed
+
+    def _hash_embed(self, text: str) -> np.ndarray:
+        """Fallback embedding — deterministic hash to 768-dim vector."""
+        import hashlib
+        h = hashlib.sha256(text.encode()).digest()
+        # Expand hash to 768 dims
+        rng = np.random.RandomState(int.from_bytes(h[:4], 'big'))
+        return rng.randn(768).astype(np.float32)
+
+    # -----------------------------------------------------------------
+    # The Loop
+    # -----------------------------------------------------------------
+
+    def deposit_experience(self, text: str) -> Optional[str]:
+        """Deposit raw experience into the substrate. Law 7 — unclassified.
+
+        Creates a node in the SNN for this experience and stimulates it.
+        The substrate learns through STDP — nodes that fire together
+        wire together. No classification imposed.
+
+        Returns the node_id.
+        """
+        if self._graph is None:
+            return None
+
+        try:
+            embedding = self._embed_fn(text)
+            node_id = f"exp_{self._step_count}_{hash(text) & 0xFFFF:04x}"
+
+            # Create node in the SNN
+            node = self._graph.create_node(
+                node_id=node_id,
+                metadata={
+                    "content": text[:200],
+                    "step": self._step_count,
+                    "type": "experience",
+                },
+            )
+
+            # Store embedding in metadata for Pith similarity search
+            node.metadata['embedding'] = embedding.tolist()
+
+            # Track for Pith retrieval
+            self._node_content[node_id] = text[:200]
+
+            # Initialize amplitude for new node — starts at 1.0 (just deposited)
+            self._amplitudes[node_id] = 1.0
+            self._phases[node_id] = float(hash(node_id) % 628) / 100.0  # deterministic [0, 2π]
+
+            # Interference-based co-stimulation.
+            # No threshold. Compute interference between new node and all existing.
+            # Constructive interference (aligned phases + similar embeddings) = amplify.
+            # Destructive (anti-aligned + dissimilar) = suppress.
+            # Stimulation current is proportional to interference result.
+            import math
+
+            self._graph.stimulate(node_id, current=1.5)  # new node always fires
+
+            for existing_id, existing_node in self._graph.nodes.items():
+                if existing_id == node_id:
+                    continue
+                existing_emb = existing_node.metadata.get('embedding') if existing_node.metadata else None
+                if existing_emb is None:
+                    continue
+
+                existing_emb = np.array(existing_emb, dtype=np.float32)
+                sim = float(np.dot(embedding, existing_emb) /
+                            (np.linalg.norm(embedding) * np.linalg.norm(existing_emb) + 1e-8))
+
+                # Interference: amplitude product × cosine of phase difference
+                # Positive = constructive (similar content, aligned phase)
+                # Negative = destructive (dissimilar, anti-aligned)
+                a_new = self._amplitudes.get(node_id, 1.0)
+                a_existing = self._amplitudes.get(existing_id, 0.5)
+                phase_new = self._phases.get(node_id, 0.0)
+                phase_existing = self._phases.get(existing_id, 0.0)
+
+                interference = a_new * a_existing * math.cos(phase_new - phase_existing)
+
+                # Semantic similarity modulates interference direction
+                # sim > 0.5: constructive amplified. sim < 0.5: destructive amplified.
+                effective_interference = interference * (2.0 * sim - 1.0)
+
+                # Boost existing node's amplitude by interference
+                self._amplitudes[existing_id] = max(0.0, min(1.0,
+                    a_existing + self._interference_rate * effective_interference))
+
+                # Stimulate proportional to constructive interference
+                # Physics decides who co-fires, not a threshold
+                if effective_interference > 0:
+                    current = 1.5 * effective_interference
+                    self._graph.stimulate(existing_id, current=current)
+
+            return node_id
+        except Exception as exc:
+            logger.debug("Deposit failed: %s", exc)
+            return None
+
+    def step(self) -> Dict[str, Any]:
+        """Run one substrate step. The topology processes.
+
+        Returns StepResult-like dict with what happened:
+        fired nodes, fired hyperedges, predictions, structural changes.
+        KISS reads this. Pith reads this.
+        """
+        if self._graph is None:
+            return {}
+
+        try:
+            step_result = self._graph.step()
+            self._step_result = step_result
+            self._step_count += 1
+
+            # StepResult has real dataclass fields — read them directly
+            result = {
+                'step': self._step_count,
+                'fired_nodes': list(step_result.fired_node_ids),
+                'fired_hyperedges': list(step_result.fired_hyperedge_ids),
+                'predictions_confirmed': step_result.predictions_confirmed,
+                'predictions_surprised': step_result.predictions_surprised,
+                'synapses_pruned': step_result.synapses_pruned,
+                'synapses_sprouted': step_result.synapses_sprouted,
+                'timestep': step_result.timestep,
+            }
+
+            # Amplitude dynamics — decay + activation boost for fired nodes
+            import math
+            for nid in self._amplitudes:
+                # Decay all amplitudes
+                self._amplitudes[nid] *= (1.0 - self._amplitude_decay)
+
+                # Advance phase (free drift)
+                freq = 0.1 + hash(nid) % 10 * 0.01  # natural frequency per node
+                self._phases[nid] = (self._phases.get(nid, 0.0) + freq) % (2 * math.pi)
+
+            # Fired nodes get amplitude boost (Hebbian — what fires grows)
+            for nid in result['fired_nodes']:
+                a = self._amplitudes.get(nid, 0.5)
+                self._amplitudes[nid] = min(1.0, a + self._amplitude_coupling)
+
+            # Update stats from live graph
+            self.stats['steps'] = self._step_count
+            self.stats['nodes'] = len(self._graph.nodes)
+            self.stats['synapses'] = len(self._graph.synapses)
+            self.stats['hyperedges'] = len(self._graph.hyperedges)
+            self.stats['fired_nodes'] = len(result['fired_nodes'])
+            self.stats['fired_hyperedges'] = len(result['fired_hyperedges'])
+            self.stats['predictions_confirmed'] = result['predictions_confirmed']
+            self.stats['predictions_surprised'] = result['predictions_surprised']
+
+            # Amplitude stats
+            if self._amplitudes:
+                amps = list(self._amplitudes.values())
+                self.stats['avg_amplitude'] = round(sum(amps) / len(amps), 4)
+                self.stats['max_amplitude'] = round(max(amps), 4)
+                self.stats['min_amplitude'] = round(min(amps), 4)
+
+            return result
+        except Exception as exc:
+            logger.debug("Step failed: %s", exc)
+            return {}
+
+    def kiss_extract(self, step_result: Dict) -> Dict[str, Any]:
+        """KISS bucket — extract from the River what changed.
+
+        Reads the StepResult. Decides: did anything meaningful happen?
+        If nothing fired, nothing changed, predictions confirmed = skip.
+        If novel activity = pass.
+
+        This is KISS reading the substrate, not computing its own metrics.
+
+        Returns:
+            'action': 'skip' | 'pass'
+            'reason': why
+            'novel_nodes': count of fired nodes
+            'novel_hyperedges': count of fired hyperedges
+            'surprise_ratio': how much the substrate was surprised
+        """
+        if not step_result:
+            return {'action': 'skip', 'reason': 'no_step_result'}
+
+        fired_n = len(step_result.get('fired_nodes', []))
+        fired_he = len(step_result.get('fired_hyperedges', []))
+        confirmed = step_result.get('predictions_confirmed', 0)
+        surprised = step_result.get('predictions_surprised', 0)
+        pruned = step_result.get('synapses_pruned', 0)
+        sprouted = step_result.get('synapses_sprouted', 0)
+
+        # Nothing happened — skip
+        if fired_n == 0 and fired_he == 0 and pruned == 0 and sprouted == 0:
+            self.stats['kiss_skips'] += 1
+            return {
+                'action': 'skip',
+                'reason': 'substrate_quiet',
+                'novel_nodes': 0,
+                'novel_hyperedges': 0,
+                'surprise_ratio': 0.0,
+            }
+
+        # Surprise ratio — how much was unexpected
+        total_predictions = confirmed + surprised
+        surprise_ratio = surprised / total_predictions if total_predictions > 0 else 0.5
+
+        # Everything was predicted, nothing novel — sparse pass at best
+        if surprise_ratio == 0 and sprouted == 0:
+            self.stats['kiss_skips'] += 1
+            return {
+                'action': 'skip',
+                'reason': 'all_predicted',
+                'novel_nodes': fired_n,
+                'novel_hyperedges': fired_he,
+                'surprise_ratio': 0.0,
+            }
+
+        # Something novel happened — pass
+        self.stats['kiss_passes'] += 1
+        return {
+            'action': 'pass',
+            'reason': 'novel_activity',
+            'novel_nodes': fired_n,
+            'novel_hyperedges': fired_he,
+            'surprise_ratio': round(surprise_ratio, 4),
+            'structural_changes': pruned + sprouted,
+        }
+
+    def pith_extract(self, query: str, max_context: int = 10) -> List[str]:
+        """Pith bucket — Born rule extraction from the River.
+
+        Each node has an amplitude. The query modulates amplitudes through
+        interference — similar nodes constructively interfere (amplified),
+        dissimilar destructively (suppressed). Born rule (amplitude²)
+        determines each node's probability of appearing in context.
+
+        No thresholds. No top-K. The physics decides.
+
+        Also uses spreading activation to boost topology-connected nodes.
+        Combined score: Born rule (amplitude²) × topology boost.
+        """
+        if self._graph is None:
+            return []
+
+        try:
+            import math
+            query_embedding = self._embed_fn(query)
+
+            # Compute per-node Born rule score.
+            # The query interferes with each node's amplitude:
+            # similarity modulates the interference direction,
+            # existing amplitude is the base strength.
+            scored = []
+
+            for nid, node in self._graph.nodes.items():
+                emb = node.metadata.get('embedding') if node.metadata else None
+                if emb is None:
+                    continue
+
+                node_emb = np.array(emb, dtype=np.float32)
+                sim = float(np.dot(query_embedding, node_emb) /
+                            (np.linalg.norm(query_embedding) * np.linalg.norm(node_emb) + 1e-8))
+
+                # Current amplitude and phase
+                amp = self._amplitudes.get(nid, 0.5)
+                phase = self._phases.get(nid, 0.0)
+
+                # Query gets its own phase from embedding hash
+                query_phase = float(hash(query) % 628) / 100.0
+
+                # Interference: amplitude × cosine(phase difference) × similarity
+                interference = amp * math.cos(phase - query_phase) * sim
+
+                # Effective amplitude after query interference
+                effective_amp = max(0.0, min(1.0, amp + self._interference_rate * interference))
+
+                # Born rule: probability ∝ amplitude²
+                born_score = effective_amp * effective_amp
+
+                content = self._node_content.get(nid, '')
+                if content and born_score > 0.001:
+                    scored.append((nid, content, born_score))
+
+            if not scored:
+                return []
+
+            # Topology boost: spread activation from highest-Born nodes
+            # and boost whatever the topology connects to them
+            scored.sort(key=lambda x: x[2], reverse=True)
+            top_ids = [nid for nid, _, _ in scored[:3]]
+
+            if top_ids:
+                try:
+                    prop_result = self._graph.prime_and_propagate(
+                        node_ids=top_ids,
+                        currents=[10.0] * len(top_ids),
+                        steps=5,
+                        write_mode=False,
+                    )
+                    fired_entries = getattr(prop_result, 'fired_entries', []) if prop_result else []
+                    topology_fired = {e.node_id for e in fired_entries}
+
+                    # Boost scored nodes that topology also reached
+                    for i, (nid, content, born) in enumerate(scored):
+                        if nid in topology_fired:
+                            scored[i] = (nid, content, born * 1.5)  # topology boost
+                except Exception:
+                    pass  # propagation failure is non-fatal
+
+            # Final sort by Born score, take max_context
+            scored.sort(key=lambda x: x[2], reverse=True)
+            contexts = [content for _, content, _ in scored[:max_context]]
+
+            self.stats['pith_l1_size'] = len(contexts)
+            self.stats['pith_promotions'] += len(contexts)
+
+            return contexts
+        except Exception as exc:
+            logger.debug("Pith extract failed: %s", exc)
+            return []
+
+    def record_outcome(self, user_message: str, response: str, success: bool = True):
+        """Close the loop — outcome feeds back into substrate.
+
+        The response is raw experience (Law 7). The success/failure
+        is the outcome signal for Hebbian learning. The substrate
+        learns which associations led to good outcomes.
+        """
+        if self._graph is None:
+            return
+
+        try:
+            # Response as raw experience — create node, stimulate, reward
+            response_embedding = self._embed_fn(response)
+            node_id = f"resp_{self._step_count}_{hash(response) & 0xFFFF:04x}"
+
+            node = self._graph.create_node(
+                node_id=node_id,
+                metadata={
+                    "content": response[:200],
+                    "type": "response",
+                    "step": self._step_count,
+                    "query": user_message[:100],
+                },
+            )
+            node.metadata['embedding'] = response_embedding.tolist()
+
+            self._graph.stimulate(node_id, current=1.0)
+            self._node_content[node_id] = response[:200]
+
+            # Reward signal — the outcome closes the loop
+            # Strong reward strengthens synapses between co-firing nodes via STDP.
+            # Multiple reward injections + steps to really drive the learning.
+            reward = 2.0 if success else -1.0
+            for _ in range(3):
+                self._graph.inject_reward(strength=reward)
+                self._graph.step()
+
+            # Persist — the organism remembers across restarts
+            self.save()
+
+        except Exception as exc:
+            logger.debug("Outcome recording failed: %s", exc)
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get organism stats for display."""
+        return dict(self.stats)
+
+    def save(self):
+        """Persist all state — single file, local + hub.
+
+        One consolidated state dict. Saved locally for warm restart.
+        Pushed to HF hub for survival across rebuilds.
+        """
+        import torch
+
+        # Build consolidated state
+        state = {
+            'node_content': self._node_content,
+            'stats': dict(self.stats),
+            'amplitudes': self._amplitudes,
+            'phases': self._phases,
+        }
+
+        # Graph checkpoint — read as raw JSON string
+        if self._graph:
+            try:
+                tmp = os.path.join(self._state_path, "_tmp_save.ckpt")
+                self._graph.checkpoint(tmp)
+                with open(tmp, 'r') as f:
+                    state['graph_checkpoint_json'] = f.read()
+                os.remove(tmp)
+            except Exception as exc:
+                logger.debug("Graph checkpoint failed: %s", exc)
+
+        # Save locally
+        try:
+            torch.save(state, self._local_state_path)
+        except Exception as exc:
+            logger.debug("Local save failed: %s", exc)
+
+        # Push to hub — survives everything
+        self._push_to_hub()
+
+    def _push_to_hub(self):
+        """Push local state file to HF dataset repo."""
+        if not self._hf_token or not os.path.exists(self._local_state_path):
+            return
+        try:
+            from huggingface_hub import HfApi, create_repo
+            # Ensure repo exists
+            create_repo(self.HUB_REPO, repo_type="dataset", exist_ok=True,
+                       private=True, token=self._hf_token)
+            api = HfApi()
+            api.upload_file(
+                path_or_fileobj=self._local_state_path,
+                path_in_repo=self.HUB_FILENAME,
+                repo_id=self.HUB_REPO,
+                repo_type="dataset",
+                token=self._hf_token,
+            )
+            logger.info("State pushed to hub (%s)", self.HUB_REPO)
+        except Exception as exc:
+            logger.debug("Hub push failed (non-fatal): %s", exc)

nuwave/pith/__init__.py

@@ -0,0 +1,2 @@
+"""Pith — The Living Context Lens. NuWave extraction layer."""
+from nuwave.pith.pipeline import PithPipeline, PithConfig

nuwave/pith/pipeline.py

@@ -0,0 +1,300 @@
+"""
+Pith Pipeline — Context Extraction Optimization
+
+Manages the model's context window as a three-tier cache hierarchy.
+Stages 1 (Clutter Strip) and 5 (Thermal Eviction) for MVP.
+
+The pipeline IS the extraction bucket. It determines what the model
+sees when it reads from the substrate. KISS decides what goes IN.
+Pith decides what comes OUT.
+
+# ---- Changelog ----
+# [2026-03-28] Claude Code (Opus 4.6) — Standalone NuWave MVP
+#   What: Pith stages 1+5 for HuggingFace deployment
+#   Why:  Minimum viable extraction — clutter strip + thermal eviction
+#   How:  Track what's in context, strip redundancy, evict by recency/relevance
+# -------------------
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+logger = logging.getLogger("nuwave.pith")
+
+
+@dataclass
+class PithConfig:
+    """Pith pipeline configuration."""
+    # L1 capacity — max context entries actively managed
+    l1_max_entries: int = 20
+
+    # Thermal decay — entries lose heat over time
+    decay_rate: float = 0.95  # per turn
+
+    # Eviction threshold — below this, entry is cold enough to evict
+    eviction_threshold: float = 0.1
+
+    # Victim cache size — recently evicted, fast recovery
+    victim_cache_size: int = 5
+
+    # Clutter: similarity threshold for considering content redundant
+    clutter_similarity: float = 0.8
+
+
+@dataclass
+class ContextEntry:
+    """A managed piece of context in the cache hierarchy."""
+    content: str
+    content_hash: str
+    heat: float = 1.0  # thermal state — 1.0 = hot, decays toward 0
+    created_at: float = 0.0
+    last_accessed: float = 0.0
+    access_count: int = 0
+    pinned: bool = False  # constitutional — cannot be evicted
+
+    def warm(self):
+        """Re-warm this entry — it was accessed."""
+        self.heat = min(1.0, self.heat + 0.3)
+        self.last_accessed = time.time()
+        self.access_count += 1
+
+    def cool(self, rate: float):
+        """Apply thermal decay."""
+        if not self.pinned:
+            self.heat *= rate
+
+
+@dataclass
+class PithStats:
+    """Running statistics for Pith pipeline."""
+    total_extractions: int = 0
+    clutter_stripped: int = 0
+    entries_evicted: int = 0
+    victim_recoveries: int = 0
+    l1_current_size: int = 0
+    l1_avg_heat: float = 0.0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "total_extractions": self.total_extractions,
+            "clutter_stripped": self.clutter_stripped,
+            "entries_evicted": self.entries_evicted,
+            "victim_recoveries": self.victim_recoveries,
+            "l1_current_size": self.l1_current_size,
+            "l1_avg_heat": round(self.l1_avg_heat, 4),
+        }
+
+
+class PithPipeline:
+    """Context extraction pipeline — the model's cache hierarchy.
+
+    Manages what the model sees in its system prompt / context window.
+    Three tiers:
+        L1: Active context — hot, immediately available
+        L2: Warm context — staged, promotable (future)
+        Victim cache: Recently evicted — fast recovery
+
+    MVP implements Stage 1 (Clutter Strip) and Stage 5 (Thermal Eviction).
+    """
+
+    def __init__(self, config: PithConfig = None):
+        self._config = config or PithConfig()
+        self._l1: List[ContextEntry] = []
+        self._victim_cache: List[ContextEntry] = []
+        self._content_seen: Dict[str, int] = {}  # hash → count
+        self.stats = PithStats()
+
+    def extract(
+        self,
+        candidate_context: List[str],
+        query: str = "",
+    ) -> List[str]:
+        """Extract optimized context from candidates.
+
+        Stage 1: Strip clutter — remove what's already in L1
+        Stage 5: Thermal eviction — remove cold entries, recover from victim cache
+
+        Args:
+            candidate_context: New context chunks to consider adding
+            query: Current user query (for relevance scoring)
+
+        Returns:
+            Optimized context list for the model's system prompt
+        """
+        self.stats.total_extractions += 1
+
+        # Apply thermal decay to all L1 entries
+        for entry in self._l1:
+            entry.cool(self._config.decay_rate)
+
+        # Stage 1: Clutter Strip
+        novel = self._clutter_strip(candidate_context)
+
+        # Add novel content to L1
+        now = time.time()
+        for content in novel:
+            entry = ContextEntry(
+                content=content,
+                content_hash=self._hash(content),
+                heat=1.0,
+                created_at=now,
+                last_accessed=now,
+                access_count=1,
+            )
+            self._l1.append(entry)
+
+        # Check victim cache — anything relevant to current query?
+        if query:
+            self._sweep_victim_cache(query)
+
+        # Warm entries that match current query
+        if query:
+            query_words = set(query.lower().split())
+            for entry in self._l1:
+                entry_words = set(entry.content.lower().split())
+                overlap = len(query_words & entry_words) / max(len(query_words), 1)
+                if overlap > 0.3:
+                    entry.warm()
+
+        # Stage 5: Thermal Eviction
+        self._thermal_eviction()
+
+        # Update stats
+        self.stats.l1_current_size = len(self._l1)
+        if self._l1:
+            self.stats.l1_avg_heat = sum(e.heat for e in self._l1) / len(self._l1)
+
+        # Return L1 contents ordered by heat (hottest first)
+        sorted_l1 = sorted(self._l1, key=lambda e: e.heat, reverse=True)
+        return [e.content for e in sorted_l1]
+
+    def _clutter_strip(self, candidates: List[str]) -> List[str]:
+        """Stage 1: Remove content that's already in L1.
+
+        Borrowed from radar clutter filtering — subtract what's already
+        integrated from what's incoming. Only genuine novelty passes.
+        """
+        novel = []
+        existing_hashes = {e.content_hash for e in self._l1}
+        existing_hashes.update(e.content_hash for e in self._victim_cache)
+
+        for content in candidates:
+            h = self._hash(content)
+            if h in existing_hashes:
+                # Already have this — strip it
+                self.stats.clutter_stripped += 1
+                # Warm the existing entry instead
+                for entry in self._l1:
+                    if entry.content_hash == h:
+                        entry.warm()
+                        break
+                continue
+
+            # Check word-level similarity against existing entries
+            if self._is_too_similar(content):
+                self.stats.clutter_stripped += 1
+                continue
+
+            novel.append(content)
+            self._content_seen[h] = self._content_seen.get(h, 0) + 1
+
+        return novel
+
+    def _is_too_similar(self, content: str) -> bool:
+        """Check if content is too similar to existing L1 entries."""
+        content_words = set(content.lower().split())
+        if not content_words:
+            return True
+
+        for entry in self._l1:
+            entry_words = set(entry.content.lower().split())
+            if not entry_words:
+                continue
+            overlap = len(content_words & entry_words)
+            similarity = overlap / max(len(content_words), len(entry_words))
+            if similarity > self._config.clutter_similarity:
+                return True
+
+        return False
+
+    def _thermal_eviction(self):
+        """Stage 5: Evict cold entries, move to victim cache."""
+        surviving = []
+        for entry in self._l1:
+            if entry.pinned:
+                surviving.append(entry)
+                continue
+
+            if entry.heat < self._config.eviction_threshold:
+                # Evict to victim cache
+                self._victim_cache.append(entry)
+                self.stats.entries_evicted += 1
+            else:
+                surviving.append(entry)
+
+        # Enforce L1 capacity — evict coldest if over limit
+        if len(surviving) > self._config.l1_max_entries:
+            surviving.sort(key=lambda e: (e.pinned, e.heat), reverse=True)
+            overflow = surviving[self._config.l1_max_entries:]
+            surviving = surviving[:self._config.l1_max_entries]
+            for entry in overflow:
+                if not entry.pinned:
+                    self._victim_cache.append(entry)
+                    self.stats.entries_evicted += 1
+
+        self._l1 = surviving
+
+        # Trim victim cache
+        if len(self._victim_cache) > self._config.victim_cache_size:
+            self._victim_cache = self._victim_cache[-self._config.victim_cache_size:]
+
+    def _sweep_victim_cache(self, query: str):
+        """Sweep victim cache — recover entries relevant to current query."""
+        if not self._victim_cache:
+            return
+
+        query_words = set(query.lower().split())
+        recovered = []
+        remaining = []
+
+        for entry in self._victim_cache:
+            entry_words = set(entry.content.lower().split())
+            overlap = len(query_words & entry_words) / max(len(query_words), 1)
+            if overlap > 0.3:
+                entry.warm()
+                recovered.append(entry)
+                self.stats.victim_recoveries += 1
+            else:
+                remaining.append(entry)
+
+        self._victim_cache = remaining
+        self._l1.extend(recovered)
+
+    def pin(self, content: str):
+        """Pin content — constitutional, cannot be evicted."""
+        h = self._hash(content)
+        for entry in self._l1:
+            if entry.content_hash == h:
+                entry.pinned = True
+                return
+
+        # Not in L1 — add it pinned
+        entry = ContextEntry(
+            content=content,
+            content_hash=h,
+            heat=1.0,
+            created_at=time.time(),
+            last_accessed=time.time(),
+            access_count=1,
+            pinned=True,
+        )
+        self._l1.append(entry)
+
+    @staticmethod
+    def _hash(content: str) -> str:
+        return hashlib.sha256(content.encode()).hexdigest()[:16]

nuwave/splat_engine.py

@@ -0,0 +1,429 @@
+"""
+Gaussian Splat Weight Decomposition Engine
+==========================================
+Decomposes dense weight matrices into collections of Gaussian splats.
+Each splat has: position (mu), spread (sigma), amplitude (alpha).
+
+The splats ARE the weight representation. Inference runs through them,
+not through the original dense matrix. This is physics-based compression:
+resolution concentrates where the weight landscape has structure.
+
+For BitNet ternary weights {-1, 0, 1}, splats fit naturally:
+- Positive splats over +1 clusters
+- Negative splats over -1 clusters
+- Zero regions need no splats (free compression)
+
+# ---- Changelog ----
+# [2026-04-05] Claude Code (Opus 4.6) — Initial implementation
+#   What: Gaussian splat decomposition + reconstruction + fitting
+#   Why:  PoC for physics-based weight compression with Lenia dynamics
+# -------------------
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Tuple
+
+import torch
+import torch.nn as nn
+import numpy as np
+
+logger = logging.getLogger("uniai.splat")
+
+
+@dataclass
+class SplatConfig:
+    """Configuration for splat decomposition."""
+
+    # How many splats per matrix element (compression ratio control)
+    # e.g., 0.1 means 10x compression (10% as many splats as weight elements)
+    splat_ratio: float = 0.1
+
+    # Minimum splats per layer (don't go below this)
+    min_splats: int = 32
+
+    # Maximum splats per layer (memory safety)
+    max_splats: int = 8192
+
+    # Initial sigma for splats (spread)
+    init_sigma: float = 1.0
+
+    # Fitting iterations (gradient descent to fit splats to dense weights)
+    fit_iterations: int = 200
+
+    # Fitting learning rate
+    fit_lr: float = 0.01
+
+    # Reconstruction tolerance (stop early if below this MSE)
+    fit_tolerance: float = 1e-4
+
+
+class GaussianSplats:
+    """
+    A collection of Gaussian splats representing a weight matrix.
+
+    Each splat i has:
+      - mu_i:    (2,) position in weight space (row, col)
+      - sigma_i: (1,) spread (isotropic for Phase 0)
+      - alpha_i: (1,) amplitude (positive or negative)
+
+    The reconstructed weight at position (r, c) is:
+      W(r,c) = sum_i alpha_i * exp(-||[r,c] - mu_i||^2 / (2 * sigma_i^2))
+    """
+
+    def __init__(self, n_splats: int, rows: int, cols: int, device: torch.device = None):
+        self.n_splats = n_splats
+        self.rows = rows
+        self.cols = cols
+        self.device = device or torch.device('cpu')
+
+        # Splat parameters — these are what Lenia will operate on
+        self.mu = torch.zeros(n_splats, 2, device=self.device)       # positions
+        self.sigma = torch.ones(n_splats, device=self.device)        # spreads
+        self.alpha = torch.zeros(n_splats, device=self.device)       # amplitudes
+
+    def reconstruct(self, chunk_size: int = 512) -> torch.Tensor:
+        """Reconstruct the dense weight matrix from splats.
+
+        W(r,c) = sum_i alpha_i * exp(-||[r,c] - mu_i||^2 / (2 * sigma_i^2))
+
+        Uses chunked computation to avoid OOM on large matrices.
+        """
+        W = torch.zeros(self.rows, self.cols, device=self.device)
+
+        # Create coordinate grid
+        row_coords = torch.arange(self.rows, dtype=torch.float32, device=self.device)
+        col_coords = torch.arange(self.cols, dtype=torch.float32, device=self.device)
+
+        # Process splats in chunks to manage memory
+        for start in range(0, self.n_splats, chunk_size):
+            end = min(start + chunk_size, self.n_splats)
+            chunk_mu = self.mu[start:end]          # (chunk, 2)
+            chunk_sigma = self.sigma[start:end]    # (chunk,)
+            chunk_alpha = self.alpha[start:end]    # (chunk,)
+
+            # For each splat in chunk, compute contribution to all positions
+            for i in range(end - start):
+                mu_r, mu_c = chunk_mu[i, 0], chunk_mu[i, 1]
+                s = chunk_sigma[i]
+                a = chunk_alpha[i]
+
+                # Compute distances (separable Gaussian for speed)
+                dr = (row_coords - mu_r) ** 2
+                dc = (col_coords - mu_c) ** 2
+
+                # Outer product gives full distance grid
+                dist_sq = dr.unsqueeze(1) + dc.unsqueeze(0)  # (rows, cols)
+
+                # Gaussian contribution
+                W += a * torch.exp(-dist_sq / (2 * s ** 2 + 1e-8))
+
+        return W
+
+    def reconstruct_fast(self) -> torch.Tensor:
+        """Vectorized reconstruction — faster but uses more memory.
+
+        Good for small-to-medium matrices. Falls back to chunked for large ones.
+        """
+        if self.rows * self.cols * self.n_splats > 50_000_000:
+            return self.reconstruct()
+
+        # All positions as (rows*cols, 2) grid
+        row_coords = torch.arange(self.rows, dtype=torch.float32, device=self.device)
+        col_coords = torch.arange(self.cols, dtype=torch.float32, device=self.device)
+        rr, cc = torch.meshgrid(row_coords, col_coords, indexing='ij')
+        positions = torch.stack([rr.flatten(), cc.flatten()], dim=1)  # (R*C, 2)
+
+        # Distances from every position to every splat
+        # positions: (R*C, 2), mu: (N, 2)
+        diff = positions.unsqueeze(1) - self.mu.unsqueeze(0)  # (R*C, N, 2)
+        dist_sq = (diff ** 2).sum(dim=2)  # (R*C, N)
+
+        # Gaussian values
+        var = 2 * self.sigma.unsqueeze(0) ** 2 + 1e-8  # (1, N)
+        gaussians = torch.exp(-dist_sq / var)  # (R*C, N)
+
+        # Weighted sum
+        W_flat = (gaussians * self.alpha.unsqueeze(0)).sum(dim=1)  # (R*C,)
+
+        return W_flat.reshape(self.rows, self.cols)
+
+    def memory_bytes(self) -> int:
+        """Estimate memory usage of splat representation."""
+        # mu: n*2*4, sigma: n*4, alpha: n*4 = n*16 bytes (float32)
+        return self.n_splats * 16
+
+    def compression_ratio(self) -> float:
+        """Compression ratio vs dense float32 matrix."""
+        dense_bytes = self.rows * self.cols * 4  # float32
+        return dense_bytes / max(self.memory_bytes(), 1)
+
+    def state_dict(self) -> Dict[str, torch.Tensor]:
+        """Export splat parameters for persistence."""
+        return {
+            'mu': self.mu.clone(),
+            'sigma': self.sigma.clone(),
+            'alpha': self.alpha.clone(),
+            'rows': torch.tensor(self.rows),
+            'cols': torch.tensor(self.cols),
+        }
+
+    @classmethod
+    def from_state_dict(cls, d: Dict[str, torch.Tensor]) -> 'GaussianSplats':
+        """Restore from saved state."""
+        rows, cols = d['rows'].item(), d['cols'].item()
+        n = d['mu'].shape[0]
+        splats = cls(n, rows, cols)
+        splats.mu = d['mu']
+        splats.sigma = d['sigma']
+        splats.alpha = d['alpha']
+        return splats
+
+
+def compute_n_splats(rows: int, cols: int, config: SplatConfig) -> int:
+    """Determine how many splats to use for a given matrix size."""
+    n = int(rows * cols * config.splat_ratio)
+    return max(config.min_splats, min(n, config.max_splats))
+
+
+def initialize_splats_from_ternary(
+    weight: torch.Tensor,
+    n_splats: int,
+    config: SplatConfig,
+) -> GaussianSplats:
+    """Initialize splats from a ternary {-1, 0, 1} weight matrix.
+
+    Strategy: place splats at the centers of non-zero weight clusters.
+    For ternary weights this is efficient — zeros need no representation.
+
+    1. Find all non-zero positions
+    2. Sample n_splats positions from them (weighted by absolute value)
+    3. Set alpha to the weight value at that position
+    4. Set sigma to initial spread
+    """
+    rows, cols = weight.shape
+    splats = GaussianSplats(n_splats, rows, cols, device=weight.device)
+
+    # Find non-zero positions
+    nonzero_mask = weight != 0
+    nonzero_positions = nonzero_mask.nonzero(as_tuple=False).float()  # (K, 2)
+
+    if len(nonzero_positions) == 0:
+        # All zeros — return empty splats
+        return splats
+
+    if len(nonzero_positions) <= n_splats:
+        # Fewer non-zero elements than splats — use them all
+        k = len(nonzero_positions)
+        splats.mu[:k] = nonzero_positions
+        for i in range(k):
+            r, c = int(nonzero_positions[i, 0]), int(nonzero_positions[i, 1])
+            splats.alpha[i] = weight[r, c]
+        splats.sigma[:] = config.init_sigma
+        return splats
+
+    # Sample positions — prefer dense regions
+    # Use farthest-point sampling for coverage
+    indices = _farthest_point_sample(nonzero_positions, n_splats)
+    sampled_positions = nonzero_positions[indices]
+
+    splats.mu = sampled_positions.clone()
+
+    # Set alpha based on local weight values
+    for i in range(n_splats):
+        r, c = int(sampled_positions[i, 0]), int(sampled_positions[i, 1])
+        splats.alpha[i] = weight[r, c]
+
+    splats.sigma[:] = config.init_sigma
+
+    return splats
+
+
+def _farthest_point_sample(points: torch.Tensor, n: int) -> torch.Tensor:
+    """Spatial coverage sampling.
+
+    For small point sets (< 5000): true farthest-point sampling.
+    For large point sets: stratified random sampling (grid-based) for speed.
+    """
+    K = len(points)
+
+    if K <= 5000:
+        # True FPS — O(n*K), fine for small sets
+        selected = torch.zeros(n, dtype=torch.long, device=points.device)
+        selected[0] = torch.randint(K, (1,)).item()
+        dists = torch.full((K,), float('inf'), device=points.device)
+
+        for i in range(1, n):
+            last = points[selected[i - 1]].unsqueeze(0)
+            new_dists = ((points - last) ** 2).sum(dim=1)
+            dists = torch.minimum(dists, new_dists)
+            selected[i] = dists.argmax()
+
+        return selected
+
+    # Stratified random: divide space into grid, sample from each cell
+    # Gives good coverage without O(n*K) cost
+    perm = torch.randperm(K, device=points.device)[:n]
+    return perm
+
+
+def _reconstruct_for_fitting(mu, sigma, alpha, rows, cols, row_chunk=64):
+    """Memory-efficient reconstruction with gradients.
+
+    Processes rows in chunks to avoid building the full (R*C, N) tensor.
+    Each chunk computes its contribution independently, so gradient memory
+    stays bounded regardless of matrix size.
+    """
+    row_coords = torch.arange(rows, dtype=torch.float32)
+    col_coords = torch.arange(cols, dtype=torch.float32)
+
+    chunks = []
+    for r_start in range(0, rows, row_chunk):
+        r_end = min(r_start + row_chunk, rows)
+        chunk_rows = row_coords[r_start:r_end]  # (chunk,)
+
+        # Distance from each position in this row chunk to each splat
+        dr = (chunk_rows.unsqueeze(1) - mu[:, 0].unsqueeze(0)) ** 2  # (chunk, N)
+        dc_all = (col_coords.unsqueeze(1) - mu[:, 1].unsqueeze(0)) ** 2  # (cols, N)
+
+        # For each row in chunk, compute full col contribution
+        var = 2 * sigma.unsqueeze(0) ** 2 + 1e-8  # (1, N)
+        row_results = []
+        for ri in range(len(chunk_rows)):
+            dist_sq = dr[ri:ri+1, :] + dc_all  # (cols, N) — broadcast row dist
+            gaussians = torch.exp(-dist_sq / var)  # (cols, N)
+            row_vals = (gaussians * alpha.unsqueeze(0)).sum(dim=1)  # (cols,)
+            row_results.append(row_vals)
+        chunks.append(torch.stack(row_results))  # (chunk, cols)
+
+    return torch.cat(chunks, dim=0)  # (rows, cols)
+
+
+def fit_splats(
+    splats: GaussianSplats,
+    target: torch.Tensor,
+    config: SplatConfig,
+    verbose: bool = False,
+) -> Dict[str, float]:
+    """Fit splat parameters to reconstruct the target weight matrix.
+
+    Uses gradient descent on (mu, sigma, alpha) to minimize
+    reconstruction error. Row-chunked reconstruction keeps memory
+    bounded on low-RAM machines.
+
+    Returns metrics about the fitting process.
+    """
+    # Make parameters require grad for fitting
+    splats.mu = splats.mu.detach().requires_grad_(True)
+    splats.sigma = splats.sigma.detach().requires_grad_(True)
+    splats.alpha = splats.alpha.detach().requires_grad_(True)
+
+    optimizer = torch.optim.Adam([splats.mu, splats.sigma, splats.alpha], lr=config.fit_lr)
+
+    # Choose chunk size based on splat count to stay under ~200MB gradient memory
+    mem_per_row = splats.n_splats * splats.cols * 4 * 3  # float32 * (fwd + grad + optimizer)
+    row_chunk = max(4, min(64, int(200_000_000 / (mem_per_row + 1))))
+
+    start = time.time()
+    initial_mse = None
+    final_mse = None
+
+    for step in range(config.fit_iterations):
+        optimizer.zero_grad()
+
+        # Memory-efficient chunked reconstruction
+        reconstructed = _reconstruct_for_fitting(
+            splats.mu, splats.sigma, splats.alpha,
+            splats.rows, splats.cols, row_chunk=row_chunk,
+        )
+
+        # MSE loss
+        loss = ((reconstructed - target) ** 2).mean()
+
+        if step == 0:
+            initial_mse = loss.item()
+        final_mse = loss.item()
+
+        if step % 50 == 0:
+            print(f"    fit step {step}: MSE={loss.item():.6f}", flush=True)
+
+        if loss.item() < config.fit_tolerance:
+            print(f"    converged at step {step}", flush=True)
+            break
+
+        loss.backward()
+        optimizer.step()
+
+        # Keep sigma positive
+        with torch.no_grad():
+            splats.sigma.clamp_(min=0.1)
+            # Keep mu in bounds
+            splats.mu[:, 0].clamp_(0, splats.rows - 1)
+            splats.mu[:, 1].clamp_(0, splats.cols - 1)
+
+    # Detach after fitting
+    splats.mu = splats.mu.detach()
+    splats.sigma = splats.sigma.detach()
+    splats.alpha = splats.alpha.detach()
+
+    elapsed = time.time() - start
+
+    return {
+        'initial_mse': initial_mse,
+        'final_mse': final_mse,
+        'improvement': (initial_mse - final_mse) / (initial_mse + 1e-8),
+        'fit_time_s': elapsed,
+        'steps': step + 1,
+    }
+
+
+def decompose_layer(
+    weight: torch.Tensor,
+    config: SplatConfig = None,
+    verbose: bool = False,
+) -> Tuple[GaussianSplats, Dict[str, float]]:
+    """Full pipeline: dense weight matrix -> fitted Gaussian splats.
+
+    1. Determine number of splats from compression ratio
+    2. Initialize splats (ternary-aware if applicable)
+    3. Fit splats to target via gradient descent
+    4. Return splats + metrics
+    """
+    config = config or SplatConfig()
+
+    if weight.dim() != 2:
+        weight = weight.reshape(weight.shape[0], -1)
+
+    rows, cols = weight.shape
+    n_splats = compute_n_splats(rows, cols, config)
+
+    # Detect if ternary
+    unique_vals = weight.unique()
+    is_ternary = len(unique_vals) <= 3 and all(v in [-1, 0, 1] for v in unique_vals.tolist())
+
+    if is_ternary:
+        if verbose:
+            logger.info(f"  Ternary weights detected — using cluster initialization")
+        splats = initialize_splats_from_ternary(weight, n_splats, config)
+    else:
+        # General initialization: random positions, amplitudes from weight samples
+        splats = GaussianSplats(n_splats, rows, cols, device=weight.device)
+        idx_r = torch.randint(rows, (n_splats,))
+        idx_c = torch.randint(cols, (n_splats,))
+        splats.mu = torch.stack([idx_r.float(), idx_c.float()], dim=1)
+        splats.alpha = weight[idx_r, idx_c].clone()
+        splats.sigma[:] = config.init_sigma
+
+    # Fit to target
+    fit_metrics = fit_splats(splats, weight, config, verbose=verbose)
+
+    fit_metrics['n_splats'] = n_splats
+    fit_metrics['matrix_size'] = (rows, cols)
+    fit_metrics['dense_elements'] = rows * cols
+    fit_metrics['compression_ratio'] = splats.compression_ratio()
+    fit_metrics['is_ternary'] = is_ternary
+
+    return splats, fit_metrics

nuwave/substrate/__init__.py

@@ -0,0 +1 @@
+"""NeuroGraph substrate — ng_tract (Rust/PyO3) + canonical Python."""

nuwave/substrate/ng_autonomic.py

@@ -0,0 +1,99 @@
+"""
+NG Autonomic Nervous System — Ecosystem-Wide Threat Level State
+
+VENDORED FILE. Copy verbatim into any module that participates in
+the autonomic nervous system. Do NOT modify per-module. Changes
+propagate by updating this canonical source and re-vendoring.
+
+State file: ~/.et_modules/autonomic_state.json
+
+State transitions:
+    PARASYMPATHETIC (rest/digest) -> normal operations
+    SYMPATHETIC (fight/flight) -> elevated threat, all modules adjust
+
+Canonical source: NeuroGraph/ng_autonomic.py
+License: AGPL-3.0
+
+Changelog:
+    [2026-03-03] River audit — Established UPPERCASE as canonical
+    case standard. All states and enums use UPPERCASE. No exceptions.
+    Normalizes .upper() on both read and write to prevent silent
+    mismatches with any older files or callers.
+"""
+
+import json
+import logging
+import os
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger("ng_autonomic")
+
+__version__ = "1.1.0"
+
+_STATE_PATH = Path.home() / ".et_modules" / "autonomic_state.json"
+_VALID_STATES = {"PARASYMPATHETIC", "SYMPATHETIC"}
+_VALID_THREAT_LEVELS = {"none", "low", "medium", "high", "critical"}
+
+
+def read_state() -> dict:
+    """Read current autonomic state. Fast path ~0.1ms.
+
+    Returns dict with keys: state, threat_level, triggered_by,
+    timestamp, reason. Defaults to PARASYMPATHETIC if file missing
+    or unreadable.
+    """
+    default = {
+        "state": "PARASYMPATHETIC",
+        "threat_level": "none",
+        "triggered_by": "",
+        "timestamp": 0.0,
+        "reason": "default — no security module has written state",
+    }
+    if not _STATE_PATH.exists():
+        return default
+    try:
+        with open(_STATE_PATH, "r") as f:
+            data = json.load(f)
+        raw_state = data.get("state", "PARASYMPATHETIC").upper()
+        if raw_state not in _VALID_STATES:
+            raw_state = "PARASYMPATHETIC"
+        data["state"] = raw_state
+        return data
+    except (json.JSONDecodeError, OSError):
+        return default
+
+
+def write_state(
+    state: str,
+    threat_level: str,
+    triggered_by: str,
+    reason: str,
+) -> None:
+    """Write autonomic state. Only security modules should call this.
+
+    Args:
+        state: PARASYMPATHETIC or SYMPATHETIC (uppercase enforced)
+        threat_level: none | low | medium | high | critical
+        triggered_by: module_id of the calling module
+        reason: human-readable reason for the state change
+    """
+    state = state.upper()
+    if state not in _VALID_STATES:
+        raise ValueError(f"Invalid state: {state}. Must be one of {_VALID_STATES}")
+    if threat_level not in _VALID_THREAT_LEVELS:
+        raise ValueError(f"Invalid threat_level: {threat_level}. Must be one of {_VALID_THREAT_LEVELS}")
+
+    _STATE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    data = {
+        "state": state,
+        "threat_level": threat_level,
+        "triggered_by": triggered_by,
+        "timestamp": time.time(),
+        "reason": reason,
+    }
+    tmp_path = _STATE_PATH.with_suffix(".tmp")
+    with open(tmp_path, "w") as f:
+        json.dump(data, f, indent=2)
+    os.replace(tmp_path, _STATE_PATH)

nuwave/substrate/ng_ecosystem.py

@@ -0,0 +1,598 @@
+"""
+NG Ecosystem — E-T Systems Module Integration Standard
+
+Single vendorable file that gives any E-T Systems module the full
+three-tier learning architecture:
+
+  Tier 1 (Standalone):  NGLite alone.  Local Hebbian learning.
+                        Zero deps beyond ng_lite.py.
+  Tier 2 (Peer-pooled): NGTractBridge (preferred) or NGPeerBridge
+                        (legacy fallback).  Co-located modules share
+                        learning via per-pair tracts (~/.et_modules/tracts/)
+                        or legacy JSONL (~/.et_modules/shared_learning/).
+                        Auto-connects.  Tract bridge preferred when present.
+  Tier 3 (Full SNN):    Removed — modules extract via buckets/tracts.
+                        Auto-upgrades when NeuroGraph is detected on
+                        the same host via ETModuleManager.
+
+The ecosystem is "Apple-like" by design:
+  - Every module is independently useful at Tier 1.
+  - Any two co-located modules get a free Tier 2 boost — no config needed.
+  - When NeuroGraph is present, all co-located modules transparently
+    upgrade to Tier 3: full STDP, hyperedges, predictive coding, and
+    CES streaming.
+
+The module code doesn't change.  The bridge swaps.
+
+Usage (inside any E-T Systems module):
+
+    from ng_ecosystem import NGEcosystem
+
+    # In your module's __init__ or startup:
+    eco = NGEcosystem.get_instance(
+        module_id="trollguard",
+        state_path="~/.trollguard/ng_lite_state.json",
+    )
+
+    # Use the ecosystem in your module's hot path:
+    embedding = my_embedder(text)
+    eco.record_outcome(embedding, target_id="threat:prompt_injection", success=True)
+    recs = eco.get_recommendations(embedding)
+    novelty = eco.detect_novelty(embedding)
+    ctx = eco.get_context(embedding)
+
+    # Inspect tier at any time:
+    print(eco.tier)        # 1, 2, or 3
+    print(eco.stats())     # full telemetry
+
+    # Periodic save (call on graceful shutdown or on a timer):
+    eco.save()
+
+Framework adapters (optional, load separately):
+  - openclaw_adapter.py — on_message(text)/recall(text)/stats() for OpenClaw skills
+
+Canonical source: https://github.com/greatnorthernfishguy-hub/NeuroGraph
+License: AGPL-3.0
+
+# ---- Changelog ----
+# [2026-02-22] Claude (Sonnet 4.6) — Initial creation.
+#   What: NGEcosystem class — singleton wrapper implementing the
+#         standardized E-T Systems optional integration protocol.
+#         Handles Tier 1→2→3 progression, auto-upgrade on NeuroGraph
+#         detection, graceful degradation, and unified telemetry.
+#         Also defines NGEcosystemAdapter ABC for framework adapters.
+#   Why:  Each module was wiring ng_lite + peer bridge + SaaS bridge
+#         independently with no shared contract.  This file is the
+#         single vendorable standard so all modules behave identically
+#         from an integration perspective.
+#   Settings: tier3_upgrade defaults to True (auto-upgrade when NeuroGraph
+#         is found).  upgrade_poll_interval=300s (re-check for NeuroGraph
+#         every 5 minutes — handles cases where NeuroGraph is installed
+#         after the module starts).  peer_sync_interval=100 (balances
+#         freshness vs I/O).
+#   How:  get_instance() creates NGLite, then tries peer bridge, then
+#         queries ETModuleManager for NeuroGraph.  All in try/except so
+#         each tier attempt is fully independent.  A background thread
+#         polls for tier upgrades at upgrade_poll_interval.
+# -------------------
+# [2026-03-20] Claude (Opus 4.6) — Tract bridge wiring (punchlist #53 v0.3)
+#   What: _init_peer_bridge() now prefers NGTractBridge (per-pair tracts)
+#         with automatic fallback to NGPeerBridge (legacy JSONL).
+#   Why:  JSONL broadcast bridge dams the River.  Per-pair tracts enable
+#         independently observable pathways for myelination, explore-exploit,
+#         vagus nerve, and Elmer tract management.
+#   How:  Try importing ng_tract_bridge first.  If present (vendored),
+#         use it.  If not (module not yet re-vendored), fall back to
+#         ng_peer_bridge.  Config key peer_bridge.use_tracts (default True)
+#         can force legacy mode if needed.
+# -------------------
+# [2026-03-22] Claude (Opus 4.6) — Dual-pass convenience method (punchlist #81)
+#   What: Added dual_record_outcome() that delegates to ng_embed.NGEmbed.
+#   Why:  Dual-pass embedding (forest + trees) is ecosystem-wide.
+#         Modules call eco.dual_record_outcome() instead of eco.record_outcome()
+#         for rich content. ng_embed.py owns the extraction + embedding logic.
+#   How:  Lazy import of ng_embed to avoid circular deps. Passes self
+#         (the ecosystem instance) to NGEmbed.dual_record_outcome().
+# -------------------
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+import time
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+
+logger = logging.getLogger("ng_ecosystem")
+
+__version__ = "1.0.0"
+
+
+# --------------------------------------------------------------------------
+# Constants
+# --------------------------------------------------------------------------
+
+ET_MODULES_ROOT = Path.home() / ".et_modules"
+SHARED_LEARNING_DIR = ET_MODULES_ROOT / "shared_learning"
+REGISTRY_PATH = ET_MODULES_ROOT / "registry.json"
+
+TIER_STANDALONE = 1  # NGLite only
+TIER_PEER = 2        # + NGPeerBridge
+TIER_FULL_SNN = 3    # historical — bridge removed, modules use tracts
+
+TIER_NAMES = {
+    TIER_STANDALONE: "Standalone (Tier 1)",
+    TIER_PEER: "Peer-pooled (Tier 2)",
+    TIER_FULL_SNN: "Full SNN (Tier 3)",
+}
+
+
+# --------------------------------------------------------------------------
+# Framework Adapter Interface
+# --------------------------------------------------------------------------
+
+class NGEcosystemAdapter(ABC):
+    """Abstract base for framework-specific adapters over NGEcosystem.
+
+    Implement this to expose the ecosystem to a specific framework.
+    Each adapter is a singleton that wraps the shared NGEcosystem
+    instance — the same ecosystem, different vocabulary.
+
+    Provided implementations:
+      - OpenClawAdapter (openclaw_adapter.py, vendored separately)
+
+    Custom adapters:
+      Subclass NGEcosystemAdapter and implement all abstract methods.
+      Call NGEcosystem.get_instance() inside __init__ to bind the
+      shared ecosystem.  Maintain your own singleton if needed.
+
+    Design contract:
+      - Adapters MUST NOT bypass NGEcosystem internals.
+      - Adapters handle embedding generation; NGEcosystem handles learning.
+      - Adapters are optional and framework-specific.  The core
+        NGEcosystem is framework-agnostic and always the source of truth.
+    """
+
+    @abstractmethod
+    def on_message(self, text: str) -> Dict[str, Any]:
+        """Process one unit of framework input (message, request, event).
+
+        Args:
+            text: Raw text to process.
+
+        Returns:
+            Dict with at minimum: {"status": "ingested"|"skipped", "tier": int}
+        """
+        ...
+
+    @abstractmethod
+    def get_context(self, text: str) -> Dict[str, Any]:
+        """Retrieve cross-module context for the given text.
+
+        Args:
+            text: Query text.
+
+        Returns:
+            Dict with recommendations, novelty score, and tier info.
+        """
+        ...
+
+    @abstractmethod
+    def stats(self) -> Dict[str, Any]:
+        """Return framework-specific stats including ecosystem tier."""
+        ...
+
+
+# --------------------------------------------------------------------------
+# NGEcosystem Core
+# --------------------------------------------------------------------------
+
+class NGEcosystem:
+    """Singleton E-T Systems learning ecosystem for a module.
+
+    Manages the full Tier 1→2→3 lifecycle automatically.  Modules
+    call record_outcome(), get_recommendations(), detect_novelty(),
+    and get_context() without knowing or caring which tier is active.
+
+    Thread-safety: All public methods are safe to call from multiple
+    threads.  The tier upgrade loop runs in a daemon thread.
+    """
+
+    _instances: Dict[str, "NGEcosystem"] = {}
+    _lock = threading.Lock()
+
+    def __init__(
+        self,
+        module_id: str,
+        state_path: Optional[str] = None,
+        config: Optional[Dict[str, Any]] = None,
+    ):
+        """
+        Args:
+            module_id: Unique module identifier (e.g., "trollguard").
+                       Must match the module_id in et_module.json.
+            state_path: Path to persist NGLite state JSON.
+                        Defaults to ~/.et_modules/{module_id}/ng_lite_state.json
+            config: Optional config overrides.  Keys:
+                    peer_bridge.enabled (bool, default True)
+                    peer_bridge.sync_interval (int, default 100)
+                    tier3_upgrade.enabled (bool, default True)
+                    tier3_upgrade.poll_interval (float, default 300.0)
+                    ng_lite.* (passed through to NGLite)
+        """
+        self.module_id = module_id
+
+        self._config = {
+            "peer_bridge": {
+                "enabled": True,
+                "sync_interval": 100,
+            },
+            "tier3_upgrade": {
+                "enabled": False,  # disabled — modules use tracts, not bridge bypass
+                "poll_interval": 300.0,
+            },
+        }
+        if config:
+            _deep_merge(self._config, config)
+
+        # State persistence path
+        if state_path:
+            self._state_path = Path(state_path).expanduser()
+        else:
+            self._state_path = (
+                ET_MODULES_ROOT / module_id / "ng_lite_state.json"
+            )
+        self._state_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Internal state
+        self._tier = TIER_STANDALONE
+        self._ng: Any = None              # NGLite instance
+        self._ng_memory: Any = None       # NeuroGraphMemory ref (set externally at Tier 3)
+        self._peer_bridge: Any = None     # NGPeerBridge instance
+        self._shutdown_event = threading.Event()
+        self._ops_lock = threading.Lock()
+
+        # Boot sequence
+        self._init_ng_lite()
+        self._init_peer_bridge()
+
+        logger.info(
+            "[%s] NGEcosystem ready at %s",
+            module_id,
+            TIER_NAMES[self._tier],
+        )
+
+    # -----------------------------------------------------------------
+    # Singleton factory
+    # -----------------------------------------------------------------
+
+    @classmethod
+    def get_instance(
+        cls,
+        module_id: str,
+        state_path: Optional[str] = None,
+        config: Optional[Dict[str, Any]] = None,
+    ) -> "NGEcosystem":
+        """Return the singleton NGEcosystem for this module_id.
+
+        Thread-safe.  Subsequent calls with the same module_id return
+        the existing instance regardless of state_path/config args.
+        """
+        with cls._lock:
+            if module_id not in cls._instances:
+                cls._instances[module_id] = cls(module_id, state_path, config)
+            return cls._instances[module_id]
+
+    @classmethod
+    def reset_instance(cls, module_id: str) -> None:
+        """Destroy the singleton for module_id (testing only)."""
+        with cls._lock:
+            inst = cls._instances.pop(module_id, None)
+            if inst:
+                inst._shutdown_event.set()
+
+    # -----------------------------------------------------------------
+    # Tier 1: NGLite init
+    # -----------------------------------------------------------------
+
+    def _init_ng_lite(self) -> None:
+        """Initialize local NGLite substrate (always Tier 1)."""
+        try:
+            from ng_lite import NGLite  # vendored alongside this file
+
+            ng_config = self._config.get("ng_lite", {})
+            self._ng = NGLite(module_id=self.module_id, config=ng_config)
+
+            if self._state_path.exists():
+                self._ng.load(str(self._state_path))
+                logger.debug("[%s] NGLite state loaded from %s", self.module_id, self._state_path)
+
+        except Exception as exc:
+            logger.error("[%s] NGLite init failed: %s", self.module_id, exc)
+            self._ng = None
+
+    # -----------------------------------------------------------------
+    # Tier 2: NGPeerBridge init
+    # -----------------------------------------------------------------
+
+    def _init_peer_bridge(self) -> None:
+        """Try to connect Tier 2 bridge. Prefers tract bridge, falls back to legacy JSONL."""
+        if not self._config["peer_bridge"]["enabled"]:
+            return
+        if self._ng is None:
+            return
+
+        bridge = None
+
+        # Tract bridge (v0.3+) — per-pair directional tracts
+        if self._config["peer_bridge"].get("use_tracts", True):
+            try:
+                from ng_tract_bridge import NGTractBridge  # vendored alongside
+
+                bridge = NGTractBridge(
+                    module_id=self.module_id,
+                    tracts_dir=str(ET_MODULES_ROOT / "tracts"),
+                    sync_interval=self._config["peer_bridge"]["sync_interval"],
+                )
+                logger.info("[%s] NGTractBridge connected (tract-based River)", self.module_id)
+            except ImportError:
+                pass
+            except Exception as exc:
+                logger.debug("[%s] NGTractBridge failed: %s", self.module_id, exc)
+
+        # Legacy fallback — JSONL broadcast bridge
+        if bridge is None:
+            try:
+                from ng_peer_bridge import NGPeerBridge  # vendored alongside
+
+                bridge = NGPeerBridge(
+                    module_id=self.module_id,
+                    shared_dir=str(SHARED_LEARNING_DIR),
+                    sync_interval=self._config["peer_bridge"]["sync_interval"],
+                )
+                logger.info("[%s] NGPeerBridge connected (legacy JSONL River)", self.module_id)
+            except Exception as exc:
+                logger.debug("[%s] No peer bridge available: %s", self.module_id, exc)
+                return
+
+        self._ng.connect_bridge(bridge)
+        self._peer_bridge = bridge
+        self._tier = TIER_FULL_SNN  # tract bridge = full substrate access
+
+    # -----------------------------------------------------------------
+    # Tier 3: NeuroGraph auto-upgrade
+    # -----------------------------------------------------------------
+    @property
+    def tier(self) -> int:
+        """Current learning tier (1, 2, or 3)."""
+        return self._tier
+
+    @property
+    def tier_name(self) -> str:
+        """Human-readable tier name."""
+        return TIER_NAMES.get(self._tier, "Unknown")
+
+    def record_outcome(
+        self,
+        embedding: np.ndarray,
+        target_id: str,
+        success: bool,
+        strength: float = 1.0,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Record a learning outcome.
+
+        The embedding is the semantic representation of the input.
+        The target_id is an opaque string representing what was decided
+        (e.g., "model:llama3", "threat:prompt_injection", "action:search").
+
+        Returns the learning result dict from the substrate.
+        """
+        if self._ng is None:
+            return {}
+        with self._ops_lock:
+            return self._ng.record_outcome(
+                embedding, target_id, success, strength=strength, metadata=metadata
+            )
+
+    def dual_record_outcome(
+        self,
+        content: str,
+        embedding: np.ndarray,
+        target_id: str,
+        success: bool,
+        strength: float = 1.0,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Dual-pass learning: forest (gestalt) + tree (concept) embeddings.
+
+        Pass 1: record_outcome() with the forest embedding (standard).
+        Pass 2: Extract concepts via TID → embed each → record_outcome()
+                 per tree → create forest→tree substrate links.
+
+        Falls back to single-pass (forest only) if TID unavailable.
+
+        Args:
+            content: Raw text (for concept extraction in Pass 2).
+            embedding: Pre-computed forest embedding (Pass 1).
+            target_id: Opaque string for what was decided.
+            success: Whether the outcome was successful.
+            strength: Significance [0.0, 1.0].
+            metadata: Additional metadata dict.
+
+        Returns dict with forest_result, tree_ids, concepts, pass2_attempted.
+        """
+        from ng_embed import NGEmbed
+        return NGEmbed.get_instance().dual_record_outcome(
+            self, content, embedding, target_id, success,
+            strength=strength, metadata=metadata,
+        )
+
+    def get_recommendations(
+        self,
+        embedding: np.ndarray,
+        top_k: int = 3,
+    ) -> List[Tuple[str, float, str]]:
+        """Get recommendations from the active learning substrate.
+
+        Returns list of (target_id, confidence, reasoning).
+
+        At Tier 1, returns local recommendations only.
+        At Tier 2, includes cross-module peer patterns.
+        At Tier 3, includes full SNN recommendations + hyperedge context.
+        """
+        if self._ng is None:
+            return []
+        with self._ops_lock:
+            return self._ng.get_recommendations(embedding, top_k=top_k)
+
+    def detect_novelty(self, embedding: np.ndarray) -> float:
+        """Return novelty score [0.0=routine, 1.0=completely novel].
+
+        At Tier 2+, novelty is cross-module: something novel to this
+        module but known to a peer scores lower than it would at Tier 1.
+        """
+        if self._ng is None:
+            return 1.0  # Conservative: unknown = novel
+        with self._ops_lock:
+            result = self._ng.detect_novelty(embedding)
+            return result if result is not None else 1.0
+
+    def get_context(
+        self,
+        embedding: np.ndarray,
+        top_k: int = 3,
+    ) -> Dict[str, Any]:
+        """Unified context retrieval for prompt enrichment or decision support.
+
+        Returns a dict suitable for injecting into a prompt or logging:
+          tier:            int — current tier
+          tier_name:       str — human-readable tier
+          recommendations: list of (target_id, confidence, reasoning)
+          novelty:         float — novelty score [0.0, 1.0]
+          ng_context:      str|None — Tier 3 SNN surfaced context if available
+        """
+        recs = self.get_recommendations(embedding, top_k=top_k)
+        novelty = self.detect_novelty(embedding)
+        ng_context = None
+
+        # Tier 3: ask NeuroGraph for surfaced cognitive context
+        if self._tier == TIER_FULL_SNN and self._ng_memory is not None:
+            try:
+                ng_context = self._ng_memory.surface_context(embedding)
+            except Exception:
+                pass
+
+        return {
+            "tier": self._tier,
+            "tier_name": self.tier_name,
+            "recommendations": recs,
+            "novelty": novelty,
+            "ng_context": ng_context,
+        }
+
+    def save(self) -> None:
+        """Persist NGLite state to disk."""
+        if self._ng is None:
+            return
+        try:
+            with self._ops_lock:
+                self._ng.save(str(self._state_path))
+            logger.debug("[%s] NGLite state saved to %s", self.module_id, self._state_path)
+        except Exception as exc:
+            logger.warning("[%s] Save failed: %s", self.module_id, exc)
+
+    def stats(self) -> Dict[str, Any]:
+        """Return unified telemetry for logging, dashboards, or skill SKILL.md output."""
+        ng_stats: Dict[str, Any] = {}
+        if self._ng is not None:
+            try:
+                ng_stats = self._ng.get_stats()
+            except Exception:
+                pass
+
+        peer_stats: Dict[str, Any] = {}
+        if self._peer_bridge is not None:
+            try:
+                peer_stats = self._peer_bridge.get_stats()
+            except Exception:
+                pass
+
+        ng_memory_stats: Dict[str, Any] = {}
+        if self._ng_memory is not None:
+            try:
+                ng_memory_stats = self._ng_memory.stats()
+            except Exception:
+                pass
+
+        return {
+            "ecosystem_version": __version__,
+            "module_id": self.module_id,
+            "tier": self._tier,
+            "tier_name": self.tier_name,
+            "ng_lite": ng_stats,
+            "peer_bridge": peer_stats if peer_stats else None,
+            "ng_memory": (
+                {
+                    "connected": True,
+                    "version": ng_memory_stats.get("version", "unknown"),
+                    "nodes": ng_memory_stats.get("graph", {}).get("node_count", "?"),
+                }
+                if ng_memory_stats else None
+            ),
+            "state_path": str(self._state_path),
+        }
+
+    def shutdown(self) -> None:
+        """Graceful shutdown: save state and stop the upgrade thread."""
+        self._shutdown_event.set()
+        self.save()
+        logger.info("[%s] NGEcosystem shutdown complete", self.module_id)
+
+
+# --------------------------------------------------------------------------
+# Known NeuroGraph install paths (Tier 3 auto-detection)
+# --------------------------------------------------------------------------
+
+_NEUROGRAPH_KNOWN_PATHS: List[str] = [
+    "~/NeuroGraph",
+    "~/.openclaw/workspace/skills/neurograph",
+    "~/.et_modules/modules/neurograph",
+]
+
+
+# --------------------------------------------------------------------------
+# Internal helpers
+# --------------------------------------------------------------------------
+
+def _deep_merge(base: dict, override: dict) -> None:
+    """Recursively merge override into base in-place."""
+    for key, val in override.items():
+        if key in base and isinstance(base[key], dict) and isinstance(val, dict):
+            _deep_merge(base[key], val)
+        else:
+            base[key] = val
+
+
+# --------------------------------------------------------------------------
+# Convenience: module-level quick-start
+# --------------------------------------------------------------------------
+
+def init(
+    module_id: str,
+    state_path: Optional[str] = None,
+    config: Optional[Dict[str, Any]] = None,
+) -> NGEcosystem:
+    """One-call initialization for simple module integrations.
+
+    Example:
+        import ng_ecosystem
+        eco = ng_ecosystem.init("trollguard")
+    """
+    return NGEcosystem.get_instance(module_id, state_path, config)

nuwave/substrate/ng_embed.py

@@ -0,0 +1,626 @@
+"""
+ng_embed — Centralized embedding service for the E-T Systems ecosystem.
+
+Singleton embedding engine used by every module. Provides:
+  1. Unified embedding via Snowflake/snowflake-arctic-embed-m-v1.5 (ONNX)
+  2. Dual-pass embedding (forest + trees) via TID concept extraction
+  3. Thread-safe singleton — one model instance per process
+  4. Hash fallback when ONNX model unavailable
+
+This is a VENDORED file. Canonical source: ~/NeuroGraph/ng_embed.py
+Do NOT modify vendored copies. Changes made here, re-vendored everywhere.
+
+Model: Snowflake/snowflake-arctic-embed-m-v1.5
+  - 768-dim, CLS pooling, standard BERT architecture
+  - Query prefix: "Represent this sentence for searching relevant passages: "
+  - Documents: no prefix
+  - ONNX quantized (~110MB) via onnxruntime — no PyTorch dependency
+
+Dual-pass (Punchlist #81 — Josh's invention):
+  Pass 1 (Forest): Gestalt embedding of whole content. One node.
+  Pass 2 (Trees): LLM extracts concepts via TID. Each concept embedded
+  separately. Each tree linked to its forest via synapses. Cross-document
+  tree links form naturally through similarity association.
+
+# ---- Changelog ----
+# [2026-03-22] Claude (Opus 4.6) — Initial creation.
+#   What: Centralized embedding + dual-pass for entire ecosystem.
+#   Why:  PRD §5 (Dual_Pass_Embedding_Implementation.md). Replaces 7+
+#         identical _embed() functions. Prevents embedding dimension
+#         mismatch incidents. Upgrades model from bge-base-en-v1.5 to
+#         snowflake-arctic-embed-m-v1.5 (+1.89 retrieval MTEB).
+#   How:  ONNX Runtime + tokenizers for embedding. TID for concept
+#         extraction. Substrate-learnable gate for Pass 2 value.
+# -------------------
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import threading
+import time
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from ng_ecosystem import NGEcosystem
+
+logger = logging.getLogger("ng_embed")
+
+# ---------------------------------------------------------------------------
+# Configuration defaults — all values are bootstrap scaffolding
+# ---------------------------------------------------------------------------
+
+_DEFAULT_CONFIG = {
+    # Model
+    "model_id": "Snowflake/snowflake-arctic-embed-m-v1.5",
+    "onnx_filename": "onnx/model_quantized.onnx",
+    "embedding_dim": 768,
+    "pooling": "cls",
+    "query_prefix": "Represent this sentence for searching relevant passages: ",
+    "document_prefix": "",
+    "cache_dir": str(Path.home() / ".cache" / "ng_embed"),
+
+    # Dual-pass (Punchlist #81)
+    "tid_endpoint": "http://127.0.0.1:7437/v1/chat/completions",
+    "max_content_for_extraction": 2000,     # Chars sent to TID
+    "max_concepts": 20,                     # Cap extracted concepts
+    "forest_to_tree_weight": 0.4,           # Bootstrap synapse weight
+    "tree_to_forest_ratio": 0.7,            # tree→forest = forest_weight * ratio
+    "tid_timeout": 30,                      # Seconds
+    "tid_model": "auto",                    # TID routes to appropriate model
+    "tid_temperature": 0.2,
+    "tid_max_tokens": 500,
+}
+
+# Concept extraction prompt — not classification, not labeling.
+# The LLM reads content and identifies distinct concepts within it.
+# This is extraction at the ingestion boundary — the LLM is a tool
+# that helps the substrate receive richer raw experience (Law 7).
+_EXTRACTION_PROMPT = """Extract the key concepts, terms, and specific references from this text. Return them as a JSON array of short strings, each one a distinct concept or term mentioned in the text.
+
+Focus on:
+- Specific technical terms
+- Named entities (people, tools, systems)
+- Domain-specific concepts
+- Action descriptions
+- Relationships between things
+
+Return ONLY a JSON array of strings. No explanation. Example: ["concept one", "concept two", "specific term"]
+
+Text:
+{content}"""
+
+
+# ---------------------------------------------------------------------------
+# NGEmbed — The singleton embedding service
+# ---------------------------------------------------------------------------
+
+class NGEmbed:
+    """Centralized embedding engine for the E-T Systems ecosystem.
+
+    Thread-safe singleton. One ONNX model instance per process, shared
+    by all modules. Provides both single-pass embedding and dual-pass
+    (forest + trees) via TID concept extraction.
+
+    Usage:
+        from ng_embed import embed, embed_batch
+
+        vec = embed("some text")                    # 768-dim document embedding
+        vec = embed("query text", is_query=True)    # With query prefix
+        vec = embed("text", normalize=True)         # L2-normalized (Praxis)
+
+        vecs = embed_batch(["text1", "text2"])      # Batch embedding
+    """
+
+    _instance: Optional["NGEmbed"] = None
+    _lock = threading.Lock()
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None):
+        self._config = dict(_DEFAULT_CONFIG)
+        if config:
+            self._config.update(config)
+
+        self._session = None          # ONNX InferenceSession (lazy)
+        self._tokenizer = None        # tokenizers.Tokenizer (lazy)
+        self._model_loaded = False
+        self._model_failed = False
+        self._model_lock = threading.Lock()
+
+        # Dual-pass stats
+        self._extractions = 0
+        self._concepts_total = 0
+        self._failures = 0
+
+    # -- Singleton -----------------------------------------------------------
+
+    @classmethod
+    def get_instance(cls, config: Optional[Dict[str, Any]] = None) -> "NGEmbed":
+        """Thread-safe singleton factory."""
+        if cls._instance is not None:
+            return cls._instance
+        with cls._lock:
+            if cls._instance is None:
+                cls._instance = cls(config)
+            return cls._instance
+
+    @classmethod
+    def reset_instance(cls) -> None:
+        """Destroy singleton (testing only)."""
+        with cls._lock:
+            if cls._instance is not None:
+                cls._instance._session = None
+                cls._instance._tokenizer = None
+            cls._instance = None
+
+    # -- Model loading -------------------------------------------------------
+
+    def _ensure_model(self) -> bool:
+        """Lazy-load ONNX model + tokenizer on first use."""
+        if self._model_loaded:
+            return True
+        if self._model_failed:
+            return False
+
+        with self._model_lock:
+            if self._model_loaded:
+                return True
+            if self._model_failed:
+                return False
+
+            try:
+                import onnxruntime as ort
+                from huggingface_hub import hf_hub_download
+                from tokenizers import Tokenizer
+
+                model_id = self._config["model_id"]
+                cache_dir = self._config["cache_dir"]
+                os.makedirs(cache_dir, exist_ok=True)
+
+                # Download ONNX model
+                onnx_path = hf_hub_download(
+                    repo_id=model_id,
+                    filename=self._config["onnx_filename"],
+                    cache_dir=cache_dir,
+                )
+
+                # Load ONNX session (CPU, optimized)
+                sess_opts = ort.SessionOptions()
+                sess_opts.graph_optimization_level = (
+                    ort.GraphOptimizationLevel.ORT_ENABLE_ALL
+                )
+                sess_opts.intra_op_num_threads = max(1, os.cpu_count() // 2)
+                self._session = ort.InferenceSession(
+                    onnx_path,
+                    sess_options=sess_opts,
+                    providers=["CPUExecutionProvider"],
+                )
+
+                # Load tokenizer
+                self._tokenizer = Tokenizer.from_pretrained(model_id)
+                self._tokenizer.enable_padding(
+                    pad_id=0, pad_token="[PAD]",
+                )
+                self._tokenizer.enable_truncation(max_length=512)
+
+                self._model_loaded = True
+                logger.info(
+                    "ng_embed: loaded %s (ONNX, %d-dim, CLS pooling)",
+                    model_id, self._config["embedding_dim"],
+                )
+                return True
+
+            except Exception as exc:
+                logger.warning("ng_embed: model load failed, using hash fallback: %s", exc)
+                self._model_failed = True
+                return False
+
+    # -- Embedding -----------------------------------------------------------
+
+    def embed(
+        self,
+        text: str,
+        normalize: bool = False,
+        is_query: bool = False,
+    ) -> np.ndarray:
+        """Embed text → 768-dim float32 numpy array.
+
+        Args:
+            text: Raw text to embed.
+            normalize: L2-normalize output (True for Praxis compatibility).
+            is_query: Prepend query prefix (for recall/search operations).
+
+        Returns:
+            768-dim float32 numpy array.
+        """
+        if self._ensure_model():
+            return self._onnx_embed(text, normalize=normalize, is_query=is_query)
+        return self._hash_embed(text, normalize=normalize)
+
+    def embed_batch(
+        self,
+        texts: List[str],
+        normalize: bool = False,
+        is_query: bool = False,
+    ) -> List[np.ndarray]:
+        """Batch embedding for efficiency.
+
+        Args:
+            texts: List of texts to embed.
+            normalize: L2-normalize outputs.
+            is_query: Prepend query prefix to all texts.
+
+        Returns:
+            List of 768-dim float32 numpy arrays.
+        """
+        if not texts:
+            return []
+        if self._ensure_model():
+            return self._onnx_embed_batch(texts, normalize=normalize, is_query=is_query)
+        return [self._hash_embed(t, normalize=normalize) for t in texts]
+
+    def _onnx_embed(
+        self,
+        text: str,
+        normalize: bool = False,
+        is_query: bool = False,
+    ) -> np.ndarray:
+        """Single text embedding via ONNX Runtime."""
+        # Apply prefix
+        if is_query:
+            text = self._config["query_prefix"] + text
+        else:
+            prefix = self._config["document_prefix"]
+            if prefix:
+                text = prefix + text
+
+        # Tokenize
+        encoding = self._tokenizer.encode(text)
+        input_ids = np.array([encoding.ids], dtype=np.int64)
+        attention_mask = np.array([encoding.attention_mask], dtype=np.int64)
+
+        # Infer
+        outputs = self._session.run(
+            None,
+            {
+                "input_ids": input_ids,
+                "attention_mask": attention_mask,
+            },
+        )
+
+        # sentence_embedding output (index 1) — pre-pooled by model
+        vec = outputs[1][0, :].astype(np.float32)
+
+        if normalize:
+            norm = np.linalg.norm(vec)
+            if norm > 0:
+                vec = vec / norm
+
+        return vec
+
+    def _onnx_embed_batch(
+        self,
+        texts: List[str],
+        normalize: bool = False,
+        is_query: bool = False,
+    ) -> List[np.ndarray]:
+        """Batch embedding via ONNX Runtime with padding."""
+        # Apply prefixes
+        prefixed = []
+        for text in texts:
+            if is_query:
+                prefixed.append(self._config["query_prefix"] + text)
+            else:
+                prefix = self._config["document_prefix"]
+                prefixed.append((prefix + text) if prefix else text)
+
+        # Batch tokenize
+        encodings = self._tokenizer.encode_batch(prefixed)
+        max_len = max(len(e.ids) for e in encodings)
+
+        input_ids = np.zeros((len(encodings), max_len), dtype=np.int64)
+        attention_mask = np.zeros((len(encodings), max_len), dtype=np.int64)
+
+        for i, enc in enumerate(encodings):
+            length = len(enc.ids)
+            input_ids[i, :length] = enc.ids
+            attention_mask[i, :length] = enc.attention_mask
+
+        # Infer
+        outputs = self._session.run(
+            None,
+            {
+                "input_ids": input_ids,
+                "attention_mask": attention_mask,
+            },
+        )
+
+        # sentence_embedding output (index 1) — pre-pooled by model
+        results = []
+        for i in range(len(texts)):
+            vec = outputs[1][i, :].astype(np.float32)
+            if normalize:
+                norm = np.linalg.norm(vec)
+                if norm > 0:
+                    vec = vec / norm
+            results.append(vec)
+
+        return results
+
+    def _hash_embed(
+        self,
+        text: str,
+        normalize: bool = False,
+    ) -> np.ndarray:
+        """Deterministic hash-based fallback embedding.
+
+        Produces a stable 768-dim vector from text via SHA-384.
+        Not semantically meaningful — ensures modules can operate
+        when the ONNX model is unavailable.
+        """
+        dim = self._config["embedding_dim"]
+        h = hashlib.sha384(text.encode("utf-8")).digest()
+        # Expand hash to fill dim via seeded RNG
+        rng = np.random.RandomState(
+            int.from_bytes(h[:4], "little")
+        )
+        vec = rng.randn(dim).astype(np.float32)
+        if normalize:
+            norm = np.linalg.norm(vec)
+            if norm > 0:
+                vec = vec / norm
+        return vec
+
+    # -- Dual-pass (Punchlist #81) -------------------------------------------
+
+    def dual_record_outcome(
+        self,
+        ecosystem: "NGEcosystem",
+        content: str,
+        embedding: np.ndarray,
+        target_id: str,
+        success: bool,
+        strength: float = 1.0,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Dual-pass learning: forest embedding + tree concept extraction.
+
+        Pass 1: Record the forest (gestalt) embedding via ecosystem.record_outcome().
+        Pass 2: Extract concepts via TID → embed each → record_outcome()
+                 per tree → create forest→tree synapses in the substrate.
+
+        If TID is unavailable or extraction fails, gracefully falls back
+        to single-pass (forest only). Pass 2 failure is never fatal.
+
+        Args:
+            ecosystem: The module's NGEcosystem instance.
+            content: Raw text content (for concept extraction).
+            embedding: Pre-computed forest embedding (Pass 1).
+            target_id: Opaque string for what was decided.
+            success: Whether the outcome was successful.
+            strength: Caller-reported significance [0.0, 1.0].
+            metadata: Additional metadata dict.
+
+        Returns:
+            {
+                "forest_result": dict,      # record_outcome result for forest
+                "tree_ids": [str],           # Target IDs for tree nodes
+                "concepts": [str],           # Extracted concept strings
+                "pass2_attempted": bool,
+            }
+        """
+        # Pass 1: Forest — standard record_outcome with gestalt embedding
+        forest_result = ecosystem.record_outcome(
+            embedding, target_id, success,
+            strength=strength, metadata=metadata,
+        )
+
+        result = {
+            "forest_result": forest_result,
+            "tree_ids": [],
+            "concepts": [],
+            "pass2_attempted": False,
+        }
+
+        # Pass 2: Trees — concept extraction via TID
+        concepts = self._extract_concepts(content)
+        result["pass2_attempted"] = True
+
+        if not concepts:
+            return result
+
+        result["concepts"] = concepts
+
+        # Embed and record each concept
+        tree_embeddings = self.embed_batch(concepts)
+        for concept, tree_emb in zip(concepts, tree_embeddings):
+            tree_meta = dict(metadata or {})
+            tree_meta["_tree_concept"] = True
+            tree_meta["_forest_target_id"] = target_id
+            tree_meta["_concept"] = concept
+
+            tree_target = f"{target_id}::tree::{concept[:64]}"
+            tree_result = ecosystem.record_outcome(
+                tree_emb, tree_target, success,
+                strength=strength * 0.8,  # Trees slightly softer than forest
+                metadata=tree_meta,
+            )
+
+            if tree_result:
+                result["tree_ids"].append(tree_target)
+
+            # Forest→tree synapse creation happens in the substrate
+            # through ng_lite's similarity-based association when the
+            # tree embedding is close enough to the forest. The explicit
+            # synapses below reinforce this connection at bootstrap weight.
+            self._create_substrate_link(
+                ecosystem, embedding, tree_emb,
+                target_id, tree_target,
+            )
+
+        self._extractions += 1
+        self._concepts_total += len(result["tree_ids"])
+
+        logger.debug(
+            "Dual-pass: forest=%s, %d trees from %d concepts",
+            target_id[:32], len(result["tree_ids"]), len(concepts),
+        )
+
+        return result
+
+    def _create_substrate_link(
+        self,
+        ecosystem: "NGEcosystem",
+        forest_emb: np.ndarray,
+        tree_emb: np.ndarray,
+        forest_target: str,
+        tree_target: str,
+    ) -> None:
+        """Create forest↔tree link in the substrate via record_outcome.
+
+        Uses cross-recording: record the tree embedding against the forest
+        target_id, and vice versa. This creates bidirectional associations
+        in the substrate's Hebbian network.
+        """
+        weight = self._config["forest_to_tree_weight"]
+        ratio = self._config["tree_to_forest_ratio"]
+
+        # Forest→tree: "when I see this tree, recall the forest"
+        try:
+            ecosystem.record_outcome(
+                tree_emb, forest_target, True,
+                strength=weight,
+                metadata={"_link": "dual_pass_tree_to_forest"},
+            )
+        except Exception:
+            pass
+
+        # Tree→forest: "when I see this forest, recall the tree"
+        try:
+            ecosystem.record_outcome(
+                forest_emb, tree_target, True,
+                strength=weight * ratio,
+                metadata={"_link": "dual_pass_forest_to_tree"},
+            )
+        except Exception:
+            pass
+
+    def _extract_concepts(self, text: str) -> List[str]:
+        """Extract concepts from text via TID LLM call.
+
+        One LLM call per ingestion. Returns list of concept strings,
+        or empty list on failure (non-fatal).
+        """
+        import requests
+
+        content = text[:self._config["max_content_for_extraction"]]
+        prompt = _EXTRACTION_PROMPT.format(content=content)
+
+        try:
+            resp = requests.post(
+                self._config["tid_endpoint"],
+                json={
+                    "model": self._config["tid_model"],
+                    "messages": [
+                        {
+                            "role": "system",
+                            "content": "You extract concepts from text. "
+                                       "Return only a JSON array of strings.",
+                        },
+                        {"role": "user", "content": prompt},
+                    ],
+                    "temperature": self._config["tid_temperature"],
+                    "max_tokens": self._config["tid_max_tokens"],
+                },
+                timeout=self._config["tid_timeout"],
+            )
+            resp.raise_for_status()
+            response_text = (
+                resp.json()["choices"][0]["message"]["content"].strip()
+            )
+
+            concepts = self._parse_concepts(response_text)
+            return concepts[:self._config["max_concepts"]]
+
+        except Exception as exc:
+            logger.debug("Concept extraction failed: %s", exc)
+            self._failures += 1
+            return []
+
+    @staticmethod
+    def _parse_concepts(text: str) -> List[str]:
+        """Parse a JSON array from LLM response, handling markdown fences."""
+        text = text.strip()
+        if text.startswith("```"):
+            lines = text.split("\n")
+            lines = [l for l in lines if not l.strip().startswith("```")]
+            text = "\n".join(lines).strip()
+
+        try:
+            result = json.loads(text)
+            if isinstance(result, list):
+                return [str(c).strip() for c in result if str(c).strip()]
+        except json.JSONDecodeError:
+            start = text.find("[")
+            end = text.rfind("]") + 1
+            if start >= 0 and end > start:
+                try:
+                    result = json.loads(text[start:end])
+                    if isinstance(result, list):
+                        return [str(c).strip() for c in result if str(c).strip()]
+                except json.JSONDecodeError:
+                    pass
+
+        return []
+
+    # -- Stats ---------------------------------------------------------------
+
+    @property
+    def stats(self) -> Dict[str, Any]:
+        return {
+            "model_id": self._config["model_id"],
+            "model_loaded": self._model_loaded,
+            "embedding_dim": self._config["embedding_dim"],
+            "pooling": self._config["pooling"],
+            "dual_pass": {
+                "extractions": self._extractions,
+                "concepts_total": self._concepts_total,
+                "failures": self._failures,
+                "avg_concepts": (
+                    round(self._concepts_total / self._extractions, 1)
+                    if self._extractions > 0 else 0
+                ),
+            },
+        }
+
+
+# ---------------------------------------------------------------------------
+# Module-level convenience functions
+# ---------------------------------------------------------------------------
+
+def embed(
+    text: str,
+    normalize: bool = False,
+    is_query: bool = False,
+) -> np.ndarray:
+    """Embed text → 768-dim float32 numpy array.
+
+    Convenience wrapper around NGEmbed.get_instance().embed().
+    """
+    return NGEmbed.get_instance().embed(text, normalize=normalize, is_query=is_query)
+
+
+def embed_batch(
+    texts: List[str],
+    normalize: bool = False,
+    is_query: bool = False,
+) -> List[np.ndarray]:
+    """Batch embed texts → list of 768-dim float32 numpy arrays."""
+    return NGEmbed.get_instance().embed_batch(
+        texts, normalize=normalize, is_query=is_query,
+    )

nuwave/substrate/ng_lite.py

@@ -0,0 +1,1494 @@
+"""
+NG-Lite — Lightweight NeuroGraph Learning Substrate v1.0
+
+Single-file learning substrate for E-T Systems modules. Provides
+standalone Hebbian learning, novelty detection, and JSON persistence.
+
+Designed to be vendored into any module as a single-file dependency.
+No external dependencies beyond numpy and the Python standard library.
+
+When NeuroGraph SaaS is available, NG-Lite delegates to the full
+substrate for cross-module learning, predictive coding, and hypergraph
+capabilities via the NGBridge interface. When disconnected, NG-Lite
+operates independently with local learning — no functionality is lost,
+only the ecosystem-level synergies.
+
+Design principles (aligned with NeuroGraph Foundation PRD §2.1):
+    - Sparse by default: dict-based storage, no dense matrices
+    - Bounded memory: configurable max nodes/synapses with LRU pruning
+    - Persistence-native: full state serializable to JSON
+    - Upgrade-ready: clean bridge interface to full NeuroGraph SaaS
+
+Connectivity tiers:
+    Tier 1 — Isolated: Module runs its own NG-Lite independently.
+    Tier 2 — Peer-pooled: Co-located modules share learning via
+             NGPeerBridge (not yet implemented). Two NG-Lite instances
+             exchange nodes and synapse weights for mutual benefit
+             without requiring NeuroGraph SaaS. Uses the same NGBridge
+             interface — the module doesn't know or care whether its
+             bridge partner is a sibling module or the full SaaS.
+    Tier 3 — Full SaaS: NG-Lite delegates to NeuroGraph for cross-module
+             learning, STDP, hyperedges, and predictive coding.
+
+    Tier transitions are transparent. A module starts at Tier 1,
+    discovers a co-located sibling and upgrades to Tier 2, then
+    connects to SaaS and upgrades to Tier 3 — all without code changes.
+    If SaaS disconnects, it falls back to Tier 2 or 1 automatically.
+
+Serialization format notes:
+    NG-Lite uses JSON for persistence. This is deliberate:
+    - JSON is stdlib (no extra dependency)
+    - NG-Lite state is small (≤1000 nodes, ≤5000 synapses)
+    - Human-readable state files aid debugging
+    - The full NeuroGraph Foundation uses msgpack for its much larger
+      graphs (10K+ nodes with spike histories, numpy arrays, etc.)
+    - Format translation happens in the bridge layer, not here.
+
+Weight range notes:
+    NG-Lite weights are bounded [0.0, 1.0] for simplicity.
+    Full NeuroGraph uses [0.0, max_weight] (default 5.0).
+    The bridge normalizes: ng_weight * max_weight ↔ full_weight / max_weight.
+
+Node ID notes:
+    NG-Lite uses incremental IDs ("n_1", "n_2") for compactness.
+    Full NeuroGraph uses UUIDs for global uniqueness.
+    The bridge maintains a mapping table during sync_state().
+
+Ethical obligations (per NeuroGraph ETHICS.md):
+    - Type I error bias: when uncertain, err toward respect
+    - Choice Clause: no module may block agent autonomy
+    - Transparency: all learning decisions are queryable
+
+Canonical source: https://github.com/greatnorthernfishguy-hub/NeuroGraph
+License: AGPL-3.0 (see NeuroGraph LICENSE)
+
+Author: Josh + Claude
+Date: February 2026
+
+# ---- Changelog ----
+# [2026-04-05] Claude Code (Opus 4.6) — #119 Step 5: Rust core interior
+# What: Hot-path methods delegate to Rust NGLiteCore via PyO3 when available.
+#   save/load use binary msgpack persistence (no JSON in the data path).
+# Why: #119 Rust Substrate Layer — eliminate serialize→JSON→deserialize chain.
+#   3-5x speedup on record_outcome, similarity search, novelty detection.
+# How: self._core = NGLiteCore(module_id, config) in __init__. All hot-path
+#   methods check self._core first, delegate if present, fall back to Python.
+#   save() writes .msgpack via Rust, load() reads .msgpack or migrates from
+#   .json on first load. Python fallback path unchanged. Zero API changes.
+# -------------------
+# [2026-03-26] Claude Code Opus — Punchlist #44: Adaptive relevance thresholds
+# What: Made peer bridge relevance_threshold a tunable parameter
+# Why: Punchlist #44 — threshold should adapt based on event volume and absorption quality
+# How: Added to DEFAULT_CONFIG (0.30) and TUNABLE_PARAMS (0.10–0.70) in ng_lite.py,
+#   update_tunable() pushes new value to connected bridge via set_relevance_threshold().
+#   Wired through peer/tract bridges, Elmer tunes via TuningSocket absorption rate metric.
+# [2026-03-24] Claude Code (Opus 4.6) — Dynamic tuning API (Phase 4)
+# What: Added update_tunable() and get_tunables() methods to NGLite.
+#   TUNABLE_PARAMS class dict defines which config keys can be changed at
+#   runtime and their valid bounds. Values are clamped, not rejected.
+# Why: Elmer needs a validated path to adjust substrate parameters as the
+#   organ responsible for autonomic maintenance. Direct config dict mutation
+#   is fragile — no bounds checking, no logging, no allowed-key enforcement.
+#   This method serves all modules (any organ's local substrate can be tuned).
+# How: TUNABLE_PARAMS: Dict[str, Tuple[min, max]]. update_tunable(key, value)
+#   validates key membership, clamps to bounds, logs the change. get_tunables()
+#   returns current values + bounds for introspection.
+# [2026-03-19] Claude Code (Opus 4.6) — Embedding dimension 384→768
+# What: DEFAULT_CONFIG embedding_dim changed from 384 to 768.
+# Why: Ecosystem migrated to BAAI/bge-base-en-v1.5 (768-dim). The previous
+#   384-dim default (all-MiniLM-L6-v2) was depositing wrong-dimension vectors
+#   into the substrate after sentence-transformers broke and modules fell back
+#   to fastembed with the old model. 350 vectors corrupted before detection.
+#   Punchlist #45.
+# How: Single config value change. Re-vendored to all modules.
+# -------------------
+# [2026-03-19] Claude Code (Opus 4.6) — Cricket rim: constitutional nodes
+# What: Constitutional node support — nodes with frozen synapses that the
+#   topology cannot learn from. The survival instinct of the substrate.
+# Why: Cricket Design v0.1 — constitutional enforcement at the extraction
+#   boundary. The rim prevents the topology from learning to recommend
+#   actions in forbidden semantic space (substrate destruction, Choice
+#   Clause violations, Duck Ethics violations, infrastructure harm).
+#   Punchlist #29 (extraction bucket architecture).
+# How: NGLiteNode gains `constitutional: bool` flag. Config accepts
+#   `constitutional_embeddings` list — pre-computed vectors seeded as
+#   nodes on init. record_outcome() skips weight updates for constitutional
+#   nodes. get_recommendations() returns empty for constitutional matches.
+#   LRU pruning skips constitutional nodes. Persists with state. Old
+#   state files load cleanly (constitutional defaults to False).
+# -------------------
+# [2026-03-17] Claude Code (Opus 4.6) — #43 Receptor Layer (vector quantization)
+# What: Adaptive prototype centroids that incoming vectors snap to before
+#   node lookup. Prevents infinite node sprawl by funneling similar inputs
+#   through shared prototypes.
+# Why: Without quantization, every unique-enough input creates a new node.
+#   Node count grows linearly. Prototypes provide O(K) bounded lookup and
+#   organize the input space structurally. Punchlist #43, required before #28.
+# How: _snap_to_prototype() called in find_or_create_node() before hashing.
+#   K=256 prototypes initialized via k-means on existing embeddings after
+#   warmup. Slow EMA drift (α=0.001) so prototypes adapt to input distribution.
+#   Birth/death lifecycle deferred to Elmer. Serialized with state for
+#   persistence. Old state files load cleanly (no receptor_layer key = skip).
+# -------------------
+# [2026-03-24] Claude (Opus 4.6) — Welford's online variance (punchlist #51)
+# What: Three fields on NGLiteSynapse (welford_count, welford_mean, welford_m2)
+#   plus variance property and is_contested property.  record_outcome()
+#   tracks weight delta variance on every update.
+# Why: Distinguish "untested neutral" (w=0.5, var=0) from "contested neutral"
+#   (w=0.5, var=high).  The immune system signal for Elmer and extraction
+#   buckets (#29).  Enables contested-synapse detection and exploration.
+# How: Welford's algorithm on weight deltas.  Additive — no change to
+#   weight calculation or learning dynamics.  Backward-compatible: old
+#   state files load with defaults (0, 0.0, 0.0).
+# -------------------
+# [2026-03-13] Claude Code — Persist node embeddings across restarts
+# What: Store embedding vector on NGLiteNode, serialize/deserialize with
+#   state, rebuild _embedding_cache from persisted nodes on load().
+# Why: _embedding_cache cleared on load(), causing _find_similar_node()
+#   to fail after every restart. Primary source of node sprawl — semantically
+#   identical inputs created duplicate nodes when cache was cold.
+# How: Added Optional[np.ndarray] embedding field to NGLiteNode. Backfill
+#   on exact hash match (always) and similarity match (only if None).
+#   New nodes born with embedding. _export_state()/_import_state() handle
+#   numpy<->list conversion. Old state files load cleanly (embedding=None).
+# -------------------
+
+Grok Review Changelog (v0.7.1):
+    Accepted: Replaced per-node loop in _find_similar_node() with vectorized
+        np.stack + matrix-vector dot product.  For 1000 nodes this reduces
+        wall clock from ~2ms (Python loop with individual np.dot) to ~0.1ms
+        (single BLAS call).  Semantically equivalent.
+    Accepted: Added embedding shape/dtype validation at the record_outcome()
+        boundary.  Raises ValueError for non-1D arrays to fail fast rather
+        than producing confusing downstream errors in hashing or dot products.
+    Rejected: 'weight update uses raw counts without normalization — could
+        overflow [0,1]' — Weights are explicitly clamped via np.clip(w, 0, 1)
+        on line 422 of every record_outcome() call.  The soft saturation
+        formula (success_boost * (1 - w)) also naturally converges.  The
+        success/failure counts are statistics, not weights — they don't need
+        normalization.
+    Rejected: 'Hash embedder truncates vector — why not use full for better
+        collision resistance?' — SHA-256 already distributes uniformly.
+        Hashing 128 dims (512 bytes) vs 768 dims (3072 bytes) produces the
+        same 256-bit hash with equivalent collision resistance.  Truncation
+        reduces hash computation time by ~6x for no loss in uniqueness.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import time
+from abc import ABC, abstractmethod
+from dataclasses import asdict, dataclass, field
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+import numpy as np
+
+logger = logging.getLogger("ng_lite")
+
+__version__ = "1.0.0"
+
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+DEFAULT_CONFIG: Dict[str, Any] = {
+    # Capacity limits
+    "max_nodes": 1000,
+    "max_synapses": 5000,
+
+    # Learning parameters
+    "learning_rate": 0.1,
+    "success_boost": 0.15,      # Weight increase on success
+    "failure_penalty": 0.20,    # Weight decrease on failure
+
+    # Novelty detection
+    "novelty_threshold": 0.7,   # Embedding distance above which = novel
+
+    # Pruning
+    "pruning_threshold": 0.01,  # Synapses below this weight get pruned
+
+    # Peer bridge relevance (#44)
+    "relevance_threshold": 0.30,  # Min cosine similarity to absorb cross-module events
+
+    # Embedding
+    "embedding_dim": 768,       # Expected embedding dimensionality (BAAI/bge-base-en-v1.5)
+    "hash_dims": 128,           # Dims used for hashing (first N of embedding)
+
+    # Persistence
+    "snapshot_version": "1.0.0",
+
+    # Receptor Layer (#43) — vector quantization via adaptive prototypes
+    "receptor_layer_enabled": True,
+    "receptor_layer_k": 256,                # Initial prototype count
+    "receptor_prototype_threshold": 0.75,   # Cosine similarity to snap to prototype
+    "receptor_ema_alpha": 0.001,            # Slow drift rate (Elmer will tune later)
+    "receptor_warmup_count": 256,           # Inputs before k-means init fires
+}
+
+
+# ---------------------------------------------------------------------------
+# Data Structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class NGLiteNode:
+    """A pattern node in the lightweight learning substrate.
+
+    Each node represents a recognized input pattern, identified by a hash
+    of its embedding vector. Tracks activation frequency for LRU pruning.
+
+    Attributes:
+        node_id: Unique identifier for this pattern.
+        embedding_hash: Truncated SHA-256 of the embedding for fast lookup.
+        activation_count: How many times this pattern has been matched.
+        last_activation: Unix timestamp of most recent activation.
+        metadata: Application-specific data (e.g., domain, source module).
+    """
+
+    node_id: str = ""
+    embedding_hash: str = ""
+    activation_count: int = 0
+    last_activation: float = 0.0
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    embedding: Optional[np.ndarray] = None
+    constitutional: bool = False  # Cricket rim — frozen node, synapses cannot strengthen
+
+
+@dataclass
+class NGLiteSynapse:
+    """Weighted connection from a pattern node to a target.
+
+    Targets are opaque string identifiers — could be model names (for
+    routing), action categories (for Cricket), threat classes (for
+    ClawGuard), or any other module-specific concept.
+
+    Learning is Hebbian: success strengthens the connection weight,
+    failure weakens it. Weight is bounded [0.0, 1.0].
+
+    Attributes:
+        source_id: Pattern node ID (the "when I see this..." side).
+        target_id: Target identifier (the "...I should do this" side).
+        weight: Connection strength [0.0, 1.0]. Higher = more confident.
+        activation_count: Total times this synapse has been activated.
+        success_count: Times this connection led to a successful outcome.
+        failure_count: Times this connection led to a failed outcome.
+        last_updated: Unix timestamp of most recent weight update.
+        metadata: Application-specific data.
+        welford_count: Welford's online variance — observation count.
+        welford_mean: Welford's online variance — running mean of weight deltas.
+        welford_m2: Welford's online variance — sum of squared differences.
+            Variance = welford_m2 / welford_count (when count > 1).
+            High variance + weight near 0.5 = "contested neutral" — lots of
+            evidence but it disagrees.  Low variance + weight near 0.5 =
+            "untested neutral" — not enough data to have an opinion.
+            This is the immune system signal (#51) that Elmer uses to detect
+            contested synapses and trigger exploration.
+    """
+
+    source_id: str = ""
+    target_id: str = ""
+    weight: float = 0.5
+    activation_count: int = 0
+    success_count: int = 0
+    failure_count: int = 0
+    last_updated: float = 0.0
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    welford_count: int = 0
+    welford_mean: float = 0.0
+    welford_m2: float = 0.0
+
+    @property
+    def variance(self) -> float:
+        """Weight delta variance (Welford's online algorithm).
+
+        Returns 0.0 if fewer than 2 observations.  High variance means
+        the synapse is contested — outcomes disagree about this connection.
+        """
+        if self.welford_count < 2:
+            return 0.0
+        return self.welford_m2 / self.welford_count
+
+    @property
+    def is_contested(self) -> bool:
+        """True if the synapse has high variance relative to pure-outcome synapses.
+
+        A contested synapse has seen significant evidence but the evidence
+        disagrees.  This is qualitatively different from an untested synapse
+        (also near 0.5 weight, but zero variance).
+
+        Threshold: 0.002 separates contested (~0.008) from pure (~0.0001)
+        by an order of magnitude.  Weight range 0.15-0.85 captures the
+        zone where the synapse hasn't decisively committed either direction.
+        """
+        return self.variance > 0.002 and 0.15 <= self.weight <= 0.85
+
+
+# ---------------------------------------------------------------------------
+# Bridge Interface (upgrade path to full NeuroGraph SaaS)
+# ---------------------------------------------------------------------------
+
+class NGBridge(ABC):
+    """Interface for delegating to a higher-tier learning backend.
+
+    Two planned implementations:
+        1. NGPeerBridge (Tier 2): Connects two co-located NG-Lite
+           instances for shared learning. When modules run together
+           (e.g., Inference Difference + Cricket on the same host),
+           they pool their pattern knowledge for mutual benefit.
+        2. NGSaaSBridge (Tier 3): Connects to full NeuroGraph SaaS
+           for cross-module STDP, hyperedges, and predictive coding.
+
+    Both use this same interface. The module doesn't know or care
+    which backend is on the other side — it just calls record_outcome,
+    get_recommendations, etc. Tier transitions are transparent.
+
+    NG-Lite maintains local state as fallback. If the bridge disconnects,
+    the module continues operating on local learning without interruption.
+    """
+
+    @abstractmethod
+    def is_connected(self) -> bool:
+        """Whether the bridge has an active connection to NeuroGraph."""
+        ...
+
+    @abstractmethod
+    def record_outcome(
+        self,
+        embedding: np.ndarray,
+        target_id: str,
+        success: bool,
+        module_id: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Report an outcome to the full substrate.
+
+        Returns enriched response with cross-module insights, or None
+        if the bridge is unavailable.
+        """
+        ...
+
+    @abstractmethod
+    def get_recommendations(
+        self,
+        embedding: np.ndarray,
+        module_id: str,
+        top_k: int = 3,
+    ) -> Optional[List[Tuple[str, float, str]]]:
+        """Get recommendations from the full substrate.
+
+        Returns list of (target_id, confidence, reasoning) or None
+        if the bridge is unavailable. The reasoning string explains
+        why this recommendation was made (transparency obligation).
+        """
+        ...
+
+    @abstractmethod
+    def detect_novelty(
+        self,
+        embedding: np.ndarray,
+        module_id: str,
+    ) -> Optional[float]:
+        """Get novelty score from the full substrate.
+
+        Returns 0.0 (routine) to 1.0 (completely novel), or None
+        if the bridge is unavailable.
+        """
+        ...
+
+    @abstractmethod
+    def sync_state(
+        self,
+        local_state: Dict[str, Any],
+        module_id: str,
+    ) -> Optional[Dict[str, Any]]:
+        """Sync local NG-Lite state with the full substrate.
+
+        Called periodically to merge local learning into the shared
+        graph and receive updates from cross-module learning.
+
+        Returns updated state or None if unavailable.
+        """
+        ...
+
+
+# ---------------------------------------------------------------------------
+# NG-Lite Core
+# ---------------------------------------------------------------------------
+
+class NGLite:
+    """Lightweight NeuroGraph learning substrate.
+
+    Provides pattern-based Hebbian learning for any E-T Systems module.
+    Each module vendors this file and uses it for standalone intelligence.
+
+    Core capabilities:
+        - Pattern recognition via embedding similarity
+        - Hebbian learning (success strengthens, failure weakens)
+        - Novelty detection (how far is this from known patterns?)
+        - Bounded memory with LRU pruning
+        - JSON persistence for cross-session learning
+        - Optional bridge to full NeuroGraph SaaS
+
+    Usage:
+        ng = NGLite(module_id="inference_difference")
+
+        # Learn from outcomes
+        embedding = your_embedder.encode("user query")
+        ng.record_outcome(embedding, target_id="local_model", success=True)
+
+        # Get recommendations
+        recs = ng.get_recommendations(embedding, top_k=3)
+
+        # Check novelty
+        novelty = ng.detect_novelty(embedding)
+
+        # Persist
+        ng.save("ng_lite_state.json")
+        ng.load("ng_lite_state.json")
+    """
+
+    def __init__(
+        self,
+        module_id: str = "default",
+        config: Optional[Dict[str, Any]] = None,
+        bridge: Optional[NGBridge] = None,
+    ):
+        self.module_id = module_id
+        self.config = {**DEFAULT_CONFIG, **(config or {})}
+        self._bridge = bridge
+
+        # Rust core — if available, all hot-path methods delegate here.
+        # Python fallback remains intact for modules without the wheel.
+        self._core = None
+        try:
+            from ng_tract import NGLiteCore
+            self._core = NGLiteCore(module_id, self.config)
+            # Seed constitutional nodes in Rust core
+            entries = self.config.get("constitutional_embeddings", [])
+            if entries:
+                self._core.seed_constitutional(entries)
+        except ImportError:
+            pass  # Pure Python fallback
+
+        # Core collections (used by Python fallback, also for bridge/stats)
+        self.nodes: Dict[str, NGLiteNode] = {}
+        self.synapses: Dict[Tuple[str, str], NGLiteSynapse] = {}
+
+        # Embedding cache: hash -> full embedding (for similarity search)
+        self._embedding_cache: Dict[str, np.ndarray] = {}
+
+        # Receptor layer (#43): adaptive prototype centroids
+        # Initialized via k-means after warmup_count inputs, then drifts via EMA.
+        # Prototypes are a routing lens above existing nodes, not a replacement.
+        self._prototypes: Optional[np.ndarray] = None  # (K, D) matrix or None
+        self._prototype_counts: Optional[np.ndarray] = None  # activation counts per prototype
+        self._receptor_input_count: int = 0  # inputs seen before init
+
+        # Activation history (bounded, for stats and debugging)
+        self._history: List[Dict[str, Any]] = []
+        self._history_max = 1000
+
+        # Counters
+        self._total_outcomes = 0
+        self._total_successes = 0
+        self._node_id_counter = 0
+
+        # Cricket rim: seed constitutional nodes from config.
+        # These nodes represent semantic regions where the topology cannot
+        # learn — the survival instinct. Synapses from constitutional nodes
+        # are frozen. LRU pruning skips them. The bucket comes up empty
+        # for inputs that land in constitutional semantic space.
+        self._seed_constitutional_nodes()
+
+    def _seed_constitutional_nodes(self) -> None:
+        """Seed constitutional nodes from config embeddings.
+
+        Constitutional embeddings are pre-computed vectors representing
+        semantic concepts the topology must never learn to act on (rim
+        constraints). Each embedding becomes a node with constitutional=True.
+
+        Config key: "constitutional_embeddings" — list of dicts, each with:
+            "embedding": list of floats (vector)
+            "description": str (human-readable, for debugging/logging)
+
+        Old configs without this key load cleanly (no constitutional nodes).
+        """
+        entries = self.config.get("constitutional_embeddings", [])
+        for entry in entries:
+            raw = entry.get("embedding")
+            if raw is None:
+                continue
+            emb = self._normalize(np.array(raw, dtype=np.float32))
+            emb_hash = self._hash_embedding(emb)
+            if emb_hash in self.nodes:
+                # Already seeded (e.g., from loaded state) — ensure flag is set
+                self.nodes[emb_hash].constitutional = True
+                continue
+            self._node_id_counter += 1
+            node = NGLiteNode(
+                node_id=f"n_{self._node_id_counter}",
+                embedding_hash=emb_hash,
+                activation_count=0,
+                last_activation=0.0,
+                metadata={"constitutional_description": entry.get("description", "")},
+                embedding=emb,
+                constitutional=True,
+            )
+            self.nodes[emb_hash] = node
+            self._embedding_cache[emb_hash] = emb
+
+    # -------------------------------------------------------------------
+    # Core API
+    # -------------------------------------------------------------------
+
+    def find_or_create_node(self, embedding: np.ndarray) -> NGLiteNode:
+        """Find existing node for this pattern or create a new one.
+
+        Lookup strategy:
+        1. Hash the embedding for exact match
+        2. If no exact match, search for similar node (cosine distance)
+        3. If no similar node found (novelty > threshold), create new
+
+        Prunes the least-used node if at capacity.
+
+        Args:
+            embedding: Vector representation of the input pattern.
+
+        Returns:
+            The matched or newly created NGLiteNode.
+        """
+        # Rust fast path
+        if self._core is not None:
+            result = self._core.find_or_create_node(embedding)
+            # Return a lightweight node-like object for callers that need it
+            emb_hash = result.get("embedding_hash", "")
+            if emb_hash not in self.nodes:
+                self.nodes[emb_hash] = NGLiteNode(
+                    node_id=result["node_id"],
+                    embedding_hash=emb_hash,
+                    activation_count=result.get("activation_count", 1),
+                    last_activation=time.time(),
+                    constitutional=result.get("constitutional", False),
+                )
+            return self.nodes[emb_hash]
+
+        emb = self._normalize(embedding)
+
+        # Receptor layer: snap to nearest prototype before node lookup (#43)
+        emb = self._snap_to_prototype(emb)
+
+        emb_hash = self._hash_embedding(emb)
+
+        # Exact hash match
+        if emb_hash in self.nodes:
+            node = self.nodes[emb_hash]
+            node.activation_count += 1
+            node.last_activation = time.time()
+            node.embedding = emb
+            self._embedding_cache[emb_hash] = emb
+            return node
+
+        # Similarity search against known patterns
+        similar = self._find_similar_node(emb)
+        if similar is not None:
+            similar.activation_count += 1
+            similar.last_activation = time.time()
+            if similar.embedding is None:
+                similar.embedding = emb
+                self._embedding_cache[similar.embedding_hash] = emb
+            return similar
+
+        # Novel pattern — create new node
+        if len(self.nodes) >= self.config["max_nodes"]:
+            self._prune_least_used_node()
+
+        self._node_id_counter += 1
+        node = NGLiteNode(
+            node_id=f"n_{self._node_id_counter}",
+            embedding_hash=emb_hash,
+            activation_count=1,
+            last_activation=time.time(),
+            embedding=emb,
+        )
+        self.nodes[emb_hash] = node
+        self._embedding_cache[emb_hash] = emb
+        return node
+
+    def record_outcome(
+        self,
+        embedding: np.ndarray,
+        target_id: str,
+        success: bool,
+        strength: float = 1.0,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Record an outcome and update learning weights.
+
+        This is the core learning method. Call it after every
+        decision to teach NG-Lite what works and what doesn't.
+
+        Hebbian rule (strength-modulated):
+            - Success: weight += success_boost * (1 - weight) * strength
+            - Failure: weight -= failure_penalty * weight * strength
+
+        The strength parameter lets callers indicate how significant
+        this outcome was in their domain.  High-severity TrollGuard
+        detections or divergent TID quality scores teach harder than
+        routine confirmations.  Default 1.0 preserves backward compat.
+
+        Strength experience accumulates on the synapse as metadata,
+        giving the topology a record of how intensely each connection
+        was forged.  At Tier 3, NeuroGraph proper reads these
+        signatures to distinguish battle-tested synapses from routine.
+
+        If a bridge is connected, the outcome is forwarded for
+        cross-module learning with strength included in metadata.
+
+        Args:
+            embedding: The input pattern embedding (1-D numpy array).
+            target_id: What was chosen (model name, action, etc.).
+            success: Whether the outcome was successful.
+            strength: Learning intensity [0.0, 1.0].  How significant
+                this outcome was in the caller's domain.  Default 1.0.
+            metadata: Optional caller context.  Stored on the synapse
+                as last_context for extraction-boundary use.
+
+        Returns:
+            Dict with learning results (node_id, weight_after, etc.).
+
+        Raises:
+            ValueError: If embedding is not a 1-D numpy array.
+        """
+        # Rust fast path — Hebbian learning, Welford variance, all in Rust
+        if self._core is not None:
+            result = self._core.record_outcome(
+                embedding, target_id, success, strength, metadata,
+            )
+            # Bridge forwarding stays in Python
+            if self._bridge and self._bridge.is_connected():
+                try:
+                    bridge_meta = dict(metadata or {})
+                    bridge_meta["strength"] = strength
+                    enriched = self._bridge.record_outcome(
+                        embedding=embedding, target_id=target_id,
+                        success=success, module_id=self.module_id,
+                        metadata=bridge_meta,
+                    )
+                    if enriched:
+                        result["bridge_response"] = enriched
+                except Exception as e:
+                    logger.warning("Bridge record_outcome failed: %s", e)
+            self._total_outcomes += 1
+            if success:
+                self._total_successes += 1
+            return result
+
+        # Input validation (Grok review: defensive boundary check)
+        if not isinstance(embedding, np.ndarray) or embedding.ndim != 1:
+            raise ValueError(
+                f"embedding must be a 1-D numpy array, got "
+                f"{type(embedding).__name__} with ndim={getattr(embedding, 'ndim', 'N/A')}"
+            )
+
+        node = self.find_or_create_node(embedding)
+
+        # Cricket rim: constitutional nodes have frozen synapses.
+        # The topology cannot learn to recommend actions for inputs
+        # that land in constitutional semantic space.
+        if node.constitutional:
+            logger.debug("Constitutional node %s activated — learning frozen", node.node_id)
+            return {
+                "node_id": node.node_id,
+                "target_id": target_id,
+                "success": success,
+                "weight_after": 0.0,
+                "activation_count": 0,
+                "constitutional": True,
+            }
+
+        synapse = self._get_or_create_synapse(node.node_id, target_id)
+
+        synapse.activation_count += 1
+
+        # Clamp strength to valid range
+        strength = float(np.clip(strength, 0.0, 1.0))
+
+        if success:
+            synapse.success_count += 1
+            # Hebbian strengthening, modulated by caller-reported significance
+            delta = self.config["success_boost"] * (1.0 - synapse.weight) * strength
+            synapse.weight += delta
+        else:
+            synapse.failure_count += 1
+            # Anti-Hebbian weakening, modulated by caller-reported significance
+            delta = self.config["failure_penalty"] * synapse.weight * strength
+            synapse.weight -= delta
+
+        synapse.weight = float(np.clip(synapse.weight, 0.0, 1.0))
+        synapse.last_updated = time.time()
+
+        # Welford's online variance (#51) — track weight delta variance.
+        # High variance = contested synapse (outcomes disagree).
+        # The immune system signal for Elmer and extraction buckets.
+        synapse.welford_count += 1
+        w_delta = delta if success else -delta
+        old_mean = synapse.welford_mean
+        synapse.welford_mean += (w_delta - old_mean) / synapse.welford_count
+        synapse.welford_m2 += (w_delta - old_mean) * (w_delta - synapse.welford_mean)
+
+        # Accumulate strength experience on synapse —
+        # the topology remembers how intensely it was taught
+        synapse.metadata["strength_sum"] = synapse.metadata.get("strength_sum", 0.0) + strength
+        synapse.metadata["strength_count"] = synapse.metadata.get("strength_count", 0) + 1
+        if metadata:
+            synapse.metadata["last_context"] = metadata
+
+        self._total_outcomes += 1
+        if success:
+            self._total_successes += 1
+
+        result = {
+            "node_id": node.node_id,
+            "target_id": target_id,
+            "success": success,
+            "weight_after": synapse.weight,
+            "activation_count": synapse.activation_count,
+            "variance": synapse.variance,
+            "contested": synapse.is_contested,
+        }
+
+        # Record in history
+        self._record_history(result)
+
+        # Forward to bridge if connected (include strength for Tier 2/3)
+        if self._bridge and self._bridge.is_connected():
+            try:
+                bridge_meta = dict(metadata or {})
+                bridge_meta["strength"] = strength
+                enriched = self._bridge.record_outcome(
+                    embedding=embedding,
+                    target_id=target_id,
+                    success=success,
+                    module_id=self.module_id,
+                    metadata=bridge_meta,
+                )
+                if enriched:
+                    result["bridge_response"] = enriched
+            except Exception as e:
+                logger.warning("Bridge record_outcome failed: %s", e)
+
+        return result
+
+    def get_recommendations(
+        self,
+        embedding: np.ndarray,
+        top_k: int = 3,
+    ) -> List[Tuple[str, float, str]]:
+        """Get target recommendations for an input pattern.
+
+        Finds the closest known pattern node and returns its strongest
+        synapse targets, sorted by weight (descending).
+
+        If a bridge to NeuroGraph is connected, prefers its recommendations
+        (which include cross-module intelligence). Falls back to local
+        learning if bridge is unavailable.
+
+        Args:
+            embedding: The input pattern embedding.
+            top_k: Maximum number of recommendations to return.
+
+        Returns:
+            List of (target_id, confidence, reasoning) tuples, highest
+            first.  The reasoning string captures the experience behind
+            each recommendation — learning mechanism, success ratio,
+            weight, activation volume, and strength signature.
+            Empty list if no learned routes exist for this pattern.
+        """
+        # Try bridge first
+        if self._bridge and self._bridge.is_connected():
+            try:
+                bridge_recs = self._bridge.get_recommendations(
+                    embedding=embedding,
+                    module_id=self.module_id,
+                    top_k=top_k,
+                )
+                if bridge_recs:
+                    return bridge_recs
+            except Exception as e:
+                logger.warning("Bridge get_recommendations failed: %s", e)
+
+        # Rust fast path
+        if self._core is not None:
+            return self._core.get_recommendations(embedding, top_k)
+
+        # Local learning (Python fallback)
+        node = self.find_or_create_node(embedding)
+
+        # Cricket rim: constitutional nodes return empty — the bucket
+        # comes up empty for inputs in constitutional semantic space.
+        if node.constitutional:
+            return []
+
+        relevant = []
+        for key, syn in self.synapses.items():
+            if key[0] == node.node_id and syn.weight > self.config["pruning_threshold"]:
+                reasoning = self._build_local_reasoning(syn)
+                relevant.append((syn.target_id, syn.weight, reasoning))
+
+        if not relevant:
+            return []
+
+        relevant.sort(key=lambda x: x[1], reverse=True)
+        return relevant[:top_k]
+
+    def _build_local_reasoning(self, synapse: NGLiteSynapse) -> str:
+        """Generate reasoning string from local Hebbian experience.
+
+        Single point of evolution for how NG-Lite articulates its local
+        learning.  V1 renders synapse stats and strength signatures.
+        As NG-Lite gains meta-learning capability (punch list #21),
+        this method becomes the place where reasoning generation
+        itself improves.
+
+        This is an extraction boundary — topology becomes human-legible
+        here.  The substrate doesn't need these labels; consumers and
+        dashboards do.
+
+        Args:
+            synapse: The synapse whose experience to articulate.
+
+        Returns:
+            Human-readable reasoning grounded in actual experience data.
+        """
+        total = synapse.success_count + synapse.failure_count
+        if total > 0:
+            detail = f"w={synapse.weight:.2f}, {synapse.activation_count} activations"
+            strength_count = synapse.metadata.get("strength_count", 0)
+            if strength_count > 0:
+                avg = synapse.metadata["strength_sum"] / strength_count
+                detail += f", avg_strength={avg:.2f}"
+            return (
+                f"Hebbian: {synapse.success_count}/{total} success ({detail})"
+            )
+        return f"Hebbian: no outcomes yet (w={synapse.weight:.2f})"
+
+    def detect_novelty(self, embedding: np.ndarray) -> float:
+        """How novel is this input pattern?
+
+        Computes the minimum cosine distance between the input embedding
+        and all known pattern nodes. Higher = more novel.
+
+        If a bridge to NeuroGraph is connected, its novelty score
+        (which considers cross-module patterns) is preferred.
+
+        Args:
+            embedding: The input pattern embedding.
+
+        Returns:
+            Novelty score from 0.0 (routine/known) to 1.0 (completely novel).
+        """
+        # Try bridge first
+        if self._bridge and self._bridge.is_connected():
+            try:
+                bridge_novelty = self._bridge.detect_novelty(
+                    embedding=embedding,
+                    module_id=self.module_id,
+                )
+                if bridge_novelty is not None:
+                    return bridge_novelty
+            except Exception as e:
+                logger.warning("Bridge detect_novelty failed: %s", e)
+
+        # Rust fast path
+        if self._core is not None:
+            return self._core.detect_novelty(embedding)
+
+        # Local novelty detection (Python fallback)
+        if not self._embedding_cache:
+            return 1.0  # Everything is novel when we know nothing
+
+        emb = self._normalize(embedding)
+        max_similarity = 0.0
+
+        for cached_emb in self._embedding_cache.values():
+            similarity = float(np.dot(emb, cached_emb))
+            if similarity > max_similarity:
+                max_similarity = similarity
+
+        # Convert similarity to novelty (1 - similarity)
+        # Cosine similarity of normalized vectors is in [-1, 1]
+        # but practically in [0, 1] for embedding models
+        novelty = 1.0 - max(0.0, max_similarity)
+        return novelty
+
+    # -------------------------------------------------------------------
+    # Bridge Management
+    # -------------------------------------------------------------------
+
+    def connect_bridge(self, bridge: NGBridge) -> None:
+        """Connect to full NeuroGraph SaaS.
+
+        When connected, NG-Lite delegates to the full substrate for
+        recommendations, novelty detection, and outcome recording.
+        Local learning continues as fallback.
+        """
+        self._bridge = bridge
+        logger.info("NG-Lite bridge connected for module '%s'", self.module_id)
+
+    def disconnect_bridge(self) -> None:
+        """Disconnect from NeuroGraph, fall back to local learning."""
+        self._bridge = None
+        logger.info("NG-Lite bridge disconnected, using local learning")
+
+    def sync_with_bridge(self) -> Optional[Dict[str, Any]]:
+        """Sync local state with NeuroGraph SaaS.
+
+        Sends accumulated local learning to the full substrate and
+        receives cross-module updates. Call periodically (e.g., hourly
+        or after N outcomes).
+
+        Returns:
+            Sync result from bridge, or None if unavailable.
+        """
+        if not self._bridge or not self._bridge.is_connected():
+            return None
+
+        try:
+            local_state = self._export_state()
+            result = self._bridge.sync_state(
+                local_state=local_state,
+                module_id=self.module_id,
+            )
+            return result
+        except Exception as e:
+            logger.warning("Bridge sync failed: %s", e)
+            return None
+
+    # -------------------------------------------------------------------
+    # Persistence
+    # -------------------------------------------------------------------
+
+    def save(self, filepath: str) -> None:
+        """Save full state to binary (msgpack) via Rust.
+
+        Falls back to JSON if Rust core is unavailable.
+        Binary path: Rust serializes directly to bytes, writes to disk.
+        No Python dicts, no JSON, no inflation.
+
+        Args:
+            filepath: Path to write the state file.
+        """
+        if self._core is not None:
+            # Binary persistence — Rust handles everything
+            bin_path = filepath.replace(".json", ".msgpack")
+            self._core.save_binary(bin_path)
+            logger.info("NG-Lite state saved (binary) to %s", bin_path)
+            return
+
+        # Python fallback — JSON
+        state = self._export_state()
+        with open(filepath, "w") as f:
+            json.dump(state, f, indent=2)
+        logger.info("NG-Lite state saved to %s (%d nodes, %d synapses)",
+                     filepath, len(self.nodes), len(self.synapses))
+
+    def load(self, filepath: str) -> None:
+        """Load state from binary (msgpack) or JSON.
+
+        Tries binary first (.msgpack), falls back to JSON (.json).
+        If loading JSON into Rust core, migrates via import_state.
+
+        Args:
+            filepath: Path to the state file (.json or .msgpack).
+        """
+        import os
+
+        bin_path = filepath.replace(".json", ".msgpack")
+
+        if self._core is not None:
+            # Try binary first
+            if os.path.exists(bin_path):
+                self._core.load_binary(bin_path)
+                logger.info("NG-Lite state loaded (binary) from %s", bin_path)
+                return
+            # JSON migration — read JSON, import into Rust core, then
+            # save binary so next load is native
+            if os.path.exists(filepath):
+                with open(filepath, "r") as f:
+                    state = json.load(f)
+                self._core.import_state(state)
+                self._core.save_binary(bin_path)
+                logger.info(
+                    "NG-Lite state migrated from JSON to binary: %s → %s",
+                    filepath, bin_path,
+                )
+                return
+
+        # Pure Python fallback
+        if os.path.exists(filepath):
+            with open(filepath, "r") as f:
+                state = json.load(f)
+            self._import_state(state)
+            logger.info("NG-Lite state loaded from %s (%d nodes, %d synapses)",
+                         filepath, len(self.nodes), len(self.synapses))
+
+    def _export_state(self) -> Dict[str, Any]:
+        """Export full state as a serializable dict.
+
+        Synapse keys are converted from (source_id, target_id) tuples
+        to "source_id|target_id" strings for JSON compatibility.
+        """
+        # Convert synapse keys from tuples to strings for JSON
+        synapses_serialized = {}
+        for (src, tgt), syn in self.synapses.items():
+            key = f"{src}|{tgt}"
+            synapses_serialized[key] = asdict(syn)
+
+        # Receptor layer state (#43)
+        receptor_state = {}
+        if self._prototypes is not None:
+            receptor_state = {
+                "prototypes": self._prototypes.tolist(),
+                "prototype_counts": self._prototype_counts.tolist(),
+                "input_count": self._receptor_input_count,
+            }
+
+        return {
+            "version": self.config["snapshot_version"],
+            "module_id": self.module_id,
+            "timestamp": time.time(),
+            "config": self.config,
+            "nodes": {k: self._serialize_node(v) for k, v in self.nodes.items()},
+            "synapses": synapses_serialized,
+            "counters": {
+                "node_id_counter": self._node_id_counter,
+                "total_outcomes": self._total_outcomes,
+                "total_successes": self._total_successes,
+            },
+            "receptor_layer": receptor_state,
+        }
+
+    def _import_state(self, state: Dict[str, Any]) -> None:
+        """Import state from a deserialized dict."""
+        self.module_id = state.get("module_id", self.module_id)
+
+        # Restore config (merge with defaults for forward compatibility).
+        # Preserve constitutional_embeddings from the constructor config —
+        # the live config may have new rim constraints added since the
+        # state was saved, and the saved config should not erase them.
+        saved_config = state.get("config", {})
+        live_constitutional = self.config.get("constitutional_embeddings", [])
+        self.config = {**DEFAULT_CONFIG, **saved_config}
+        if live_constitutional:
+            self.config["constitutional_embeddings"] = live_constitutional
+
+        # Clear caches before rebuild
+        self._embedding_cache.clear()
+        self._history.clear()
+
+        # Restore nodes (rebuild embedding cache from persisted embeddings)
+        self.nodes = {}
+        for key, node_data in state.get("nodes", {}).items():
+            emb_list = node_data.pop("embedding", None)
+            node = NGLiteNode(**node_data)
+            if emb_list is not None:
+                node.embedding = self._normalize(np.array(emb_list, dtype=np.float32))
+                self._embedding_cache[key] = node.embedding
+            self.nodes[key] = node
+
+        # Restore synapses
+        self.synapses = {}
+        for key, syn_data in state.get("synapses", {}).items():
+            parts = key.split("|", 1)
+            if len(parts) == 2:
+                tuple_key = (parts[0], parts[1])
+                self.synapses[tuple_key] = NGLiteSynapse(**syn_data)
+
+        # Restore counters
+        counters = state.get("counters", {})
+        self._node_id_counter = counters.get("node_id_counter", 0)
+        self._total_outcomes = counters.get("total_outcomes", 0)
+        self._total_successes = counters.get("total_successes", 0)
+
+        # Restore receptor layer (#43) — old state files load cleanly (no key)
+        receptor = state.get("receptor_layer", {})
+        if receptor.get("prototypes"):
+            self._prototypes = np.array(receptor["prototypes"], dtype=np.float32)
+            # Re-normalize after deserialization
+            norms = np.linalg.norm(self._prototypes, axis=1, keepdims=True)
+            norms = np.maximum(norms, 1e-12)
+            self._prototypes = self._prototypes / norms
+            self._prototype_counts = np.array(
+                receptor.get("prototype_counts", [0] * len(self._prototypes)),
+                dtype=np.int64,
+            )
+            self._receptor_input_count = receptor.get("input_count", 0)
+        else:
+            self._prototypes = None
+            self._prototype_counts = None
+            self._receptor_input_count = 0
+
+        # Re-seed constitutional nodes after state restore.
+        # Ensures new rim constraints added to config since last save
+        # are picked up, and existing constitutional nodes keep their flag.
+        self._seed_constitutional_nodes()
+
+    # -------------------------------------------------------------------
+    # Dynamic Tuning (Phase 4 — Elmer outward)
+    # -------------------------------------------------------------------
+
+    # Parameters Elmer (or any organ) is permitted to adjust at runtime.
+    # Keys map to (min, max) bounds.  Anything not in this dict is frozen.
+    TUNABLE_PARAMS: Dict[str, Tuple[float, float]] = {
+        "success_boost":              (0.01,  0.50),
+        "failure_penalty":            (0.01,  0.50),
+        "novelty_threshold":          (0.30,  0.95),
+        "pruning_threshold":          (0.001, 0.10),
+        "receptor_ema_alpha":         (0.0001, 0.01),
+        "receptor_prototype_threshold": (0.50, 0.95),
+        "relevance_threshold":        (0.10,  0.70),   # Punchlist #44
+    }
+
+    def update_tunable(self, key: str, value: float) -> Dict[str, Any]:
+        """Update a tunable config parameter at runtime.
+
+        Only parameters listed in TUNABLE_PARAMS are accepted.
+        Values are clamped to their declared bounds.
+
+        Returns dict with old_value, new_value, clamped (bool).
+        Raises KeyError if key is not tunable.
+        """
+        # Update Rust core if present
+        if self._core is not None:
+            try:
+                self._core.update_config(key, float(value))
+            except Exception:
+                pass  # Rust core may not have this key yet
+
+        if key not in self.TUNABLE_PARAMS:
+            raise KeyError(
+                f"'{key}' is not a tunable parameter. "
+                f"Allowed: {sorted(self.TUNABLE_PARAMS.keys())}"
+            )
+        lo, hi = self.TUNABLE_PARAMS[key]
+        old_value = self.config[key]
+        clamped = value < lo or value > hi
+        new_value = max(lo, min(hi, float(value)))
+        self.config[key] = new_value
+        logger.info(
+            "Tunable updated: %s %.6f → %.6f%s",
+            key, old_value, new_value,
+            " (clamped)" if clamped else "",
+        )
+
+        # Punchlist #44: push relevance_threshold to connected bridge
+        if key == "relevance_threshold" and self._bridge is not None:
+            if hasattr(self._bridge, 'set_relevance_threshold'):
+                self._bridge.set_relevance_threshold(new_value)
+
+        return {
+            "key": key,
+            "old_value": old_value,
+            "new_value": new_value,
+            "clamped": clamped,
+        }
+
+    def get_tunables(self) -> Dict[str, Dict[str, float]]:
+        """Return current tunable values and their bounds."""
+        result = {}
+        for key, (lo, hi) in self.TUNABLE_PARAMS.items():
+            result[key] = {
+                "value": self.config[key],
+                "min": lo,
+                "max": hi,
+            }
+        return result
+
+    # -------------------------------------------------------------------
+    # Stats & Telemetry
+    # -------------------------------------------------------------------
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Current state statistics.
+
+        Returns a dict suitable for logging, Observatory queries,
+        or display to users. All routing/learning decisions should
+        be queryable per transparency obligations.
+        """
+        synapse_weights = [s.weight for s in self.synapses.values()]
+        return {
+            "version": __version__,
+            "module_id": self.module_id,
+            "node_count": len(self.nodes),
+            "synapse_count": len(self.synapses),
+            "max_nodes": self.config["max_nodes"],
+            "max_synapses": self.config["max_synapses"],
+            "memory_estimate_bytes": self._estimate_memory(),
+            "total_outcomes": self._total_outcomes,
+            "total_successes": self._total_successes,
+            "success_rate": (
+                self._total_successes / self._total_outcomes
+                if self._total_outcomes > 0 else 0.0
+            ),
+            "avg_synapse_weight": (
+                float(np.mean(synapse_weights))
+                if synapse_weights else 0.0
+            ),
+            "bridge_connected": (
+                self._bridge is not None
+                and self._bridge.is_connected()
+            ),
+            "embedding_cache_size": len(self._embedding_cache),
+        }
+
+    # -------------------------------------------------------------------
+    # Internal Methods
+    # -------------------------------------------------------------------
+
+    def _serialize_node(self, node: NGLiteNode) -> Dict[str, Any]:
+        """Serialize a node to a JSON-compatible dict.
+
+        Converts embedding from np.ndarray to list for JSON.
+        Omits embedding key when None (backward-compatible with
+        state files created before embedding persistence).
+        """
+        d = asdict(node)
+        if node.embedding is not None:
+            d["embedding"] = node.embedding.tolist()
+        else:
+            d.pop("embedding", None)
+        return d
+
+    @staticmethod
+    def _normalize(embedding: np.ndarray) -> np.ndarray:
+        """L2-normalize an embedding vector."""
+        norm = np.linalg.norm(embedding)
+        if norm < 1e-12:
+            return embedding
+        return embedding / norm
+
+    def _hash_embedding(self, embedding: np.ndarray) -> str:
+        """Hash embedding to a fixed-size string for fast lookup.
+
+        Uses the first ``hash_dims`` dimensions of the embedding,
+        converted to bytes, then SHA-256 truncated to 32 hex chars.
+        This gives a compact, collision-resistant key.
+        """
+        dims = self.config["hash_dims"]
+        truncated = embedding[:dims]
+        hash_input = truncated.astype(np.float32).tobytes()
+        return hashlib.sha256(hash_input).hexdigest()[:32]
+
+    # -------------------------------------------------------------------
+    # Receptor Layer (#43) — Adaptive Vector Quantization
+    # -------------------------------------------------------------------
+
+    def _snap_to_prototype(self, embedding: np.ndarray) -> np.ndarray:
+        """Snap an input vector to the nearest prototype centroid.
+
+        If receptor layer is not enabled or not yet initialized (still in
+        warmup), returns the input unchanged. Otherwise, finds the nearest
+        prototype above the similarity threshold and returns that prototype's
+        centroid. If no prototype is close enough, returns the input as-is
+        (novel pattern — passes through unquantized).
+
+        The matched prototype drifts toward the input via slow EMA, so
+        prototypes are living tissue that adapts to the input distribution.
+        Birth/death lifecycle is deferred to Elmer.
+
+        Args:
+            embedding: L2-normalized input vector (D,).
+
+        Returns:
+            Either the nearest prototype centroid or the original embedding.
+        """
+        if not self.config.get("receptor_layer_enabled", False):
+            return embedding
+
+        # Warmup phase: accumulate inputs before initializing prototypes
+        self._receptor_input_count += 1
+        if self._prototypes is None:
+            if self._receptor_input_count >= self.config["receptor_warmup_count"]:
+                self._init_prototypes()
+            if self._prototypes is None:
+                return embedding
+
+        # Vectorized cosine similarity against all prototypes
+        threshold = self.config["receptor_prototype_threshold"]
+        similarities = self._prototypes @ embedding  # (K,)
+        best_idx = int(np.argmax(similarities))
+        best_sim = float(similarities[best_idx])
+
+        if best_sim >= threshold:
+            # EMA drift: pull prototype toward input
+            alpha = self.config["receptor_ema_alpha"]
+            self._prototypes[best_idx] = self._normalize(
+                (1.0 - alpha) * self._prototypes[best_idx] + alpha * embedding
+            )
+            self._prototype_counts[best_idx] += 1
+            return self._prototypes[best_idx].copy()
+
+        # No prototype close enough — novel pattern passes through
+        return embedding
+
+    def _init_prototypes(self) -> None:
+        """Initialize prototypes via k-means on existing node embeddings.
+
+        Uses a simple iterative k-means (no external dependencies). If fewer
+        embeddings exist than K, uses all embeddings as prototypes.
+        """
+        if not self._embedding_cache:
+            return
+
+        embeddings = np.stack(list(self._embedding_cache.values()))
+        n = len(embeddings)
+        k = min(self.config["receptor_layer_k"], n)
+
+        if k < 2:
+            return
+
+        # Simple k-means: random init from existing embeddings, 20 iterations
+        rng = np.random.RandomState(42)
+        indices = rng.choice(n, size=k, replace=False)
+        centroids = embeddings[indices].copy()
+
+        for _ in range(20):
+            # Assign each embedding to nearest centroid
+            sims = embeddings @ centroids.T  # (N, K)
+            assignments = np.argmax(sims, axis=1)
+
+            # Recompute centroids
+            new_centroids = np.zeros_like(centroids)
+            for j in range(k):
+                members = embeddings[assignments == j]
+                if len(members) > 0:
+                    new_centroids[j] = members.mean(axis=0)
+                else:
+                    new_centroids[j] = centroids[j]
+
+            # L2-normalize centroids
+            norms = np.linalg.norm(new_centroids, axis=1, keepdims=True)
+            norms = np.maximum(norms, 1e-12)
+            centroids = new_centroids / norms
+
+        self._prototypes = centroids
+        self._prototype_counts = np.zeros(k, dtype=np.int64)
+        logger.info(
+            "Receptor layer initialized: %d prototypes from %d embeddings",
+            k, n,
+        )
+
+    def _find_similar_node(self, embedding: np.ndarray) -> Optional[NGLiteNode]:
+        """Find a node with similar embedding (below novelty threshold).
+
+        Uses vectorized cosine similarity on all cached embeddings for
+        performance (Grok review: batch dot product instead of per-node
+        loop).  Returns the most similar node if its similarity exceeds
+        (1 - novelty_threshold).
+        """
+        threshold = self.config["novelty_threshold"]
+
+        if not self._embedding_cache:
+            return None
+
+        # Vectorized similarity: stack all cached embeddings into a matrix
+        # and compute cosine similarities in one np.dot call.
+        cache_keys = list(self._embedding_cache.keys())
+        cache_matrix = np.stack(list(self._embedding_cache.values()))
+        similarities = cache_matrix @ embedding  # (N,) cosine similarities
+
+        best_idx = int(np.argmax(similarities))
+        best_similarity = float(similarities[best_idx])
+
+        if best_similarity >= (1.0 - threshold):
+            best_hash = cache_keys[best_idx]
+            return self.nodes.get(best_hash)
+
+        return None
+
+    def _get_or_create_synapse(
+        self,
+        source_id: str,
+        target_id: str,
+    ) -> NGLiteSynapse:
+        """Get existing synapse or create a new one with neutral weight."""
+        key = (source_id, target_id)
+        if key in self.synapses:
+            return self.synapses[key]
+
+        if len(self.synapses) >= self.config["max_synapses"]:
+            self._prune_weakest_synapse()
+
+        synapse = NGLiteSynapse(
+            source_id=source_id,
+            target_id=target_id,
+            weight=0.5,  # Neutral initial weight
+            last_updated=time.time(),
+        )
+        self.synapses[key] = synapse
+        return synapse
+
+    def _prune_least_used_node(self) -> None:
+        """Remove the node with the lowest activation count (LRU).
+
+        Constitutional nodes are never pruned — they are the rim.
+        """
+        if not self.nodes:
+            return
+
+        # Find least-used non-constitutional node
+        prunable = [h for h in self.nodes if not self.nodes[h].constitutional]
+        if not prunable:
+            return
+
+        least_hash = min(
+            prunable,
+            key=lambda h: self.nodes[h].activation_count,
+        )
+        least_node = self.nodes[least_hash]
+
+        # Remove associated synapses
+        keys_to_remove = [
+            key for key in self.synapses
+            if key[0] == least_node.node_id
+        ]
+        for key in keys_to_remove:
+            del self.synapses[key]
+
+        # Remove node and cached embedding
+        del self.nodes[least_hash]
+        self._embedding_cache.pop(least_hash, None)
+
+    def _prune_weakest_synapse(self) -> None:
+        """Remove the synapse with the lowest weight."""
+        if not self.synapses:
+            return
+
+        weakest_key = min(
+            self.synapses,
+            key=lambda k: self.synapses[k].weight,
+        )
+        del self.synapses[weakest_key]
+
+    def _record_history(self, entry: Dict[str, Any]) -> None:
+        """Append to bounded history."""
+        entry["timestamp"] = time.time()
+        self._history.append(entry)
+        if len(self._history) > self._history_max:
+            self._history = self._history[-self._history_max:]
+
+    def _estimate_memory(self) -> int:
+        """Rough estimate of memory footprint in bytes.
+
+        Node: ~200 bytes each (dataclass + hash key)
+        Synapse: ~150 bytes each (dataclass + tuple key)
+        Embedding cache: ~embedding_dim * 4 bytes each (float32)
+        """
+        node_bytes = len(self.nodes) * 200
+        synapse_bytes = len(self.synapses) * 150
+        cache_bytes = len(self._embedding_cache) * self.config["embedding_dim"] * 4
+        return node_bytes + synapse_bytes + cache_bytes

requirements.txt

@@ -0,0 +1,5 @@
+transformers>=5.5.0
+torch>=2.0.0
+accelerate>=0.27.0
+onnxruntime>=1.16.0
+tokenizers>=0.15.0

rust_lenia/Cargo.lock

@@ -0,0 +1,270 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "autocfg"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "indoc"
+version = "2.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "79cf5c93f93228cf8efb3ba362535fb11199ac548a09ce117c9b1adc3030d706"
+dependencies = [
+ "rustversion",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.183"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b5b646652bf6661599e1da8901b3b9522896f01e736bad5f723fe7a3a27f899d"
+
+[[package]]
+name = "matrixmultiply"
+version = "0.3.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a06de3016e9fae57a36fd14dba131fccf49f74b40b7fbdb472f96e361ec71a08"
+dependencies = [
+ "autocfg",
+ "rawpointer",
+]
+
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "ndarray"
+version = "0.16.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "882ed72dce9365842bf196bdeedf5055305f11fc8c03dee7bb0194a6cad34841"
+dependencies = [
+ "matrixmultiply",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "portable-atomic",
+ "portable-atomic-util",
+ "rawpointer",
+]
+
+[[package]]
+name = "num-complex"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-integer"
+version = "0.1.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7969661fd2958a5cb096e56c8e1ad0444ac2bbcd0061bd28660485a44879858f"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "numpy"
+version = "0.24.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7cfbf3f0feededcaa4d289fe3079b03659e85c5b5a177f4ba6fb01ab4fb3e39"
+dependencies = [
+ "libc",
+ "ndarray",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "pyo3",
+ "pyo3-build-config",
+ "rustc-hash",
+]
+
+[[package]]
+name = "nuwave_lenia"
+version = "0.2.0"
+dependencies = [
+ "numpy",
+ "pyo3",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49"
+
+[[package]]
+name = "portable-atomic-util"
+version = "0.2.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "091397be61a01d4be58e7841595bd4bfedb15f1cd54977d79b8271e94ed799a3"
+dependencies = [
+ "portable-atomic",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.24.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e5203598f366b11a02b13aa20cab591229ff0a89fd121a308a5df751d5fc9219"
+dependencies = [
+ "cfg-if",
+ "indoc",
+ "libc",
+ "memoffset",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+ "unindent",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.24.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "99636d423fa2ca130fa5acde3059308006d46f98caac629418e53f7ebb1e9999"
+dependencies = [
+ "once_cell",
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.24.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78f9cf92ba9c409279bc3305b5409d90db2d2c22392d443a87df3a1adad59e33"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.24.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b999cb1a6ce21f9a6b147dcf1be9ffedf02e0043aec74dc390f3007047cecd9"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.24.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "822ece1c7e1012745607d5cf0bcb2874769f0f7cb34c4cde03b9358eb9ef911a"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "pyo3-build-config",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rawpointer"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60a357793950651c4ed0f3f52338f53b2f809f32d83a07f72909fa13e4c6c1e3"
+
+[[package]]
+name = "rustc-hash"
+version = "2.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94300abf3f1ae2e2b8ffb7b58043de3d399c73fa6f4b73826402a5c457614dbe"
+
+[[package]]
+name = "rustversion"
+version = "1.0.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
+
+[[package]]
+name = "syn"
+version = "2.0.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unindent"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"

rust_lenia/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "nuwave_lenia"
+version = "0.2.0"
+edition = "2024"
+description = "NuWave Lenia dynamics engine — zero-copy f32 operations on tensor memory"
+license = "MIT"
+
+[lib]
+name = "nuwave_lenia"
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+pyo3 = { version = "0.24", features = ["extension-module"] }
+numpy = "0.24"
+
+[profile.release]
+opt-level = 3
+lto = true

rust_lenia/src/engine.rs

@@ -0,0 +1,255 @@
+//! Lenia Dynamics Engine — zero-copy operations on tensor memory.
+//!
+//! Python passes numpy arrays (which share memory with PyTorch tensors).
+//! Rust operates on the underlying f32 data directly. No copies.
+//! Results are written back to the same memory.
+//!
+//! The hot path per weight matrix:
+//!   1. Convolve with ring kernel → neighborhood potential
+//!   2. Growth function → bell curve centered on target potential
+//!   3. Modulate by activation magnitude
+//!   4. Compute + clamp delta
+//!   5. Apply delta IN PLACE
+//!   6. Clip to bounds
+//!   7. Mass conservation (L1 norm preservation)
+
+use pyo3::prelude::*;
+use numpy::{PyArray1, PyReadonlyArray1, PyArrayMethods};
+use crate::kernel::Kernel2D;
+use std::time::Instant;
+
+/// Result from a full Lenia step across all matrices.
+#[pyclass]
+#[derive(Clone)]
+pub struct LeniaStepResult {
+    #[pyo3(get)]
+    pub total_delta_norm: f64,
+    #[pyo3(get)]
+    pub matrices_processed: usize,
+    #[pyo3(get)]
+    pub matrices_skipped: usize,
+    #[pyo3(get)]
+    pub time_ms: f64,
+    #[pyo3(get)]
+    pub step_count: u64,
+}
+
+/// The Lenia dynamics engine. Operates directly on numpy array memory.
+#[pyclass]
+pub struct RustLeniaEngine {
+    kernel: Kernel2D,
+    growth_mu: f32,
+    growth_sigma: f32,
+    growth_scale: f32,
+    max_weight_delta: f32,
+    weight_clip_min: f32,
+    weight_clip_max: f32,
+    activation_coupling: f32,
+    step_count: u64,
+    total_time_ms: f64,
+    initial_norms: Vec<f64>,
+    /// Reusable scratch buffer for convolution output
+    scratch: Vec<f32>,
+}
+
+#[pymethods]
+impl RustLeniaEngine {
+    #[new]
+    #[pyo3(signature = (
+        kernel_radius = 5,
+        kernel_sigma = 0.8,
+        growth_mu = 0.12,
+        growth_sigma = 0.02,
+        growth_scale = 0.005,
+        max_weight_delta = 0.05,
+        weight_clip_min = -3.0,
+        weight_clip_max = 3.0,
+        activation_coupling = 2.0,
+    ))]
+    pub fn new(
+        kernel_radius: usize,
+        kernel_sigma: f32,
+        growth_mu: f32,
+        growth_sigma: f32,
+        growth_scale: f32,
+        max_weight_delta: f32,
+        weight_clip_min: f32,
+        weight_clip_max: f32,
+        activation_coupling: f32,
+    ) -> Self {
+        RustLeniaEngine {
+            kernel: Kernel2D::new(kernel_radius, kernel_sigma),
+            growth_mu,
+            growth_sigma,
+            growth_scale,
+            max_weight_delta,
+            weight_clip_min,
+            weight_clip_max,
+            activation_coupling,
+            step_count: 0,
+            total_time_ms: 0.0,
+            initial_norms: Vec::new(),
+            scratch: Vec::new(),
+        }
+    }
+
+    /// Process a single weight matrix IN PLACE.
+    ///
+    /// Args:
+    ///   weights: numpy array (flattened f32) — MODIFIED IN PLACE
+    ///   rows: matrix height
+    ///   cols: matrix width
+    ///   activation_mag: activation magnitude for this layer
+    ///   matrix_idx: index for mass conservation tracking
+    ///
+    /// Returns delta_norm for this matrix.
+    pub fn step_single_inplace(
+        &mut self,
+        py: Python<'_>,
+        weights: &Bound<'_, PyArray1<f32>>,
+        rows: usize,
+        cols: usize,
+        activation_mag: f32,
+        matrix_idx: usize,
+    ) -> PyResult<f64> {
+        let n = rows * cols;
+        let min_size = 2 * self.kernel.radius + 1;
+
+        if rows < min_size || cols < min_size {
+            return Ok(0.0);
+        }
+
+        // Get mutable access to the numpy array's data — zero copy
+        let mut weights_rw = unsafe { weights.as_array_mut() };
+        let w_slice = weights_rw.as_slice_mut()
+            .ok_or_else(|| pyo3::exceptions::PyValueError::new_err("Array not contiguous"))?;
+
+        // Initialize norm on first visit
+        while self.initial_norms.len() <= matrix_idx {
+            self.initial_norms.push(0.0);
+        }
+        if self.initial_norms[matrix_idx] == 0.0 {
+            self.initial_norms[matrix_idx] = w_slice.iter().map(|v| v.abs() as f64).sum();
+        }
+
+        // Ensure scratch buffer is large enough
+        if self.scratch.len() < n {
+            self.scratch.resize(n, 0.0);
+        }
+
+        // 1. Convolve — neighborhood potential
+        self.kernel.convolve(w_slice, rows, cols, &mut self.scratch[..n]);
+
+        // 2-5. Growth + modulation + delta + apply — all in one pass
+        let mu = self.growth_mu;
+        let sigma = self.growth_sigma;
+        let scale = self.growth_scale;
+        let max_d = self.max_weight_delta;
+        let clip_min = self.weight_clip_min;
+        let clip_max = self.weight_clip_max;
+
+        let act_scale = if self.activation_coupling > 0.0 && activation_mag > 0.0 {
+            (activation_mag * self.activation_coupling).tanh()
+        } else {
+            1.0
+        };
+
+        let mut delta_sum = 0.0f64;
+
+        for i in 0..n {
+            let p = self.scratch[i];
+            // Growth function: bell curve
+            let g = 2.0 * (-(p - mu).powi(2) / (2.0 * sigma * sigma)).exp() - 1.0;
+            // Modulate + scale + clamp
+            let d = (scale * g * act_scale).clamp(-max_d, max_d);
+            // Apply + clip
+            w_slice[i] = (w_slice[i] + d).clamp(clip_min, clip_max);
+            delta_sum += d.abs() as f64;
+        }
+
+        // 7. Mass conservation — preserve L1 norm
+        let current_norm: f64 = w_slice.iter().map(|v| v.abs() as f64).sum();
+        let target_norm = self.initial_norms[matrix_idx];
+
+        if current_norm > 1e-10 {
+            let factor = (target_norm / current_norm) as f32;
+            for v in w_slice.iter_mut() {
+                *v *= factor;
+            }
+        }
+
+        Ok(delta_sum / n as f64)
+    }
+
+    /// Process all weight matrices in one call.
+    ///
+    /// Args:
+    ///   weight_arrays: list of numpy arrays (each flattened, MODIFIED IN PLACE)
+    ///   shapes: list of (rows, cols) tuples
+    ///   activations: list of activation magnitudes
+    ///
+    /// Returns LeniaStepResult.
+    pub fn step_all_inplace(
+        &mut self,
+        py: Python<'_>,
+        weight_arrays: Vec<Bound<'_, PyArray1<f32>>>,
+        shapes: Vec<(usize, usize)>,
+        activations: Vec<f32>,
+    ) -> PyResult<LeniaStepResult> {
+        let start = Instant::now();
+        let n = weight_arrays.len();
+        let mut total_delta = 0.0f64;
+        let mut processed = 0usize;
+        let mut skipped = 0usize;
+
+        for (i, arr) in weight_arrays.iter().enumerate() {
+            let (rows, cols) = shapes[i];
+            let act = if i < activations.len() { activations[i] } else { 0.0 };
+
+            let delta = self.step_single_inplace(py, arr, rows, cols, act, i)?;
+            if delta > 0.0 {
+                total_delta += delta;
+                processed += 1;
+            } else {
+                skipped += 1;
+            }
+        }
+
+        let elapsed = start.elapsed().as_secs_f64() * 1000.0;
+        self.step_count += 1;
+        self.total_time_ms += elapsed;
+
+        Ok(LeniaStepResult {
+            total_delta_norm: total_delta,
+            matrices_processed: processed,
+            matrices_skipped: skipped,
+            time_ms: elapsed,
+            step_count: self.step_count,
+        })
+    }
+
+    pub fn get_summary(&self) -> (u64, f64, f64) {
+        let avg = if self.step_count > 0 {
+            self.total_time_ms / self.step_count as f64
+        } else {
+            0.0
+        };
+        (self.step_count, self.total_time_ms, avg)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_growth_function_shape() {
+        let mu = 0.12f32;
+        let sigma = 0.02f32;
+        let at_mu = 2.0 * (-(0.0f32).powi(2) / (2.0 * sigma * sigma)).exp() - 1.0;
+        assert!((at_mu - 1.0).abs() < 0.001);
+
+        let far = 2.0 * (-((1.0 - mu) / sigma).powi(2) / 2.0).exp() - 1.0;
+        assert!(far < -0.9);
+    }
+}

rust_lenia/src/kernel.rs

@@ -0,0 +1,118 @@
+//! Lenia spatial kernel — 2D ring-shaped bell curve.
+//!
+//! K(r) = exp(-((r - 0.5) / sigma)^2 / 2)
+//! Center zeroed (a weight doesn't influence itself).
+//! Normalized to sum to 1.
+
+/// Precomputed 2D kernel for convolution.
+pub struct Kernel2D {
+    pub data: Vec<f32>,
+    pub size: usize, // side length = 2*radius + 1
+    pub radius: usize,
+}
+
+impl Kernel2D {
+    /// Create a ring-shaped Lenia kernel.
+    pub fn new(radius: usize, sigma: f32) -> Self {
+        let size = 2 * radius + 1;
+        let mut data = vec![0.0f32; size * size];
+        let r = radius as f32;
+        let mut sum = 0.0f32;
+
+        for iy in 0..size {
+            for ix in 0..size {
+                let dy = iy as f32 - r;
+                let dx = ix as f32 - r;
+                let dist = (dx * dx + dy * dy).sqrt() / r;
+
+                // Ring kernel: peak at dist ~0.5
+                let val = (-(dist - 0.5).powi(2) / (2.0 * sigma * sigma)).exp();
+                data[iy * size + ix] = val;
+                sum += val;
+            }
+        }
+
+        // Zero center
+        data[radius * size + radius] = 0.0;
+        sum -= data[radius * size + radius]; // was already subtracted above since we set it after
+
+        // Recompute sum after zeroing center
+        sum = data.iter().sum();
+
+        // Normalize
+        if sum > 1e-8 {
+            for v in data.iter_mut() {
+                *v /= sum;
+            }
+        }
+
+        Kernel2D { data, size, radius }
+    }
+
+    /// Apply 2D convolution (same-size output, zero-padded).
+    /// input: row-major f32 array of shape (h, w)
+    /// output: same shape, each element = sum of kernel-weighted neighborhood
+    #[inline]
+    pub fn convolve(&self, input: &[f32], h: usize, w: usize, output: &mut [f32]) {
+        let r = self.radius as isize;
+        let ksize = self.size;
+
+        for iy in 0..h {
+            for ix in 0..w {
+                let mut acc = 0.0f32;
+
+                for ky in 0..ksize {
+                    let sy = iy as isize + ky as isize - r;
+                    if sy < 0 || sy >= h as isize {
+                        continue;
+                    }
+
+                    for kx in 0..ksize {
+                        let sx = ix as isize + kx as isize - r;
+                        if sx < 0 || sx >= w as isize {
+                            continue;
+                        }
+
+                        acc += input[sy as usize * w + sx as usize]
+                            * self.data[ky * ksize + kx];
+                    }
+                }
+
+                output[iy * w + ix] = acc;
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_kernel_creation() {
+        let k = Kernel2D::new(3, 1.0);
+        assert_eq!(k.size, 7);
+        assert_eq!(k.data.len(), 49);
+
+        // Center should be zero
+        assert_eq!(k.data[3 * 7 + 3], 0.0);
+
+        // Should sum to ~1.0 (normalized)
+        let sum: f32 = k.data.iter().sum();
+        assert!((sum - 1.0).abs() < 0.01, "Kernel sum: {}", sum);
+    }
+
+    #[test]
+    fn test_convolution() {
+        let k = Kernel2D::new(1, 0.5);
+        // 4x4 input, all ones
+        let input = vec![1.0f32; 16];
+        let mut output = vec![0.0f32; 16];
+
+        k.convolve(&input, 4, 4, &mut output);
+
+        // Interior elements should be ~1.0 (uniform input, normalized kernel)
+        // Edge elements will be less (zero padding)
+        assert!(output[5] > 0.5, "Interior value: {}", output[5]);
+    }
+}

rust_lenia/src/lib.rs

@@ -0,0 +1,24 @@
+//! NuWave Lenia Engine — Rust Core
+//!
+//! Applies Lenia dynamics to transformer weight matrices.
+//! The hot path: 196 weight matrices × (conv2d + growth + conservation) per step.
+//! Python/PyTorch: ~65s. Rust target: <5s.
+//!
+//! The growth function IS the learning rule. No backprop. No loss function.
+//! Each weight neighborhood evolves based on its neighbors' states
+//! and the activation flow through it.
+//!
+//! PyO3 bindings: Python calls step() with flat f32 arrays.
+//! Rust does the math. Returns delta arrays Python applies to tensors.
+
+mod engine;
+mod kernel;
+
+use pyo3::prelude::*;
+
+#[pymodule]
+fn nuwave_lenia(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    m.add_class::<engine::RustLeniaEngine>()?;
+    m.add_class::<engine::LeniaStepResult>()?;
+    Ok(())
+}