Add neural_matrix8 and neural_subleq8io (universal constructor); move dev scripts to tools/

README.md

@@ -5,6 +5,9 @@ tags:
 - neuromorphic
 - computer-architecture
 - turing-complete
+- recurrent-neural-network
+- in-memory-computing
+- self-replication
 - loihi
 - truenorth
 - akida
@@ -32,14 +35,24 @@ variants/neural_computer{8,16,32}_registers.safetensors          16 B memory
 variants/neural_alu{8,16,32}.safetensors                         pure ALU, no memory
 variants/neural_subleq8.safetensors                              one-instruction machine (SUBLEQ)
 variants/neural_rv32.safetensors                                 RV32IM + F-subset RISC-V processor
+variants/neural_matrix8.safetensors                              the CPU as one recurrent ternary matrix stack
+variants/neural_subleq8io.safetensors                            SUBLEQ host for the universal constructor
 ```
 
-Two further machines mark the endpoints of the family, each detailed in
-its own section below: `neural_subleq8`, a Turing-complete one-instruction
-computer whose entire control flow is a single threshold neuron; and
-`neural_rv32`, a RISC-V processor (RV32IM + an F subset) that runs
-stock-compiler C, with dual-issue execution, memory-mapped I/O, and a
-self-referential NEUR opcode.
+Four further machines are detailed in their own sections below, and together
+they carry the family from the smallest possible processor to two results
+about what a threshold network can be. `neural_subleq8` is a Turing-complete
+one-instruction computer whose entire control flow is a single threshold
+neuron. `neural_rv32` is a RISC-V processor (RV32IM plus an F subset) that
+runs stock-compiler C, with dual-issue execution, memory-mapped I/O, and a
+self-referential NEUR opcode. `neural_matrix8` drops the gate graph entirely:
+the whole processor is compiled into a fixed stack of ternary weight matrices
+with a Heaviside step between them, so one clock cycle is one matrix-vector
+product followed by thresholding, exactly what a resistive or photonic
+crossbar computes. And `neural_subleq8io` hosts a universal constructor: a
+program that reads a description of any machine in the family and prints that
+machine's weight file byte for byte, self-reproduction being the case where
+the description is its own.
 
 ---
 
@@ -77,19 +90,19 @@ python eval_all.py --cpu-program variants/                # also run an assemble
 For an interactive walkthrough that exercises Boolean gates, the 8-bit ALU, mod-5 divisibility, and a CPU loop end-to-end:
 
 ```bash
-python play.py                                            # 1 KB demo, runs in seconds
-python play.py --model neural_computer.safetensors        # 64 KB, slower
+python tools/play.py                                      # 1 KB demo, runs in seconds
+python tools/play.py --model neural_computer.safetensors  # 64 KB, slower
 ```
 
 For end-to-end CPU validation (Fibonacci, sum 1..N, bubble sort, self-modifying JMP, all eight conditional jumps, CALL stack semantics, MUL cross-checked against repeated ADD, DIV cross-checked against repeated SUB, a bitwise AND/OR/XOR/SHL/SHR chain, and the architectural flag policy):
 
 ```bash
-python test_cpu.py                                        # default: 1 KB, ~2 s
-python test_cpu.py --model neural_computer.safetensors    # 64 KB canonical, ~2 min
-python test_cpu.py --only fib,sum_n                       # subset of suite
+python tools/test_cpu.py                                     # default: 1 KB, ~2 s
+python tools/test_cpu.py --model neural_computer.safetensors # 64 KB canonical, ~2 min
+python tools/test_cpu.py --only fib,sum_n                    # subset of suite
 ```
 
-Each program is assembled by a small Python assembler (`cpu_programs.py`) and run through the threshold-gated CPU; the driver verifies expected memory contents at HALT.
+Each program is assembled by a small Python assembler (`tools/cpu_programs.py`) and run through the threshold-gated CPU; the driver verifies expected memory contents at HALT.
 
 ---
 
@@ -290,7 +303,7 @@ python build.py --bits 32 -a 6 --apply all         # neural_computer32_addr6.saf
 To regenerate every named variant in one pass:
 
 ```bash
-python build_all.py
+python tools/build_all.py
 ```
 
 This populates `variants/` with all 18 builds, quantizes each one to the smallest signed integer dtype that exactly represents its weights (~4× reduction in tensor data, with file size dominated by the safetensors header on the smaller profiles), verifies the strictly ternary weight invariant (`--ternary --strict`, so a build with any non-ternary weight fails loudly), stamps the `weight_quantization` metadata field, and runs `eval.py` on each as a sanity check.
@@ -334,7 +347,7 @@ Every weight and bias tensor in the canonical model fits in `int8`. The eval pip
 
 The 8-bit arithmetic and ALU tests use strategic sampling rather than the full 65,536-case sweep because exhaustive coverage at 8-bit is feasible but not necessary given that the circuits are constructed gate-by-gate. The 16-bit and 32-bit arithmetic tests sample edge cases only; full exhaustive coverage at those widths is infeasible without specialized hardware.
 
-`eval_all.py` runs the unified suite. Exit code is the number of failing variants (0 means all pass). **Testing is evaluation, not rebuilding**: `python eval_all.py variants/` scores all 18 fitness variants against the shipped weights in about two minutes (~6 s each, the composed float netlists evaluated in `NetlistEvaluator`'s leveled mode) and cleanly skips the two standalone machines. Rebuilding the models (`build_all.py`, ~50 min for all 18) is a separate step, needed only when the circuit constructions in `build.py` change — routine verification never rebuilds. The batched evaluator is population-safe: every chained intermediate (carry, borrow, mux select) is computed per population slot, so `prune_weights.py`'s parallel fitness screens are exact rather than slot-0 approximations.
+`eval_all.py` runs the unified suite. Exit code is the number of failing variants (0 means all pass). **Testing is evaluation, not rebuilding**: `python eval_all.py variants/` scores all 18 fitness variants against the shipped weights in about two minutes (~6 s each, the composed float netlists evaluated in `NetlistEvaluator`'s leveled mode) and cleanly skips the four standalone machines. Rebuilding the models (`tools/build_all.py`, ~50 min for all 18) is a separate step, needed only when the circuit constructions in `build.py` change; routine verification never rebuilds. The batched evaluator is population-safe: every chained intermediate (carry, borrow, mux select) is computed per population slot, so `tools/prune_weights.py`'s parallel fitness screens are exact rather than slot-0 approximations.
 
 ---
 
@@ -381,6 +394,110 @@ The composed circuits evaluate in a leveled mode (`NetlistEvaluator`, one padded
 
 ---
 
+## neural_matrix8 — the processor as one recurrent threshold network
+
+Every machine above is a graph of individually-named gates. `neural_matrix8`
+is the same processor with the graph dissolved: the verified gate wiring of
+the registers-profile CPU (8-bit data, 4-bit addresses, 16 B of memory) is
+compiled into a fixed sequence of ternary weight matrices `W1..Wk` with a
+Heaviside step between them, acting on a single state vector that holds the
+program counter, all four registers, the flags, the stack pointer, the halt
+bit, and every memory bit:
+
+```
+[ PC[4] | R0[8] R1[8] R2[8] R3[8] | Z N C V | SP[4] | HALT | MEM[16][8] ]   = 173 bits
+```
+
+One instruction is one pass through the stack, `s' = H(Wk · … H(W1·s + b1) …
++ bk)`; the machine is that stack iterated until the halt bit sets, so the
+whole processor is a single recurrent linear-threshold network. The
+transition is total: a halted state is a fixed point (every architectural
+write is gated by NOT halt), so iterating past HALT is harmless.
+
+- **Ternary and small-integer, end to end.** The step circuit is assembled
+  from the family's verified cells (two-layer OR/NAND XOR, ripple-carry full
+  adders, bit-cascade comparators, restoring-division stages, 2:1 muxes,
+  one-gate address-decode rows), then levelized with identity pass-throughs
+  carrying live signals forward. It compiles to 108 matrices whose every
+  entry is in `{-1, 0, 1}` with small integer biases (~9.1 MB on disk).
+- **Equality is machine-checked bit for bit,** not sampled: all 65,536 `(a,
+  b)` operand pairs for each of the ten ALU opcodes (ADD SUB AND OR XOR SHL
+  SHR MUL DIV CMP) batched through the matrices against an integer reference;
+  the full Jcc × flag, JMP, CALL, and LOAD/STORE control space; 2,000 uniformly
+  random full states plus 500 halted-state fixed points; and per-instruction
+  full-state lockstep against the gate-graph `GenericThresholdCPU` walking the
+  shipped `neural_computer8_registers` weights.
+- **Analog realization.** Pre-activations are integers; a firing gate sits at
+  `>= 0` and a non-firing gate at `<= -1`, so a comparator threshold at `-0.5`
+  gives every gate a guaranteed noise margin of exactly 0.5 (measured minimum
+  over random states: 0.500). Any total analog error below 0.5 per
+  pre-activation therefore reproduces the digital circuit bit for bit. Each
+  matrix maps to a crossbar with conductances drawn from `{-1, 0, +1}` and one
+  clock cycle is one analog matrix-vector product followed by thresholding;
+  the suite injects Gaussian read noise (bit-exact through σ ≈ 0.10, breaking
+  down near σ = 0.15 exactly where the error model predicts) and static
+  conductance mismatch (bit-exact through σ_G = 0.10).
+
+```bash
+python matrix8.py build          # compile + save variants/neural_matrix8.safetensors
+python matrix8.py verify         # exhaustive equality vs the gate graph and integer reference
+python matrix8.py analog         # margin measurement + read-noise + conductance-mismatch sweeps
+```
+
+Because the transition is a fixed matrix stack proven equal to the gate-graph
+processor, the ISA semantics carry over unchanged, and the digital circuit and
+its analog crossbar realization coincide within the device's quantization and
+noise margins. The processor is no longer *described by* a neural network; it
+*is* one, iterated.
+
+---
+
+## neural_subleq8io and the universal constructor — a machine that prints itself
+
+`neural_subleq8io` is the one-instruction machine extended with three
+memory-mapped device cells (a tape-input byte, an input strobe, and an output
+byte). The device logic lives in the runtime, exactly as `neural_rv32`'s
+console does; the processor's gates are unchanged, 194 of them. On this host
+runs the **universal constructor**: a 21-instruction SUBLEQ program that reads
+a *construction recipe* off the tape and emits a safetensors file one byte at
+a time.
+
+`describe(file_bytes)` compiles any file in the family into a recipe; running
+the constructor on that recipe emits the file back byte for byte. The
+constructor is therefore universal, and the description selects what is built.
+Self-reproduction is the single case where the description handed to the
+constructor is that of the running machine: the program's output stream is
+then the byte-for-byte safetensors file of the host itself.
+
+The equality is machine-checked rather than observed on one run:
+
+- the recipe codec round-trips every file in the family (all 23 shipped
+  `.safetensors`, 551 MB, byte-identical and sha-verified);
+- the constructor program is executed on three independently-verified
+  backends — a pure-integer reference, the gate-graph `SubleqThresholdCPU`
+  walking the shipped netlist, and the host itself compiled to recurrent
+  ternary matrices by `matrix8`'s compiler — and they agree cycle for cycle;
+- **full self-reproduction runs entirely on the threshold matrices:** the host
+  compiles to 34 ternary layers, and generation 1 emits all 95,306 bytes of
+  its own weight file in 359,743 recurrences, each output byte asserted
+  against the target as it streams, ending on an sha match and an instruction
+  count identical to the reference;
+- the offspring file then boots as generation 2 and reconstructs itself,
+  closing the loop across two generations.
+
+```bash
+python constructor8.py build     # emit variants/neural_subleq8io.safetensors
+python constructor8.py verify    # host soundness + codec round-trip + constructor on all 3 backends
+python constructor8.py self      # full self-reproduction on the threshold matrices, then gen-2 boot
+```
+
+A program running on the processor emits the exact tensor file that defines
+that processor, and builds any other machine in the family from a description
+of it: von Neumann's universal constructor, realized as ternary threshold
+weights and checked to the byte.
+
+---
+
 ## Threshold logic
 
 A threshold gate computes a Boolean function by taking a weighted sum of binary inputs and comparing the result to a threshold; the output is 1 when the sum meets or exceeds the threshold and 0 otherwise. Equivalently, it is a neuron with Heaviside step activation, integer weights, and an integer bias.
@@ -553,18 +670,22 @@ Loss components: BCE on output bits, BCE on extracted A and B bits (2× weight),
 
 ```
 neural_computer.safetensors         canonical model (32-bit, 64 KB, ~8.61M params)
-variants/                           18 prebuilt configurations + neural_subleq8 + neural_rv32
+variants/                           18 fitness variants + 4 standalone machines
+                                    (neural_subleq8, neural_rv32, neural_matrix8, neural_subleq8io)
 build.py                            generator (one safetensors per invocation; also `subleq`, `rv32`)
-build_all.py                        builds, quantizes (--ternary --strict), and verifies every profile
 quantize.py                         min integer dtypes + ternary verification/repair
-eval.py                             gate-level fitness suite, NetlistEvaluator, 64 KB reference CPU
+eval.py                             gate-level fitness suite, NetlistEvaluator, float oracles, reference CPU
 eval_all.py                         variant-agnostic harness + manifest-sized threshold CPU
-cpu_programs.py                     assembler + ten-program suite for CPU-level validation
-test_cpu.py                         runs the program suite against a chosen variant
 machines.py                         neural_subleq8 + neural_rv32 runtimes, references, assemblers,
-                                    RV32 object loader, and both test suites (subleq / rv32 / rv32-c)
-play.py                             interactive demo
-prune_weights.py                    GPU-batched weight reduction with conflict resolution
+                                    RV32 object loader, and the test suites (subleq / rv32 / rv32-c)
+matrix8.py                          compiles the CPU to a recurrent ternary matrix stack; the
+                                    exhaustive equality suite and the analog crossbar simulation
+constructor8.py                     the neural_subleq8io host, the recipe codec, and the universal
+                                    constructor / self-reproduction suite
+tools/                              build_all.py (build + quantize + verify every profile),
+                                    cpu_programs.py (assembler + CPU program suite), test_cpu.py
+                                    (program suite vs a variant), play.py (interactive demo),
+                                    prune_weights.py (GPU-batched weight reduction)
 llm_integration/                    SmolLM2 extractor + circuit wrapper + training code
   ├── circuits.py                   FrozenThresholdCircuits (loads safetensors, exposes
   │                                 add_8bit / sub_8bit / mul_8bit / compare_*)

constructor8.py

@@ -0,0 +1,646 @@
+"""neural_subleq8io + the universal constructor.
+
+The host is the family's one-instruction machine extended with three
+memory-mapped device cells (all device logic lives in the runtimes, exactly
+like neural_rv32's console at 0xFF00; the processor's gates are unchanged):
+
+    0xFD  IN_DATA    reads as the current tape byte (device-refreshed)
+    0xFC  IN_STROBE  any write advances the tape head (device clears to 0)
+    0xFE  OUT        any write emits the written byte (device clears to 0)
+
+A 21-instruction SUBLEQ program — the constructor — interprets a construction
+recipe streamed on the tape:
+
+    tag 0            END
+    tag 1..127       literal record: the next `tag` tape bytes, each stored
+                     negated mod 256, are emitted one per SUBLEQ instruction
+                     (M[0xFE] = 0 - M[0xFD] recovers the byte)
+    tag 129..255     repeat record: the next tape byte (negated value) is
+                     emitted 256-tag times without strobing (tag 128 unused)
+
+`describe(file_bytes)` compiles any safetensors file in the family into a
+recipe; the constructor run on that recipe emits the file byte for byte, so
+the constructor is universal and the description selects what is built.
+Self-reproduction is the case where the description handed to the constructor
+is that of the running machine: the program's output stream is the
+byte-for-byte safetensors file of the host itself.
+
+The equality is machine-checked rather than observed on a single run:
+  - the recipe codec round-trips every family file (byte equality + sha256);
+  - the constructor program is executed on three proven-equal backends
+    (pure-integer reference, the gate-graph SubleqThresholdCPU walking the
+    shipped netlist, and the host compiled to recurrent ternary matrices with
+    matrix8's compiler) with cycle-lockstep spot checks between them;
+  - the full self-reproduction runs at threshold fidelity on the matrix
+    backend, and the emitted stream must equal the host's file exactly;
+  - the offspring file then boots as generation 2 and reproduces again.
+
+Usage:
+    python constructor8.py build     # emit variants/neural_subleq8io.safetensors
+    python constructor8.py verify   # host soundness + codec + constructor runs
+    python constructor8.py self     # full self-reproduction at threshold fidelity
+    python constructor8.py all
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import sys
+import time
+from typing import Dict, List, Optional, Tuple
+
+import torch
+from safetensors import safe_open
+from safetensors.torch import save_file
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+REPO = os.path.dirname(os.path.abspath(__file__))
+MODEL_PATH = os.path.join(REPO, "variants", "neural_subleq8io.safetensors")
+
+from matrix8 import Net, compile_net  # machine-1 compiler, reused verbatim
+
+IN_DATA, IN_STROBE, OUT = 0xFD, 0xFC, 0xFE
+HALT_PC = 0xFF
+
+
+# =============================================================================
+# Build the host file (family per-gate style, .inputs wiring, ternary strict)
+# =============================================================================
+
+def build_host(save: bool = True) -> str:
+    import build as B
+    from quantize import quantize_tensors
+
+    tensors: Dict[str, torch.Tensor] = {}
+    B.add_decoder(tensors, 8, 256)
+    B.add_memory_read_mux(tensors, 256)
+    B.add_memory_write_cells(tensors, 256)
+    B.add_subleq_core(tensors)
+    tensors["manifest.data_bits"] = torch.tensor([8.0])
+    tensors["manifest.addr_bits"] = torch.tensor([8.0])
+    tensors["manifest.memory_bytes"] = torch.tensor([256.0])
+    tensors["manifest.pc_width"] = torch.tensor([8.0])
+    tensors["manifest.version"] = torch.tensor([4.0])
+    tensors, reg, stats = B.build_inputs(tensors)
+    tensors, counts, _, _ = quantize_tensors(tensors, ternary=False)
+    for k, t in tensors.items():
+        if k.endswith(".weight") and not k.startswith("manifest."):
+            tf = t.float() if t.dtype.is_floating_point else t.to(torch.float32)
+            assert (tf.abs() <= 1).all(), f"non-ternary weight {k}"
+    meta = {
+        "machine": "subleq8io",
+        "weight_quantization": "ternary",
+        "signal_registry": reg.to_metadata(),
+        "io": json.dumps({"in_data": IN_DATA, "in_strobe": IN_STROBE,
+                          "out": OUT, "halt_pc": HALT_PC}),
+    }
+    if save:
+        save_file(tensors, MODEL_PATH, metadata=meta)
+        sz = os.path.getsize(MODEL_PATH)
+        print(f"  built {MODEL_PATH}: {stats['added']} wired gates, "
+              f"{len(tensors)} tensors, {sz:,} bytes")
+    return MODEL_PATH
+
+
+# =============================================================================
+# Recipe codec (the construction-description language)
+# =============================================================================
+
+def describe(data: bytes) -> bytes:
+    """Compile raw bytes into a construction recipe for the constructor."""
+    tape = bytearray()
+    i, n = 0, len(data)
+    while i < n:
+        j = i
+        while j < n and data[j] == data[i] and j - i < 127:
+            j += 1
+        if j - i >= 4:
+            tape.append(256 - (j - i))              # repeat tag 129..252
+            tape.append((256 - data[i]) % 256)      # value, negated
+            i = j
+            continue
+        k = i
+        while k < n and k - i < 127:                # literal until a run starts
+            m = k
+            while m < n and data[m] == data[k] and m - k < 4:
+                m += 1
+            if m - k >= 4:
+                break
+            k += 1
+        k = max(k, i + 1)
+        tape.append(k - i)                          # literal tag 1..127
+        tape.extend((256 - x) % 256 for x in data[i:k])
+        i = k
+    tape.append(0)                                  # END
+    return bytes(tape)
+
+
+def decode(tape: bytes) -> bytes:
+    """Pure-Python reference semantics of the recipe language."""
+    out = bytearray()
+    i = 0
+    while True:
+        t = tape[i]
+        i += 1
+        if t == 0:
+            return bytes(out)
+        if t <= 127:
+            for _ in range(t):
+                out.append((256 - tape[i]) % 256)
+                i += 1
+        else:
+            out.extend([(256 - tape[i]) % 256] * (256 - t))
+            i += 1
+
+
+# =============================================================================
+# The constructor program (21 SUBLEQ instructions + 4 variable cells)
+# =============================================================================
+
+Z, ONE, T1, T2 = 0xF0, 0xF1, 0xF2, 0xF3
+
+CONSTRUCTOR = [
+    # main loop: read tag T; T1 = -T (== run length for repeat tags), T2 = T
+    (T2, T2, 0x03),          # 00  T2 = 0
+    (T1, T1, 0x06),          # 03  T1 = 0
+    (IN_DATA, T1, 0x09),     # 06  T1 = -T
+    (Z, IN_STROBE, 0x0C),    # 09  consume tag byte
+    (T1, T2, 0x0F),          # 0C  T2 = T
+    (Z, T2, 0x15),           # 0F  if T == 0 or T >= 128 -> 15, else literal
+    (Z, Z, 0x24),            # 12  goto LITERAL
+    (Z, T1, 0x1B),           # 15  T1 = -T: leq only when T == 0 -> END
+    (Z, Z, 0x30),            # 18  goto REPEAT (T1 holds 256-T = run length)
+    (Z, Z, HALT_PC),         # 1B  END: halt
+    (Z, Z, 0x21),            # 1E  (pad)
+    (Z, Z, 0x24),            # 21  (pad)
+    (IN_DATA, OUT, 0x27),    # 24  LITERAL: emit 0 - tape_byte
+    (Z, IN_STROBE, 0x2A),    # 27  consume it
+    (ONE, T2, 0x00),         # 2A  T2 -= 1; done -> main loop
+    (Z, Z, 0x24),            # 2D  next literal byte
+    (IN_DATA, OUT, 0x33),    # 30  REPEAT: emit 0 - value (no strobe)
+    (ONE, T1, 0x39),         # 33  T1 -= 1; done -> 39
+    (Z, Z, 0x30),            # 36  emit again
+    (Z, IN_STROBE, 0x3C),    # 39  consume the value byte
+    (Z, Z, 0x00),            # 3C  goto main loop
+]
+
+
+def constructor_image() -> List[int]:
+    mem = [0] * 256
+    for idx, (a, b, c) in enumerate(CONSTRUCTOR):
+        mem[idx * 3] = a
+        mem[idx * 3 + 1] = b
+        mem[idx * 3 + 2] = c
+    mem[ONE] = 1
+    return mem
+
+
+# =============================================================================
+# Backend 1: fast pure-integer reference with devices
+# =============================================================================
+
+def ref_construct(tape: bytes, max_steps: int = 1 << 34,
+                  ) -> Tuple[bytes, int]:
+    mem = constructor_image()
+    mem[IN_DATA] = tape[0] if tape else 0
+    out = bytearray()
+    head = 0
+    pc = 0
+    steps = 0
+    tn = len(tape)
+    while pc != HALT_PC and steps < max_steps:
+        A = mem[pc]
+        Bc = mem[(pc + 1) & 0xFF]
+        C = mem[(pc + 2) & 0xFF]
+        r = (mem[Bc] - mem[A]) & 0xFF
+        mem[Bc] = r
+        pc = C if (r == 0 or r >= 0x80) else (pc + 3) & 0xFF
+        if Bc == OUT:
+            out.append(r)
+            mem[OUT] = 0
+        elif Bc == IN_STROBE:
+            head += 1
+            mem[IN_STROBE] = 0
+            mem[IN_DATA] = tape[head] if head < tn else 0
+        steps += 1
+    return bytes(out), steps
+
+
+# =============================================================================
+# Backend 2: the gate-graph processor (shipped netlist) with devices
+# =============================================================================
+
+class GateHost:
+    def __init__(self, path: str = MODEL_PATH):
+        from machines import SubleqThresholdCPU, load_tensors
+        from eval import load_metadata
+        T = load_tensors(path)
+        reg = load_metadata(path)["signal_registry"]
+        self.cpu = SubleqThresholdCPU(T, reg)
+
+    def run(self, tape: bytes, max_steps: int) -> Tuple[bytes, int, dict]:
+        s = {"pc": 0, "mem": constructor_image(), "halted": False}
+        s["mem"][IN_DATA] = tape[0] if tape else 0
+        out = bytearray()
+        head = 0
+        n = 0
+        while not s["halted"] and n < max_steps:
+            Bc = s["mem"][(s["pc"] + 1) & 0xFF]
+            s = self.cpu.step(s)
+            if Bc == OUT:
+                out.append(s["mem"][OUT])
+                s["mem"][OUT] = 0
+            elif Bc == IN_STROBE:
+                head += 1
+                s["mem"][IN_STROBE] = 0
+                s["mem"][IN_DATA] = tape[head] if head < len(tape) else 0
+            n += 1
+        return bytes(out), n, s
+
+
+# =============================================================================
+# Backend 3: the host compiled to recurrent ternary matrices (machine 1 tech)
+# =============================================================================
+
+def subleq_state_names() -> List[str]:
+    names = [f"pc{i}" for i in range(8)] + ["halt"]
+    for j in range(256):
+        names += [f"m{j}b{i}" for i in range(8)]
+    return names
+
+
+def build_subleq_step_net() -> Tuple[Net, List[str], List[str]]:
+    net = Net()
+    pc = [f"pc{i}" for i in range(8)]
+    halt = "halt"
+    mem = [[f"m{j}b{i}" for i in range(8)] for j in range(256)]
+
+    P = [net.DECODE(f"pd{j}", pc, j) for j in range(256)]
+    byte = []
+    for o in range(3):                     # A, B, C operand bytes
+        bo = [net.OR(f"f{o}b{bit}",
+                     [net.AND(f"f{o}a{j}b{bit}", [mem[j][bit], P[(j - o) % 256]])
+                      for j in range(256)]) for bit in range(8)]
+        byte.append(bo)
+    A, Bb, C = byte
+
+    AD = [net.DECODE(f"ad{j}", A, j) for j in range(256)]
+    BD = [net.DECODE(f"bd{j}", Bb, j) for j in range(256)]
+    x = [net.OR(f"x{bit}", [net.AND(f"x{bit}a{j}", [mem[j][bit], AD[j]])
+                            for j in range(256)]) for bit in range(8)]
+    y = [net.OR(f"y{bit}", [net.AND(f"y{bit}a{j}", [mem[j][bit], BD[j]])
+                            for j in range(256)]) for bit in range(8)]
+
+    nx = [net.NOT(f"nx{k}", x[7 - k]) for k in range(8)]     # LSB-first
+    c = "#1"
+    r_l = []
+    for k in range(8):
+        s_, c = net.FA(f"sub.fa{k}", y[7 - k], nx[k], c)
+        r_l.append(s_)
+    r = [r_l[7 - i] for i in range(8)]
+
+    zero = net.NOR("rzero", r)
+    leq = net.OR("leq", [r[0], zero])
+
+    pc_l = [pc[7 - k] for k in range(8)]
+    c = "#0"
+    p3_l = []
+    for k in range(8):
+        addend = "#1" if k in (0, 1) else "#0"
+        s_, c = net.FA(f"pc3.fa{k}", pc_l[k], addend, c)
+        p3_l.append(s_)
+    p3 = [p3_l[7 - i] for i in range(8)]
+
+    pcm = [net.MUX(f"pcm{i}", leq, C[i], p3[i]) for i in range(8)]
+    pcn = [net.MUX(f"pcn{i}", halt, pc[i], pcm[i]) for i in range(8)]
+    hdec = net.DECODE("hdec", pcn, HALT_PC)
+    halt_n = net.OR("haltn", [halt, hdec])
+
+    nh = net.NOT("nh", halt)
+    mem_n = []
+    for j in range(256):
+        ws = net.AND(f"ws{j}", [BD[j], nh])
+        nws = net.NOT(f"nws{j}", ws)
+        row = [net.OR(f"mn{j}b{bit}",
+                      [net.AND(f"mn{j}b{bit}o", [mem[j][bit], nws]),
+                       net.AND(f"mn{j}b{bit}n", [r[bit], ws])])
+               for bit in range(8)]
+        mem_n.append(row)
+
+    outputs = pcn + [halt_n] + [s for row in mem_n for s in row]
+    return net, subleq_state_names(), outputs
+
+
+class MatrixHost:
+    """The subleq8io processor as a recurrent ternary linear-threshold
+    network, with the device cells poked between recurrences."""
+
+    N = 8 + 1 + 2048
+
+    def __init__(self, device: str = "cpu"):
+        t0 = time.perf_counter()
+        net, inputs, outputs = build_subleq_step_net()
+        layers, info = compile_net(net, inputs, outputs)
+        for W, Bt in layers:
+            vals = set(torch.unique(W).tolist())
+            assert vals <= {-1, 0, 1}
+        self.W = [W.to(device=device, dtype=torch.float32) for W, _ in layers]
+        self.B = [Bt.to(device=device, dtype=torch.float32) for _, Bt in layers]
+        self.device = device
+        self.info = info
+        print(f"  host compiled to {info['layers']} ternary matrices "
+              f"(max width {info['max_width']}, "
+              f"{info['total_weights']:,} weights) in "
+              f"{time.perf_counter() - t0:.1f}s on {device}")
+
+    def _vec(self, pc: int, mem: List[int], halt: bool = False) -> torch.Tensor:
+        v = torch.zeros(self.N)
+        for k in range(8):
+            v[k] = (pc >> (7 - k)) & 1
+        v[8] = 1.0 if halt else 0.0
+        for j in range(256):
+            for k in range(8):
+                v[9 + j * 8 + k] = (mem[j] >> (7 - k)) & 1
+        return v
+
+    def step(self, v: torch.Tensor) -> torch.Tensor:
+        for W, b in zip(self.W, self.B):
+            v = ((v @ W.T + b) >= 0).float()
+        return v
+
+    @staticmethod
+    def _byte(vcpu: torch.Tensor, j: int) -> int:
+        x = 0
+        for k in range(8):
+            x = (x << 1) | int(vcpu[9 + j * 8 + k])
+        return x
+
+    def run(self, tape: bytes, max_steps: int, expect: Optional[bytes] = None,
+            report_every: int = 100000) -> Tuple[bytes, int]:
+        mem = constructor_image()
+        mem[IN_DATA] = tape[0] if tape else 0
+        v = self._vec(0, mem).unsqueeze(0).to(self.device)
+        out = bytearray()
+        head = 0
+        n = 0
+        idx_pch = torch.arange(0, 9, device=self.device)
+        t0 = time.perf_counter()
+        while n < max_steps:
+            front = v[0, idx_pch].tolist()
+            if front[8] >= 0.5:
+                break
+            pcv = 0
+            for k in range(8):
+                pcv = (pcv << 1) | int(front[k])
+            bidx = (pcv + 1) & 0xFF
+            bbits = v[0, 9 + bidx * 8: 9 + bidx * 8 + 8].tolist()
+            Bc = 0
+            for k in range(8):
+                Bc = (Bc << 1) | int(bbits[k])
+            v = self.step(v)
+            n += 1
+            if Bc == OUT:
+                ob = v[0, 9 + OUT * 8: 9 + OUT * 8 + 8].tolist()
+                val = 0
+                for k in range(8):
+                    val = (val << 1) | int(ob[k])
+                out.append(val)
+                if expect is not None and out[-1] != expect[len(out) - 1]:
+                    raise AssertionError(
+                        f"stream diverged at byte {len(out) - 1}: "
+                        f"got {out[-1]:#04x} want {expect[len(out) - 1]:#04x}")
+                v[0, 9 + OUT * 8: 9 + OUT * 8 + 8] = 0.0
+            elif Bc == IN_STROBE:
+                head += 1
+                v[0, 9 + IN_STROBE * 8: 9 + IN_STROBE * 8 + 8] = 0.0
+                nxt = tape[head] if head < len(tape) else 0
+                for k in range(8):
+                    v[0, 9 + IN_DATA * 8 + k] = float((nxt >> (7 - k)) & 1)
+            if report_every and n % report_every == 0:
+                rate = n / (time.perf_counter() - t0)
+                print(f"    ... {n:,} recurrences, {len(out):,} bytes emitted "
+                      f"({rate:,.0f} instr/s)")
+        return bytes(out), n
+
+    def exhaustive_datapath(self) -> bool:
+        """All 65,536 (x, y) operand pairs through the matrices in one batch."""
+        xs = torch.arange(65536) % 256
+        ys = torch.arange(65536) // 256
+        V = torch.zeros(65536, self.N)
+        mem = [0] * 256
+        mem[0], mem[1], mem[2] = 0x90, 0x91, 0x30
+        v0 = self._vec(0, mem)
+        V[:] = v0
+        for k in range(8):
+            V[:, 9 + 0x90 * 8 + k] = ((xs >> (7 - k)) & 1).float()
+            V[:, 9 + 0x91 * 8 + k] = ((ys >> (7 - k)) & 1).float()
+        V = V.to(self.device)
+        for W, b in zip(self.W, self.B):
+            V = ((V @ W.T + b) >= 0).float()
+        V = V.cpu()
+        r = torch.zeros(65536, dtype=torch.long)
+        for k in range(8):
+            r = (r << 1) | V[:, 9 + 0x91 * 8 + k].long()
+        pcv = torch.zeros(65536, dtype=torch.long)
+        for k in range(8):
+            pcv = (pcv << 1) | V[:, k].long()
+        exp_r = (ys - xs) & 0xFF
+        exp_leq = (exp_r == 0) | (exp_r >= 0x80)
+        exp_pc = torch.where(exp_leq, torch.full_like(pcv, 0x30),
+                             torch.full_like(pcv, 3))
+        ok = bool((r == exp_r).all()) and bool((pcv == exp_pc).all())
+        print(f"  {'OK ' if ok else 'FAIL'} matrix datapath exhaustive: "
+              f"65,536/65,536 subtract results and branch decisions exact")
+        return ok
+
+
+# =============================================================================
+# Verification
+# =============================================================================
+
+def sha(b: bytes) -> str:
+    return hashlib.sha256(b).hexdigest()[:16]
+
+
+def family_files() -> List[str]:
+    files = [os.path.join(REPO, "neural_computer.safetensors")]
+    vdir = os.path.join(REPO, "variants")
+    files += sorted(os.path.join(vdir, f) for f in os.listdir(vdir)
+                    if f.endswith(".safetensors"))
+    return files
+
+
+def verify(device: str) -> bool:
+    ok = True
+
+    print("\n[1/5] Host machine soundness (shipped netlist, exhaustive datapath)")
+    from eval import NetlistEvaluator, load_metadata
+    from machines import load_tensors
+    T = load_tensors(MODEL_PATH)
+    reg = load_metadata(MODEL_PATH)["signal_registry"]
+    ne = NetlistEvaluator(T, reg, "subleq")
+    a_v = torch.arange(65536) % 256
+    b_v = torch.arange(65536) // 256
+    ext = {}
+    for k in range(8):
+        ext[f"$a[{k}]"] = ((a_v >> k) & 1).float()
+        ext[f"$b[{k}]"] = ((b_v >> k) & 1).float()
+        ext[f"$pc[{k}]"] = torch.zeros(65536)
+        ext[f"$c[{k}]"] = torch.zeros(65536)
+    o = ne.run(ext)
+    rr = sum(o[f"subleq.sub.fa{k}.ha2.sum.layer2"][:, 0].long() << k for k in range(8))
+    lq = o["subleq.leq"][:, 0].long()
+    exp_r = (b_v - a_v) & 0xFF
+    exp_l = ((exp_r == 0) | (exp_r >= 128)).long()
+    good = bool((rr == exp_r).all()) and bool((lq == exp_l).all())
+    print(f"  {'OK ' if good else 'FAIL'} gate netlist exhaustive: 65,536/65,536 exact")
+    ok &= good
+
+    print("\n[2/5] Recipe codec round-trip over the whole family")
+    total = 0
+    for p in family_files():
+        data = open(p, "rb").read()
+        tape = describe(data)
+        good = decode(tape) == data
+        ok &= good
+        total += len(data)
+        print(f"  {'OK ' if good else 'FAIL'} {os.path.basename(p):<44} "
+              f"{len(data):>10,} B -> tape {len(tape):>10,} B  sha {sha(data)}")
+    print(f"  ({total / 1e6:.0f} MB described and decoded back, byte-identical)")
+
+    print("\n[3/5] Constructor program on the integer reference "
+          "(output stream == target file, byte for byte)")
+    targets = [MODEL_PATH,
+               os.path.join(REPO, "variants", "neural_subleq8.safetensors"),
+               os.path.join(REPO, "variants", "neural_matrix8.safetensors")]
+    for p in targets:
+        data = open(p, "rb").read()
+        tape = describe(data)
+        t0 = time.perf_counter()
+        out, steps = ref_construct(tape)
+        dt = time.perf_counter() - t0
+        good = out == data
+        ok &= good
+        tag = "SELF-REPRODUCTION" if p == MODEL_PATH else "universal build"
+        print(f"  {'OK ' if good else 'FAIL'} {os.path.basename(p):<40} "
+              f"{len(out):>10,} B in {steps:>12,} instructions ({dt:.1f}s)  "
+              f"[{tag}] sha {sha(out)}")
+
+    print("\n[4/5] Matrix backend (machine-1 compile of the host)")
+    mh = MatrixHost(device=device)
+    ok &= mh.exhaustive_datapath()
+
+    print("\n[5/5] Backend lockstep on a shared prefix "
+          "(gate graph vs matrices vs reference, first 600 cycles)")
+    data = open(MODEL_PATH, "rb").read()
+    tape = describe(data)
+    gh = GateHost()
+    s = {"pc": 0, "mem": constructor_image(), "halted": False}
+    s["mem"][IN_DATA] = tape[0]
+    mem2 = constructor_image()
+    mem2[IN_DATA] = tape[0]
+    v = mh._vec(0, mem2).unsqueeze(0).to(device)
+    headg = headm = 0
+    outg, outm = bytearray(), bytearray()
+    good = True
+    for n in range(600):
+        Bg = s["mem"][(s["pc"] + 1) & 0xFF]
+        s = gh.cpu.step(s)
+        if Bg == OUT:
+            outg.append(s["mem"][OUT])
+            s["mem"][OUT] = 0
+        elif Bg == IN_STROBE:
+            headg += 1
+            s["mem"][IN_STROBE] = 0
+            s["mem"][IN_DATA] = tape[headg] if headg < len(tape) else 0
+        vc = v[0].cpu()
+        pcm = 0
+        for k in range(8):
+            pcm = (pcm << 1) | int(vc[k])
+        Bm = MatrixHost._byte(vc, (pcm + 1) & 0xFF)
+        v = mh.step(v)
+        if Bm == OUT:
+            outm.append(MatrixHost._byte(v[0].cpu(), OUT))
+            v[0, 9 + OUT * 8: 9 + OUT * 8 + 8] = 0.0
+        elif Bm == IN_STROBE:
+            headm += 1
+            v[0, 9 + IN_STROBE * 8: 9 + IN_STROBE * 8 + 8] = 0.0
+            nxt = tape[headm] if headm < len(tape) else 0
+            for k in range(8):
+                v[0, 9 + IN_DATA * 8 + k] = float((nxt >> (7 - k)) & 1)
+        vc = v[0].cpu()
+        pcm = 0
+        for k in range(8):
+            pcm = (pcm << 1) | int(vc[k])
+        memm = [MatrixHost._byte(vc, j) for j in range(256)]
+        if pcm != s["pc"] or memm != s["mem"] or outg != outm:
+            print(f"  FAIL lockstep diverged at cycle {n}")
+            good = False
+            break
+    print(f"  {'OK ' if good else 'FAIL'} gate graph and matrix form agree "
+          f"cycle-for-cycle for 600 cycles ({len(outg)} bytes emitted identically)")
+    ok &= good
+
+    print("\nCONSTRUCTOR VERIFICATION:", "PASS" if ok else "FAIL")
+    return ok
+
+
+def self_reproduce(device: str, gen2: bool = True) -> bool:
+    """Full self-reproduction at threshold fidelity on the matrix backend."""
+    data = open(MODEL_PATH, "rb").read()
+    tape = describe(data)
+    print(f"\nSelf-reproduction on the threshold matrices: target "
+          f"{len(data):,} bytes (sha {sha(data)}), tape {len(tape):,} bytes")
+    ref_out, ref_steps = ref_construct(tape)
+    assert ref_out == data, "reference construction failed"
+    print(f"  reference: {ref_steps:,} instructions")
+
+    mh = MatrixHost(device=device)
+    t0 = time.perf_counter()
+    out, n = mh.run(tape, max_steps=ref_steps + 64, expect=data)
+    dt = time.perf_counter() - t0
+    ok = out == data and n == ref_steps
+    print(f"  GEN 1: emitted {len(out):,} bytes in {n:,} recurrences "
+          f"({dt / 60:.1f} min, {n / dt:,.0f} instr/s)  sha {sha(out)}")
+    print(f"  {'OK ' if ok else 'FAIL'} output stream == host safetensors file, "
+          f"byte for byte; instruction count matches reference exactly")
+
+    if ok and gen2:
+        off_path = os.path.join(REPO, "variants", "_offspring_subleq8io.safetensors")
+        with open(off_path, "wb") as f:
+            f.write(out)
+        gh = GateHost(off_path)     # boot the offspring's own gates
+        probe_tape = describe(out[:2048])
+        want = out[:2048]
+        got, steps, _ = gh.run(probe_tape, max_steps=len(probe_tape) * 8 + 64)
+        good2 = got == want
+        print(f"  GEN 2: offspring file booted as a machine (gate graph); "
+              f"constructed the first {len(want):,} bytes of itself in "
+              f"{steps:,} instructions: {'exact' if good2 else 'MISMATCH'}")
+        os.remove(off_path)
+        ok &= good2
+    print("SELF-REPRODUCTION:", "PASS" if ok else "FAIL")
+    return ok
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("cmd", choices=["build", "verify", "self", "all"])
+    ap.add_argument("--device", default="cuda" if torch.cuda.is_available() else "cpu")
+    args = ap.parse_args()
+    rc = 0
+    if args.cmd in ("build", "all"):
+        build_host(save=True)
+    if args.cmd in ("verify", "all"):
+        rc |= 0 if verify(args.device) else 1
+    if args.cmd in ("self", "all"):
+        rc |= 0 if self_reproduce(args.device) else 1
+    return rc
+
+
+if __name__ == "__main__":
+    sys.exit(main())

eval_all.py

@@ -615,16 +615,26 @@ def list_safetensors(path: Path) -> List[Path]:
     return []
 
 
+# Standalone machines carry their own circuit inventory and are verified by
+# their own scripts, not the gate-fitness suite. Each maps to the tool that
+# checks it.
+MACHINE_VERIFIER = {
+    "subleq8": "machines.py",
+    "rv32": "machines.py",
+    "matrix8": "matrix8.py",
+    "subleq8io": "constructor8.py",
+}
+
+
 def evaluate_one(path: Path, device: str, pop_size: int, debug: bool, run_cpu_program: bool) -> Dict:
     out: Dict = {"path": str(path), "filename": path.name}
-    # The standalone machines (neural_subleq8, neural_rv32) carry their own
-    # circuit inventory and are verified by machines.py, not the gate-fitness
-    # suite; skip them cleanly rather than error on missing standard gates.
+    # Skip standalone machines cleanly rather than error on missing standard gates.
     with safe_open(str(path), framework="pt") as f:
         meta = f.metadata() or {}
     if meta.get("machine"):
-        out.update(status="SKIP", machine=meta["machine"],
-                   note="standalone machine — verify with machines.py")
+        m = meta["machine"]
+        out.update(status="SKIP", machine=m,
+                   note=f"standalone machine — verify with {MACHINE_VERIFIER.get(m, 'machines.py')}")
         return out
     try:
         tensors = load_model(str(path))
@@ -724,7 +734,8 @@ def evaluate_one(path: Path, device: str, pop_size: int, debug: bool, run_cpu_pr
 
 def print_row(r: Dict, show_cpu: bool) -> None:
     if r.get("status") == "SKIP":
-        print(f"  {r['filename']:<48}  SKIP  ({r.get('machine', 'machine')} — verify with machines.py)")
+        m = r.get("machine", "machine")
+        print(f"  {r['filename']:<48}  SKIP  ({m} — verify with {MACHINE_VERIFIER.get(m, 'machines.py')})")
         return
     if "error" in r:
         print(f"  {r['filename']:<48}  ERROR: {r['error'][:80]}")

matrix8.py

@@ -0,0 +1,1081 @@
+"""neural_matrix8 — the 8-bit threshold CPU as a recurrent ternary linear-threshold
+network.
+
+The verified gate wiring of the registers-profile CPU (8-bit data, 4-bit
+addresses, 16 B memory) is compiled into a fixed sequence of ternary weight
+matrices W1..Wk with a Heaviside step between them, acting on a 173-bit state
+vector that holds the program counter, all four registers, the flags, the
+stack pointer, the halt bit, and every memory bit:
+
+    [ PC[4] | R0[8] R1[8] R2[8] R3[8] | Z N C V | SP[4] | HALT | MEM[16][8] ]
+
+One instruction is one pass through the stack (s' = H(Wk @ ... H(W1 @ s + b1)
+... + bk)); the machine is the stack iterated until the halt bit sets, so the
+whole processor is a single recurrent linear-threshold network. The transition
+is total: a halted state is a fixed point (every architectural write is gated
+by NOT halt), so iteration past halt is harmless.
+
+Every weight is in {-1, 0, 1} and every bias is a small integer; the circuit
+is assembled from the same verified cell constructions the family ships
+(two-layer OR/NAND XOR cells, ha1/ha2/carry_or full adders, bit-cascade
+comparators, 2:1 mux cells, one-threshold-gate address decode rows), then
+levelized ASAP with identity pass-throughs (H(x-1)) carrying live signals
+between layers.
+
+Equality with the gate-graph processor is machine-checked, bit for bit:
+  - exhaustively over all 65,536 (a, b) operand pairs for every ALU opcode
+    (ADD SUB AND OR XOR SHL SHR MUL DIV CMP), batched through the matrices;
+  - exhaustively over all Jcc condition x flag combinations, all JMP/CALL
+    targets and SP values, and all LOAD/STORE address/data pairs;
+  - by full-state lockstep against GenericThresholdCPU walking the shipped
+    neural_computer8_registers weights, per instruction, on a micro-program
+    suite covering every opcode;
+  - by single-step agreement with a pure-integer reference on random states.
+
+Analog realization: pre-activations are integers, 1-firing gates sit at >= 0
+and 0-gates at <= -1, so placing the analog comparator threshold at -0.5 gives
+every gate a symmetric guaranteed noise margin of 0.5 — any total analog error
+(read noise + conductance mismatch) below 0.5 per pre-activation provably
+reproduces the digital circuit bit-exactly. The analog suite measures the
+margin, then sweeps Gaussian read noise and static ternary-conductance
+mismatch to locate the empirical breakdown against the guarantee.
+
+Usage:
+    python matrix8.py build      # compile + save variants/neural_matrix8.safetensors
+    python matrix8.py verify     # equality suite (build in memory if file absent)
+    python matrix8.py analog     # margin + noise / mismatch sweeps
+    python matrix8.py all        # build + verify + analog
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from typing import Dict, List, Optional, Tuple
+
+import torch
+from safetensors import safe_open
+from safetensors.torch import save_file
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+REPO = os.path.dirname(os.path.abspath(__file__))
+MODEL_PATH = os.path.join(REPO, "variants", "neural_matrix8.safetensors")
+GATE_MODEL_PATH = os.path.join(REPO, "variants", "neural_computer8_registers.safetensors")
+
+ADDR_BITS = 4
+MEM_BYTES = 16
+STATE_BITS = 4 + 32 + 4 + 4 + 1 + 128  # pc, regs, flags, sp, halt, mem
+
+
+# =============================================================================
+# Circuit IR: named threshold gates over binary signals, constants fold away
+# =============================================================================
+
+class Net:
+    """A DAG of threshold gates. Signals are names; '#0' / '#1' are constants
+    folded into biases. Helper constructors perform algebraic collapse
+    (AND(x,#1)=x, OR with one live input = that input, ...) so the compiled
+    stack carries no dead logic; the collapses change nothing semantically and
+    the whole machine is verified bit-for-bit afterwards."""
+
+    def __init__(self):
+        self.gates: Dict[str, Tuple[List[Tuple[str, int]], int]] = {}
+
+    def g(self, name: str, ins: List[Tuple[str, int]], bias: int) -> str:
+        folded: List[Tuple[str, int]] = []
+        b = int(bias)
+        for s, w in ins:
+            assert w in (-1, 1), f"non-ternary weight {w} at {name}"
+            if s == "#1":
+                b += w
+            elif s == "#0":
+                pass
+            else:
+                folded.append((s, int(w)))
+        if name in self.gates:
+            raise ValueError(f"duplicate gate {name}")
+        self.gates[name] = (folded, b)
+        return name
+
+    # --- verified cell constructions --------------------------------------
+    def NOT(self, name, x):
+        if x == "#1":
+            return "#0"
+        if x == "#0":
+            return "#1"
+        return self.g(name, [(x, -1)], 0)
+
+    def BUF(self, name, x):
+        if x in ("#0", "#1"):
+            return x
+        return self.g(name, [(x, 1)], -1)
+
+    def AND(self, name, ins: List[str]):
+        live = []
+        for s in ins:
+            if s == "#0":
+                return "#0"
+            if s != "#1":
+                live.append(s)
+        if not live:
+            return "#1"
+        if len(live) == 1:
+            return live[0]
+        return self.g(name, [(s, 1) for s in live], -len(live))
+
+    def OR(self, name, ins: List[str]):
+        live = []
+        for s in ins:
+            if s == "#1":
+                return "#1"
+            if s != "#0":
+                live.append(s)
+        if not live:
+            return "#0"
+        if len(live) == 1:
+            return live[0]
+        return self.g(name, [(s, 1) for s in live], -1)
+
+    def NOR(self, name, ins: List[str]):
+        live = [s for s in ins if s != "#0"]
+        if any(s == "#1" for s in live):
+            return "#0"
+        if not live:
+            return "#1"
+        return self.g(name, [(s, -1) for s in live], 0)
+
+    def XOR(self, prefix, a, b):
+        """Two-layer OR/NAND XOR, the family's verified construction."""
+        if a == "#0":
+            return b if b in ("#0", "#1") else self.BUF(f"{prefix}.buf", b)
+        if b == "#0":
+            return a if a in ("#0", "#1") else self.BUF(f"{prefix}.buf", a)
+        if a == "#1":
+            return self.NOT(f"{prefix}.not", b)
+        if b == "#1":
+            return self.NOT(f"{prefix}.not", a)
+        h_or = self.g(f"{prefix}.l1or", [(a, 1), (b, 1)], -1)
+        h_nand = self.g(f"{prefix}.l1nand", [(a, -1), (b, -1)], 1)
+        return self.g(prefix, [(h_or, 1), (h_nand, 1)], -2)
+
+    def FA(self, prefix, a, b, cin):
+        """Verified full-adder cell (ha1 XOR/AND, ha2 XOR/AND, carry OR)."""
+        s1 = self.XOR(f"{prefix}.ha1s", a, b)
+        c1 = self.AND(f"{prefix}.ha1c", [a, b])
+        s2 = self.XOR(f"{prefix}.ha2s", s1, cin)
+        c2 = self.AND(f"{prefix}.ha2c", [s1, cin])
+        co = self.OR(f"{prefix}.cor", [c1, c2])
+        return s2, co
+
+    def MUX(self, prefix, sel, x1, x0):
+        """2:1 mux cell: sel ? x1 : x0 (not_sel / and / and / or)."""
+        if sel == "#1":
+            return x1
+        if sel == "#0":
+            return x0
+        if x1 == x0:
+            return x0
+        ns = self.NOT(f"{prefix}.ns", sel)
+        a1 = self.AND(f"{prefix}.a1", [x1, sel])
+        a0 = self.AND(f"{prefix}.a0", [x0, ns])
+        return self.OR(f"{prefix}.or", [a1, a0])
+
+    def DECODE(self, name, bits: List[str], value: int):
+        """One-gate address-decode row (the memory.addr_decode construction):
+        fires iff the MSB-first bits equal `value`."""
+        n = len(bits)
+        ins = []
+        pop = 0
+        for i in range(n):
+            bit = (value >> (n - 1 - i)) & 1
+            ins.append((bits[i], 1 if bit else -1))
+            pop += bit
+        return self.g(name, ins, -pop)
+
+
+# =============================================================================
+# State layout
+# =============================================================================
+
+def state_names() -> List[str]:
+    names = [f"pc{i}" for i in range(4)]
+    for r in range(4):
+        names += [f"r{r}b{i}" for i in range(8)]
+    names += ["fZ", "fN", "fC", "fV"]
+    names += [f"sp{i}" for i in range(4)]
+    names += ["halt"]
+    for j in range(MEM_BYTES):
+        names += [f"m{j}b{i}" for i in range(8)]
+    return names
+
+
+def state_to_vec(s: dict) -> torch.Tensor:
+    v = torch.zeros(STATE_BITS)
+    i = 0
+    for k in range(4):
+        v[i] = (s["pc"] >> (3 - k)) & 1
+        i += 1
+    for r in range(4):
+        for k in range(8):
+            v[i] = (s["regs"][r] >> (7 - k)) & 1
+            i += 1
+    for k in range(4):
+        v[i] = s["flags"][k]
+        i += 1
+    for k in range(4):
+        v[i] = (s["sp"] >> (3 - k)) & 1
+        i += 1
+    v[i] = 1.0 if s["halted"] else 0.0
+    i += 1
+    for j in range(MEM_BYTES):
+        for k in range(8):
+            v[i] = (s["mem"][j] >> (7 - k)) & 1
+            i += 1
+    return v
+
+
+def vec_to_state(v: torch.Tensor) -> dict:
+    bits = [int(round(float(x))) for x in v.tolist()]
+    i = 0
+    pc = 0
+    for k in range(4):
+        pc = (pc << 1) | bits[i]
+        i += 1
+    regs = []
+    for r in range(4):
+        x = 0
+        for k in range(8):
+            x = (x << 1) | bits[i]
+            i += 1
+        regs.append(x)
+    flags = bits[i:i + 4]
+    i += 4
+    sp = 0
+    for k in range(4):
+        sp = (sp << 1) | bits[i]
+        i += 1
+    halted = bool(bits[i])
+    i += 1
+    mem = []
+    for j in range(MEM_BYTES):
+        x = 0
+        for k in range(8):
+            x = (x << 1) | bits[i]
+            i += 1
+        mem.append(x)
+    return {"pc": pc, "regs": regs, "flags": flags, "sp": sp,
+            "halted": halted, "mem": mem}
+
+
+# =============================================================================
+# The step circuit: one full instruction of the registers-profile CPU
+# =============================================================================
+
+def build_step_net() -> Tuple[Net, List[str], List[str]]:
+    net = Net()
+    pc = [f"pc{i}" for i in range(4)]
+    R = [[f"r{r}b{i}" for i in range(8)] for r in range(4)]
+    fl = ["fZ", "fN", "fC", "fV"]
+    sp = [f"sp{i}" for i in range(4)]
+    halt = "halt"
+    mem = [[f"m{j}b{i}" for i in range(8)] for j in range(MEM_BYTES)]
+
+    # ---- fetch: bytes at PC .. PC+3 (decode lines reindexed, no adders) ----
+    P = [net.DECODE(f"pdec{j}", pc, j) for j in range(MEM_BYTES)]
+    byte = []
+    for o in range(4):
+        bo = []
+        for bit in range(8):
+            terms = [net.AND(f"f{o}a{j}b{bit}", [mem[j][bit], P[(j - o) % MEM_BYTES]])
+                     for j in range(MEM_BYTES)]
+            bo.append(net.OR(f"f{o}b{bit}", terms))
+        byte.append(bo)
+
+    # ---- field decode; opcode lines gated by NOT halt (total transition) ---
+    nhalt = net.NOT("nhalt", halt)
+    O = [net.DECODE(f"op{v:X}", byte[0][0:4], v) for v in range(16)]
+    OG = [net.AND(f"og{v:X}", [O[v], nhalt]) for v in range(16)]
+    rdl = [net.DECODE(f"rdl{r}", byte[0][4:6], r) for r in range(4)]
+    rsl = [net.DECODE(f"rsl{r}", byte[0][6:8], r) for r in range(4)]
+    CL = [net.DECODE(f"cond{c}", byte[1][5:8], c) for c in range(8)]
+
+    # ---- register read ports ----------------------------------------------
+    a = [net.OR(f"a{bit}", [net.AND(f"a{bit}r{r}", [R[r][bit], rdl[r]])
+                            for r in range(4)]) for bit in range(8)]
+    b = [net.OR(f"b{bit}", [net.AND(f"b{bit}r{r}", [R[r][bit], rsl[r]])
+                            for r in range(4)]) for bit in range(8)]
+    a_l = lambda k: a[7 - k]  # LSB-first views for the adder chains
+    b_l = lambda k: b[7 - k]
+
+    # ---- ALU: ADD ----------------------------------------------------------
+    c = "#0"
+    add_l = []
+    for k in range(8):
+        s_, c = net.FA(f"add.fa{k}", a_l(k), b_l(k), c)
+        add_l.append(s_)
+    add = [add_l[7 - i] for i in range(8)]
+    add_c = c
+
+    # ---- SUB (shared by CMP): a + ~b + 1 -----------------------------------
+    nb_l = [net.NOT(f"sub.nb{k}", b_l(k)) for k in range(8)]
+    c = "#1"
+    sub_l = []
+    for k in range(8):
+        s_, c = net.FA(f"sub.fa{k}", a_l(k), nb_l[k], c)
+        sub_l.append(s_)
+    sub = [sub_l[7 - i] for i in range(8)]
+    sub_c = c  # carry set = no borrow
+
+    # ---- bitwise / shifts ---------------------------------------------------
+    andr = [net.AND(f"land{bit}", [a[bit], b[bit]]) for bit in range(8)]
+    orr = [net.OR(f"lor{bit}", [a[bit], b[bit]]) for bit in range(8)]
+    xorr = [net.XOR(f"lxor{bit}", a[bit], b[bit]) for bit in range(8)]
+    shl = [a[bit + 1] if bit < 7 else "#0" for bit in range(8)]
+    shr = [a[bit - 1] if bit > 0 else "#0" for bit in range(8)]
+
+    # ---- MUL: partial products + 7 chained shift-add adders ----------------
+    pp = [[net.AND(f"pp.a{i}b{j}", [a[i], b[j]]) for j in range(8)] for i in range(8)]
+    acc_l: List[str] = ["#0"] * 8
+    acc_l[7] = pp[7][0]                      # row j=0 shifted by 7
+    for j in range(1, 8):
+        shift = 7 - j
+        c = "#0"
+        nxt = []
+        for k in range(8):
+            addend = pp[14 - k - j][j] if shift <= k <= min(7, 14 - j) else "#0"
+            s_, c = net.FA(f"mul.s{j}.fa{k}", acc_l[k], addend, c)
+            nxt.append(s_)
+        acc_l = nxt
+    mul = [acc_l[7 - i] for i in range(8)]
+
+    # ---- DIV: 8 restoring stages (bit-cascade GE + subtract + mux) ---------
+    def cascade_lt(prefix: str, x_m: List[str], y_m: List[str]) -> str:
+        """Unsigned x < y via the verified bit-cascade (bit 0 = MSB)."""
+        bit_lt, bit_eq = [], []
+        for i in range(8):
+            bit_lt.append(net.g(f"{prefix}.b{i}lt", [(x_m[i], -1), (y_m[i], 1)], -1)
+                          if x_m[i] != "#0" else
+                          (y_m[i] if y_m[i] != "#0" else "#0"))
+            if x_m[i] == "#0":
+                bit_eq.append(net.NOT(f"{prefix}.b{i}eq", y_m[i]))
+            else:
+                e_and = net.AND(f"{prefix}.b{i}ea", [x_m[i], y_m[i]])
+                e_nor = net.NOR(f"{prefix}.b{i}en", [x_m[i], y_m[i]])
+                bit_eq.append(net.OR(f"{prefix}.b{i}eq", [e_and, e_nor]))
+        casc = [bit_lt[0]]
+        for i in range(1, 8):
+            pref = net.AND(f"{prefix}.ep{i}", bit_eq[:i])
+            casc.append(net.AND(f"{prefix}.cl{i}", [pref, bit_lt[i]]))
+        return net.OR(f"{prefix}.lt", casc)
+
+    rem_l: List[str] = ["#0"] * 8
+    q_m: List[str] = []
+    for st in range(8):
+        sh_l = [a[st]] + rem_l[0:7]          # (rem << 1) | a_bit; top bit provably 0
+        sh_m = [sh_l[7 - i] for i in range(8)]
+        lt = cascade_lt(f"div.s{st}.cmp", sh_m, b)
+        ge = net.NOT(f"div.s{st}.ge", lt)
+        c = "#1"
+        dsub_l = []
+        for k in range(8):
+            s_, c = net.FA(f"div.s{st}.sub.fa{k}", sh_l[k], nb_l[k], c)
+            dsub_l.append(s_)
+        rem_l = [net.MUX(f"div.s{st}.mx{k}", ge, dsub_l[k], sh_l[k]) for k in range(8)]
+        q_m.append(ge)
+    div = q_m                                # quotient, MSB-first
+
+    # ---- LOAD read port (address = low nibble of byte3) --------------------
+    addr4 = byte[3][4:8]
+    AD = [net.DECODE(f"adec{j}", addr4, j) for j in range(MEM_BYTES)]
+    ld = [net.OR(f"ld{bit}", [net.AND(f"ld{bit}a{j}", [mem[j][bit], AD[j]])
+                              for j in range(MEM_BYTES)]) for bit in range(8)]
+
+    # ---- result mux over opcode lines ---------------------------------------
+    srcs = [(0, add), (1, sub), (2, andr), (3, orr), (4, xorr),
+            (5, shl), (6, shr), (7, mul), (8, div), (0xA, ld)]
+    res = [net.OR(f"res{bit}", [net.AND(f"res{bit}o{v:X}", [src[bit], OG[v]])
+                                for v, src in srcs]) for bit in range(8)]
+
+    # ---- flags ---------------------------------------------------------------
+    z_add = net.NOR("zadd", add)
+    z_sub = net.NOR("zsub", sub)
+    z_mul = net.NOR("zmul", mul)
+    v_add = net.AND("vadd", [net.XOR("vadd.x1", a[0], add[0]),
+                             net.XOR("vadd.x2", b[0], add[0])])
+    v_sub = net.AND("vsub", [net.XOR("vsub.x1", a[0], b[0]),
+                             net.XOR("vsub.x2", a[0], sub[0])])
+    f_src = {  # per-source (Z, N, C, V); CMP shares the SUB datapath
+        0: (z_add, add[0], add_c, v_add),
+        1: (z_sub, sub[0], sub_c, v_sub),
+        7: (z_mul, mul[0], "#0", "#0"),
+        9: (z_sub, sub[0], sub_c, v_sub),
+    }
+    fw = net.OR("fw", [OG[0], OG[1], OG[7], OG[9]])
+    fl_next = []
+    for fi, fn in enumerate("ZNCV"):
+        new = net.OR(f"fnew{fn}", [net.AND(f"fnew{fn}o{v:X}", [f_src[v][fi], OG[v]])
+                                   for v in (0, 1, 7, 9)])
+        fl_next.append(net.MUX(f"fmux{fn}", fw, new, fl[fi]))
+
+    # ---- register writeback --------------------------------------------------
+    wen = net.OR("wen", [OG[v] for v in (0, 1, 2, 3, 4, 5, 6, 7, 8, 0xA)])
+    R_next = []
+    for r in range(4):
+        wsel = net.AND(f"wsel{r}", [wen, rdl[r]])
+        nws = net.NOT(f"nws{r}", wsel)
+        row = []
+        for bit in range(8):
+            t1 = net.AND(f"wb{r}b{bit}n", [res[bit], wsel])
+            t0 = net.AND(f"wb{r}b{bit}o", [R[r][bit], nws])
+            row.append(net.OR(f"wb{r}b{bit}", [t1, t0]))
+        R_next.append(row)
+
+    # ---- program counter ------------------------------------------------------
+    pc_l = [pc[3 - k] for k in range(4)]     # LSB-first view
+    p2_l = [pc_l[0], net.NOT("pc2.n1", pc_l[1]),
+            net.XOR("pc2.x2", pc_l[2], pc_l[1]),
+            net.XOR("pc2.x3", pc_l[3], net.AND("pc2.c3", [pc_l[2], pc_l[1]]))]
+    p4_l = [pc_l[0], pc_l[1], net.NOT("pc4.n2", pc_l[2]),
+            net.XOR("pc4.x3", pc_l[3], pc_l[2])]
+    ext = net.OR("ext", [OG[v] for v in (0xA, 0xB, 0xC, 0xD, 0xE)])
+    adv_l = [net.MUX(f"padv{k}", ext, p4_l[k], p2_l[k]) for k in range(4)]
+    pc_adv = [adv_l[3 - i] for i in range(4)]
+
+    nfl = [net.NOT(f"nf{fn}", fl[i]) for i, fn in enumerate("ZNCV")]
+    cond_flag = [fl[0], nfl[0], fl[2], nfl[2], fl[1], nfl[1], fl[3], nfl[3]]
+    condsel = net.OR("condsel", [net.AND(f"ct{cnd}", [CL[cnd], cond_flag[cnd]])
+                                 for cnd in range(8)])
+    take = net.OR("take", [OG[0xC], OG[0xE], net.AND("jcct", [OG[0xD], condsel])])
+    keeppc = net.OR("keeppc", [halt, OG[0xF]])
+    adv = net.AND("adv", [net.NOT("ntake", take), net.NOT("nkeep", keeppc)])
+    pc_next = [net.OR(f"pcn{i}", [net.AND(f"pcn{i}t", [addr4[i], take]),
+                                  net.AND(f"pcn{i}k", [pc[i], keeppc]),
+                                  net.AND(f"pcn{i}a", [pc_adv[i], adv])])
+               for i in range(4)]
+
+    # ---- stack pointer (CALL: SP-2 = SP + 14) ---------------------------------
+    sp_l = [sp[3 - k] for k in range(4)]
+    c = "#0"
+    s2_l = []
+    for k, addend in enumerate(["#0", "#1", "#1", "#1"]):
+        s_, c = net.FA(f"spm2.fa{k}", sp_l[k], addend, c)
+        s2_l.append(s_)
+    spm2 = [s2_l[3 - i] for i in range(4)]
+    sp_next = [net.MUX(f"spn{i}", OG[0xE], spm2[i], sp[i]) for i in range(4)]
+
+    # ---- halt (sticky) ---------------------------------------------------------
+    halt_next = net.OR("haltn", [halt, OG[0xF]])
+
+    # ---- memory next: STORE write, CALL pushes ret-hi (0) and ret-lo ----------
+    SPD = [net.DECODE(f"spdec{j}", sp, j) for j in range(MEM_BYTES)]
+    mem_next = []
+    for j in range(MEM_BYTES):
+        st_sel = net.AND(f"stsel{j}", [OG[0xB], AD[j]])
+        ch_sel = net.AND(f"chsel{j}", [OG[0xE], SPD[(j + 1) % MEM_BYTES]])
+        cl_sel = net.AND(f"clsel{j}", [OG[0xE], SPD[(j + 2) % MEM_BYTES]])
+        keep = net.NOR(f"keep{j}", [st_sel, ch_sel, cl_sel])
+        row = []
+        for bit in range(8):
+            terms = [net.AND(f"mn{j}b{bit}k", [mem[j][bit], keep]),
+                     net.AND(f"mn{j}b{bit}s", [b[bit], st_sel])]
+            if bit >= 4:  # ret-lo low nibble carries pc_adv; high nibble is 0
+                terms.append(net.AND(f"mn{j}b{bit}c", [pc_adv[bit - 4], cl_sel]))
+            row.append(net.OR(f"mn{j}b{bit}", terms))
+        mem_next.append(row)
+
+    outputs = (pc_next
+               + [bitsig for row in R_next for bitsig in row]
+               + fl_next + sp_next + [halt_next]
+               + [bitsig for row in mem_next for bitsig in row])
+    return net, state_names(), outputs
+
+
+# =============================================================================
+# Compiler: levelize ASAP, insert pass-throughs, emit dense ternary matrices
+# =============================================================================
+
+def compile_net(net: Net, inputs: List[str], outputs: List[str],
+                ) -> Tuple[List[Tuple[torch.Tensor, torch.Tensor]], dict]:
+    gates = net.gates
+    level: Dict[str, int] = {s: 0 for s in inputs}
+
+    consumers: Dict[str, List[str]] = {}
+    indeg: Dict[str, int] = {}
+    for gname, (ins, _) in gates.items():
+        deps = [s for s, _ in ins if s in gates]
+        indeg[gname] = len(deps)
+        for s, _ in ins:
+            consumers.setdefault(s, []).append(gname)
+    order = [g for g, d in indeg.items() if d == 0]
+    i = 0
+    while i < len(order):
+        for cns in consumers.get(order[i], []):
+            indeg[cns] -= 1
+            if indeg[cns] == 0:
+                order.append(cns)
+        i += 1
+    if len(order) != len(gates):
+        raise ValueError("cycle in step circuit")
+    for gname in order:
+        ins, _ = gates[gname]
+        level[gname] = 1 + max((level[s] for s, _ in ins), default=0)
+
+    kmax = max(level[gname] for gname in gates)
+    K = kmax + 1  # final layer selects the next-state bits in order
+
+    last_use: Dict[str, int] = {}
+    for gname, (ins, _) in gates.items():
+        for s, _ in ins:
+            last_use[s] = max(last_use.get(s, 0), level[gname])
+    for s in outputs:
+        if s not in ("#0", "#1"):
+            last_use[s] = K
+
+    by_level: Dict[int, List[str]] = {}
+    for gname in gates:
+        by_level.setdefault(level[gname], []).append(gname)
+
+    vec = list(inputs)                       # V_0
+    layers: List[Tuple[torch.Tensor, torch.Tensor]] = []
+    for lv in range(1, K + 1):
+        if lv < K:
+            new_gates = sorted(by_level.get(lv, []))
+            passes = [s for s in vec if last_use.get(s, 0) > lv]
+            rows = new_gates + passes
+        else:
+            rows = list(outputs)
+        cols = {s: idx for idx, s in enumerate(vec)}
+        W = torch.zeros(len(rows), len(vec), dtype=torch.int8)
+        B = torch.zeros(len(rows), dtype=torch.int8)
+        out_names = []
+        for ri, s in enumerate(rows):
+            if lv == K and s == "#0":
+                B[ri] = -1
+                out_names.append(s)
+                continue
+            if lv == K and s == "#1":
+                B[ri] = 0
+                out_names.append(s)
+                continue
+            if s in gates and level[s] == lv:
+                ins, bias = gates[s]
+                for src, w in ins:
+                    W[ri, cols[src]] += w
+                B[ri] = bias
+            else:
+                W[ri, cols[s]] = 1
+                B[ri] = -1
+            out_names.append(s)
+        layers.append((W, B))
+        vec = out_names
+
+    if vec != outputs:
+        raise AssertionError("final layer does not emit the state vector")
+
+    info = {
+        "layers": K,
+        "gates": len(gates),
+        "max_width": max(max(W.shape) for W, _ in layers),
+        "total_weights": sum(W.numel() for W, _ in layers),
+        "widths": [layers[0][0].shape[1]] + [W.shape[0] for W, _ in layers],
+    }
+    return layers, info
+
+
+# =============================================================================
+# Recurrent runtime
+# =============================================================================
+
+class MatrixMachine:
+    """s' = H(Wk @ ... H(W1 @ s + b1) ... + bk); iterate until the halt bit.
+
+    Digital mode thresholds at 0 (pre-activations are integers). Analog mode
+    thresholds at -0.5 (the max-margin comparator point) and can inject
+    Gaussian read noise per MVM and static ternary-conductance mismatch."""
+
+    HALT_IDX = 4 + 32 + 4 + 4  # index of the halt bit in the state vector
+
+    def __init__(self, layers, device="cpu"):
+        self.device = device
+        self.W = [W.to(device=device, dtype=torch.float32) for W, _ in layers]
+        self.B = [B.to(device=device, dtype=torch.float32) for _, B in layers]
+
+    @classmethod
+    def from_file(cls, path=MODEL_PATH, device="cpu"):
+        layers = []
+        with safe_open(path, framework="pt") as f:
+            n = 0
+            while f"matrix.layer{n:03d}.weight" in f.keys():
+                layers.append((f.get_tensor(f"matrix.layer{n:03d}.weight"),
+                               f.get_tensor(f"matrix.layer{n:03d}.bias")))
+                n += 1
+        if not layers:
+            raise FileNotFoundError(f"no matrix layers in {path}")
+        return cls(layers, device=device)
+
+    def perturbed(self, sigma_g: float, seed: int = 0) -> "MatrixMachine":
+        """Static conductance mismatch: each nonzero ternary conductance gets a
+        fixed Gaussian perturbation (fabrication variation, constant per run)."""
+        gen = torch.Generator(device="cpu").manual_seed(seed)
+        m = MatrixMachine.__new__(MatrixMachine)
+        m.device = self.device
+        m.W = []
+        m.B = self.B
+        for W in self.W:
+            d = torch.randn(W.shape, generator=gen).to(self.device) * sigma_g
+            m.W.append(W + d * (W != 0))
+        return m
+
+    def step(self, v: torch.Tensor, analog: bool = False,
+             noise_sigma: float = 0.0, gen: Optional[torch.Generator] = None,
+             ) -> torch.Tensor:
+        thresh = -0.5 if analog else 0.0
+        for W, b in zip(self.W, self.B):
+            pre = v @ W.T + b
+            if noise_sigma > 0.0:
+                pre = pre + torch.randn(pre.shape, generator=gen,
+                                        device=pre.device) * noise_sigma
+            v = (pre >= thresh).float()
+        return v
+
+    def run(self, state: dict, max_cycles: int = 64, **kw) -> Tuple[dict, int]:
+        v = state_to_vec(state).unsqueeze(0).to(self.device)
+        n = 0
+        while n < max_cycles and v[0, self.HALT_IDX] < 0.5:
+            v = self.step(v, **kw)
+            n += 1
+        return vec_to_state(v[0].cpu()), n
+
+    def min_margin(self, v: torch.Tensor) -> float:
+        """Distance of every pre-activation from the analog threshold -0.5."""
+        m = float("inf")
+        for W, b in zip(self.W, self.B):
+            pre = v @ W.T + b
+            m = min(m, float((pre + 0.5).abs().min()))
+            v = (pre >= 0).float()
+        return m
+
+
+# =============================================================================
+# Pure-integer reference (mirrors GenericThresholdCPU semantics, 4-bit addr)
+# =============================================================================
+
+_JCC_FLAG = [0, 0, 2, 2, 1, 1, 3, 3]
+
+
+def ref_step(s: dict) -> dict:
+    if s["halted"]:
+        return {k: (list(v) if isinstance(v, list) else v) for k, v in s.items()}
+    s = {"pc": s["pc"], "regs": list(s["regs"]), "flags": list(s["flags"]),
+         "sp": s["sp"], "halted": s["halted"], "mem": list(s["mem"])}
+    M = MEM_BYTES - 1
+    pc = s["pc"]
+    ir = (s["mem"][pc] << 8) | s["mem"][(pc + 1) & M]
+    op, rd, rs = (ir >> 12) & 0xF, (ir >> 10) & 3, (ir >> 8) & 3
+    imm = ir & 0xFF
+    next_pc = (pc + 2) & M
+    addr = None
+    if op in (0xA, 0xB, 0xC, 0xD, 0xE):
+        al = s["mem"][(next_pc + 1) & M]
+        addr = al & M
+        next_pc = (next_pc + 2) & M
+    a, b = s["regs"][rd], s["regs"][rs]
+    result, carry, ovf, wr = a, 0, 0, True
+    if op == 0x0:
+        result = (a + b) & 0xFF
+        carry = 1 if a + b > 0xFF else 0
+        ovf = 1 if ((a ^ result) & (b ^ result)) & 0x80 else 0
+    elif op == 0x1:
+        result = (a - b) & 0xFF
+        carry = 1 if a >= b else 0
+        ovf = 1 if ((a ^ b) & (a ^ result)) & 0x80 else 0
+    elif op == 0x2:
+        result = a & b
+    elif op == 0x3:
+        result = a | b
+    elif op == 0x4:
+        result = a ^ b
+    elif op == 0x5:
+        result = (a << 1) & 0xFF
+    elif op == 0x6:
+        result = a >> 1
+    elif op == 0x7:
+        result = (a * b) & 0xFF
+    elif op == 0x8:
+        result = 0xFF if b == 0 else a // b
+    elif op == 0x9:
+        r2 = (a - b) & 0xFF
+        carry = 1 if a >= b else 0
+        ovf = 1 if ((a ^ b) & (a ^ r2)) & 0x80 else 0
+        s["flags"] = [1 if r2 == 0 else 0, 1 if r2 & 0x80 else 0, carry, ovf]
+        wr = False
+    elif op == 0xA:
+        result = s["mem"][addr]
+    elif op == 0xB:
+        s["mem"][addr] = b & 0xFF
+        wr = False
+    elif op == 0xC:
+        s["pc"] = addr
+        return s
+    elif op == 0xD:
+        cnd = imm & 7
+        flag = s["flags"][_JCC_FLAG[cnd]]
+        sel = flag if cnd % 2 == 0 else 1 - flag
+        s["pc"] = addr if sel else next_pc
+        return s
+    elif op == 0xE:
+        ret = next_pc
+        sp2 = (s["sp"] - 1) & M
+        s["mem"][sp2] = (ret >> 8) & 0xFF
+        sp2 = (sp2 - 1) & M
+        s["mem"][sp2] = ret & 0xFF
+        s["sp"] = sp2
+        s["pc"] = addr
+        return s
+    elif op == 0xF:
+        s["halted"] = True
+        return s
+    if wr and op != 0x9:
+        s["regs"][rd] = result & 0xFF
+    if op in (0x0, 0x1, 0x7):
+        s["flags"] = [1 if result == 0 else 0, 1 if result & 0x80 else 0,
+                      carry, ovf]
+    s["pc"] = next_pc
+    return s
+
+
+# =============================================================================
+# Build + save
+# =============================================================================
+
+def build(save: bool = True):
+    print("Assembling the step circuit from the verified cell library...")
+    t0 = time.perf_counter()
+    net, inputs, outputs = build_step_net()
+    print(f"  {len(net.gates)} threshold gates")
+    layers, info = compile_net(net, inputs, outputs)
+    dt = time.perf_counter() - t0
+    print(f"  compiled to {info['layers']} ternary matrices in {dt:.1f}s; "
+          f"max width {info['max_width']}, "
+          f"{info['total_weights']:,} dense weight entries")
+    for W, B in layers:
+        vals = set(torch.unique(W).tolist())
+        assert vals <= {-1, 0, 1}, f"non-ternary matrix: {vals}"
+        assert int(B.min()) >= -128 and int(B.max()) <= 127
+
+    if save:
+        tensors = {}
+        for i, (W, B) in enumerate(layers):
+            tensors[f"matrix.layer{i:03d}.weight"] = W
+            tensors[f"matrix.layer{i:03d}.bias"] = B
+        tensors["manifest.data_bits"] = torch.tensor([8.0])
+        tensors["manifest.addr_bits"] = torch.tensor([float(ADDR_BITS)])
+        tensors["manifest.memory_bytes"] = torch.tensor([float(MEM_BYTES)])
+        tensors["manifest.registers"] = torch.tensor([4.0])
+        tensors["manifest.layers"] = torch.tensor([float(info["layers"])])
+        tensors["manifest.state_bits"] = torch.tensor([float(STATE_BITS)])
+        tensors["manifest.version"] = torch.tensor([4.0])
+        meta = {
+            "machine": "matrix8",
+            "weight_quantization": "ternary",
+            "state_layout": json.dumps(state_names()),
+            "analog": json.dumps({
+                "comparator_threshold": -0.5,
+                "guaranteed_margin": 0.5,
+                "note": "pre-activations are integers; any total analog error "
+                        "below 0.5 per pre-activation is provably bit-exact",
+            }),
+        }
+        save_file(tensors, MODEL_PATH, metadata=meta)
+        sz = os.path.getsize(MODEL_PATH) / (1024 * 1024)
+        print(f"  saved {MODEL_PATH} ({sz:.1f} MB)")
+    return layers, info
+
+
+# =============================================================================
+# Verification: matrix form == gate graph == integer reference, bit for bit
+# =============================================================================
+
+def _mk_state(mem=None, regs=(0, 0, 0, 0), flags=(0, 0, 0, 0), pc=0,
+              sp=MEM_BYTES - 1, halted=False):
+    m = [0] * MEM_BYTES
+    if mem:
+        for i, x in enumerate(mem):
+            m[i] = x & 0xFF
+    return {"pc": pc, "regs": list(regs), "flags": list(flags), "sp": sp,
+            "halted": halted, "mem": m}
+
+
+def _instr(op, rd=0, rs=0, imm=0):
+    w = ((op & 0xF) << 12) | ((rd & 3) << 10) | ((rs & 3) << 8) | (imm & 0xFF)
+    return [(w >> 8) & 0xFF, w & 0xFF]
+
+
+def verify(mm: MatrixMachine, device: str) -> bool:
+    ok_all = True
+
+    # ---- 1. exhaustive ALU sweeps: all 65,536 operand pairs per opcode ------
+    print("\n[1/4] Exhaustive ALU sweeps (65,536 operand pairs x 10 opcodes, "
+          "batched through the matrices, vs integer reference)")
+    aa = torch.arange(65536) % 256
+    bb = torch.arange(65536) // 256
+    for op, name in [(0, "ADD"), (1, "SUB"), (2, "AND"), (3, "OR"), (4, "XOR"),
+                     (5, "SHL"), (6, "SHR"), (7, "MUL"), (8, "DIV"), (9, "CMP")]:
+        for f_init in (0, 0xF):
+            V = torch.zeros(65536, STATE_BITS)
+            prog = _instr(op, rd=0, rs=1) + _instr(0xF)
+            base = _mk_state(mem=prog, flags=[(f_init >> (3 - i)) & 1 for i in range(4)])
+            V[:] = state_to_vec(base)
+            for k in range(8):
+                V[:, 4 + k] = ((aa >> (7 - k)) & 1).float()      # R0
+                V[:, 12 + k] = ((bb >> (7 - k)) & 1).float()     # R1
+            V = mm.step(V.to(device)).cpu()
+            bad = 0
+            probe = list(range(0, 65536, 4099)) + [0, 65535, 255, 256, 32768]
+            for idx in probe:
+                st = _mk_state(mem=prog, regs=(int(aa[idx]), int(bb[idx]), 0, 0),
+                               flags=base["flags"])
+                if vec_to_state(V[idx]) != ref_step(st):
+                    bad += 1
+            # full vectorized compare of the architectural result field
+            r0 = sum(V[:, 4 + k].long() << (7 - k) for k in range(8))
+            fZ, fN, fC, fV = (V[:, 36].long(), V[:, 37].long(),
+                              V[:, 38].long(), V[:, 39].long())
+            if op == 0:
+                exp = (aa + bb) & 0xFF
+            elif op in (1, 9):
+                exp = (aa - bb) & 0xFF
+            elif op == 2:
+                exp = aa & bb
+            elif op == 3:
+                exp = aa | bb
+            elif op == 4:
+                exp = aa ^ bb
+            elif op == 5:
+                exp = (aa << 1) & 0xFF
+            elif op == 6:
+                exp = aa >> 1
+            elif op == 7:
+                exp = (aa * bb) & 0xFF
+            else:
+                exp = torch.where(bb == 0, torch.full_like(aa, 0xFF),
+                                  aa // torch.clamp(bb, min=1))
+            reg_exp = aa if op == 9 else exp
+            n_bad = int((r0 != reg_exp).sum())
+            if op in (0, 1, 7, 9):
+                zx = (exp == 0).long()
+                nx = ((exp & 0x80) > 0).long()
+                if op == 0:
+                    cx = ((aa + bb) > 0xFF).long()
+                    vx = ((((aa ^ exp) & (bb ^ exp)) & 0x80) > 0).long()
+                elif op in (1, 9):
+                    cx = (aa >= bb).long()
+                    vx = ((((aa ^ bb) & (aa ^ exp)) & 0x80) > 0).long()
+                else:
+                    cx = torch.zeros_like(aa)
+                    vx = torch.zeros_like(aa)
+                n_bad += int((fZ != zx).sum() + (fN != nx).sum()
+                             + (fC != cx).sum() + (fV != vx).sum())
+            else:
+                want = torch.tensor([(f_init >> (3 - i)) & 1 for i in range(4)])
+                n_bad += int((torch.stack([fZ, fN, fC, fV], 1)
+                              != want.unsqueeze(0)).sum())
+            status = "OK " if (n_bad == 0 and bad == 0) else "FAIL"
+            if n_bad or bad:
+                ok_all = False
+            if f_init == 0:
+                print(f"  {status} {name:4} 65,536/65,536 operand pairs exact"
+                      + ("" if n_bad == 0 else f"  ({n_bad} mismatches)"))
+
+    # ---- 2. exhaustive control-flow sweeps ----------------------------------
+    print("\n[2/4] Exhaustive control-flow sweeps")
+    cases = []
+    for cnd in range(8):                     # all Jcc x all flag nibbles
+        for f in range(16):
+            prog = _instr(0xD, imm=cnd) + [0x00, 0x08] + _instr(0xF) + [0] * 2 + _instr(0xF)
+            cases.append(_mk_state(mem=prog, flags=[(f >> (3 - i)) & 1 for i in range(4)]))
+    for t in range(16):                      # all JMP targets
+        prog = _instr(0xC) + [0x00, t]
+        cases.append(_mk_state(mem=prog))
+    for spv in range(16):                    # CALL: every SP value
+        prog = _instr(0xE) + [0x00, 0x06] + [0, 0] + _instr(0xF)
+        cases.append(_mk_state(mem=prog, sp=spv))
+    for ad in range(16):                     # LOAD/STORE: every address
+        prog = _instr(0xA, rd=2) + [0x00, ad]
+        st = _mk_state(mem=prog)
+        st["mem"][ad] |= 0xA5 if ad >= 4 else st["mem"][ad]
+        cases.append(st)
+        prog = _instr(0xB, rs=1) + [0x00, ad]
+        cases.append(_mk_state(mem=prog, regs=(0, 0x5A, 0, 0)))
+    V = torch.stack([state_to_vec(s) for s in cases]).to(device)
+    V = mm.step(V).cpu()
+    bad = sum(1 for i, s in enumerate(cases) if vec_to_state(V[i]) != ref_step(s))
+    print(f"  {'OK ' if bad == 0 else 'FAIL'} {len(cases)} directed cases "
+          f"(8 Jcc x 16 flag sets, 16 JMP targets, 16 CALL SPs, 32 LOAD/STORE) exact")
+    ok_all &= bad == 0
+
+    # ---- 3. random-state fuzz + halt fixed point -----------------------------
+    print("\n[3/4] Random-state fuzz (single step vs integer reference)")
+    gen = torch.Generator().manual_seed(0xC0FFEE)
+    Vr = (torch.rand(2000, STATE_BITS, generator=gen) < 0.5).float()
+    Vr[:, MatrixMachine.HALT_IDX] = 0.0
+    out = mm.step(Vr.to(device)).cpu()
+    bad = sum(1 for i in range(Vr.shape[0])
+              if vec_to_state(out[i]) != ref_step(vec_to_state(Vr[i])))
+    print(f"  {'OK ' if bad == 0 else 'FAIL'} 2,000 uniformly random full states exact")
+    ok_all &= bad == 0
+    Vh = (torch.rand(500, STATE_BITS, generator=gen) < 0.5).float()
+    Vh[:, MatrixMachine.HALT_IDX] = 1.0
+    outh = mm.step(Vh.to(device)).cpu()
+    fixed = bool((outh == Vh.to(outh.device)).all())
+    print(f"  {'OK ' if fixed else 'FAIL'} 500 halted states are exact fixed points")
+    ok_all &= fixed
+
+    # ---- 4. lockstep vs the gate-graph processor (shipped weights) ----------
+    print("\n[4/4] Instruction lockstep vs GenericThresholdCPU on "
+          "neural_computer8_registers (the gate graph)")
+    from eval_all import GenericThresholdCPU
+    T = {}
+    with safe_open(GATE_MODEL_PATH, framework="pt") as f:
+        for nm in f.keys():
+            T[nm] = f.get_tensor(nm).float()
+    gcpu = GenericThresholdCPU(T)
+    progs = [
+        ("alu_chain", _mk_state(mem=_instr(0, 0, 1) + _instr(7, 2, 0) + _instr(9, 2, 1)
+                                + _instr(4, 1, 2) + _instr(0xF),
+                                regs=(9, 5, 3, 0))),
+        ("div_by_zero", _mk_state(mem=_instr(8, 0, 1) + _instr(0xF), regs=(77, 0, 0, 0))),
+        ("load_store", _mk_state(mem=_instr(0xA, rd=3) + [0x00, 0x0E]
+                                 + _instr(0xB, rs=3) + [0x00, 0x0F] + _instr(0xF)
+                                 + [0] * 4 + [0xB7, 0x00],
+                                 )),
+        ("call", _mk_state(mem=_instr(0xE) + [0x00, 0x06] + _instr(0xF)
+                           + _instr(0xF), sp=0xF)),
+        ("jcc_taken", _mk_state(mem=_instr(0xD, imm=1) + [0x00, 0x06] + _instr(0xF)
+                                + _instr(0xF), flags=(0, 0, 0, 0))),
+        ("shift_mul", _mk_state(mem=_instr(5, 0) + _instr(6, 1) + _instr(7, 0, 1)
+                                + _instr(0xF), regs=(0x81, 0x81, 0, 0))),
+    ]
+    for name, st0 in progs:
+        sm = dict(st0)
+        sg = {"pc": st0["pc"], "regs": list(st0["regs"]), "flags": list(st0["flags"]),
+              "mem": list(st0["mem"]), "halted": False, "sp": st0["sp"]}
+        good = True
+        for _ in range(12):
+            if sm["halted"]:
+                break
+            sm, _n = mm.run(sm, max_cycles=1)
+            sg = gcpu.step(sg)
+            match = (sm["pc"] == sg["pc"] and sm["regs"] == sg["regs"]
+                     and sm["flags"] == sg["flags"] and sm["mem"] == sg["mem"]
+                     and sm["halted"] == sg["halted"]
+                     and sm["sp"] == sg.get("sp", MEM_BYTES - 1))
+            if not match:
+                good = False
+                break
+        good = good and sm["halted"]
+        print(f"  {'OK ' if good else 'FAIL'} {name}: full-state lockstep, every instruction")
+        ok_all &= good
+
+    print("\nMATRIX == GATE GRAPH == REFERENCE:", "PASS" if ok_all else "FAIL")
+    return ok_all
+
+
+# =============================================================================
+# Analog realization
+# =============================================================================
+
+def analog(mm: MatrixMachine, device: str) -> bool:
+    ok = True
+    print("\nAnalog crossbar simulation "
+          "(comparator at -0.5; ternary conductances are exact by construction)")
+
+    gen = torch.Generator().manual_seed(7)
+    Vr = (torch.rand(512, STATE_BITS, generator=gen) < 0.5).float().to(device)
+    margin = mm.min_margin(Vr)
+    print(f"  measured minimum |pre-activation - (-0.5)| over 512 random states, "
+          f"all layers: {margin:.3f} (guarantee: 0.5)")
+    ok &= abs(margin - 0.5) < 1e-6
+
+    prog = (_instr(0, 0, 1) + _instr(7, 2, 0) + _instr(9, 2, 1) + _instr(0xF))
+    st0 = _mk_state(mem=prog, regs=(9, 5, 3, 0))
+    ref_final, _ = mm.run(dict(st0), max_cycles=8)
+
+    import math
+    rows_per_step = sum(int(W.shape[0]) for W in mm.W)
+    n_steps = 4
+    print(f"  Gaussian read noise per MVM ({rows_per_step:,} comparator "
+          f"decisions per instruction; flip iff |noise| >= 0.5):")
+    for sigma in (0.05, 0.08, 0.10, 0.15, 0.25, 0.45):
+        p_flip = math.erfc(0.5 / (sigma * math.sqrt(2.0)))
+        exp_flips = p_flip * rows_per_step * n_steps
+        exact = 0
+        for t in range(20):
+            g = torch.Generator(device=device).manual_seed(1000 + t)
+            v = state_to_vec(st0).unsqueeze(0).to(device)
+            for _ in range(8):
+                if v[0, MatrixMachine.HALT_IDX] >= 0.5:
+                    break
+                v = mm.step(v, analog=True, noise_sigma=sigma, gen=g)
+            exact += int(vec_to_state(v[0].cpu()) == ref_final)
+        print(f"    sigma={sigma:.2f}: {exact}/20 runs bit-exact "
+              f"(theory: {exp_flips:.2e} expected flips per run)")
+        if exp_flips < 1e-3 and exact != 20:
+            ok = False
+
+    print("  Static ternary-conductance mismatch (device variation, "
+          "10 fabricated instances each):")
+    for sg in (0.02, 0.05, 0.10, 0.20):
+        exact = 0
+        for t in range(10):
+            mmp = mm.perturbed(sg, seed=200 + t)
+            v = state_to_vec(st0).unsqueeze(0).to(device)
+            for _ in range(8):
+                if v[0, MatrixMachine.HALT_IDX] >= 0.5:
+                    break
+                v = mmp.step(v, analog=True)
+            exact += int(vec_to_state(v[0].cpu()) == ref_final)
+        print(f"    sigma_G={sg:.2f}: {exact}/10 instances bit-exact")
+        if sg <= 0.02 and exact != 10:
+            ok = False
+
+    print("ANALOG REALIZATION:", "PASS (bit-exact within the stated margins)"
+          if ok else "FAIL")
+    return ok
+
+
+# =============================================================================
+# CLI
+# =============================================================================
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="neural_matrix8 builder/verifier")
+    ap.add_argument("cmd", choices=["build", "verify", "analog", "all"])
+    ap.add_argument("--device", default="cuda" if torch.cuda.is_available() else "cpu")
+    args = ap.parse_args()
+
+    rc = 0
+    layers = None
+    if args.cmd in ("build", "all"):
+        layers, _ = build(save=True)
+    if args.cmd in ("verify", "analog", "all"):
+        if layers is not None:
+            mm = MatrixMachine(layers, device=args.device)
+        elif os.path.exists(MODEL_PATH):
+            mm = MatrixMachine.from_file(MODEL_PATH, device=args.device)
+        else:
+            layers, _ = build(save=False)
+            mm = MatrixMachine(layers, device=args.device)
+        if args.cmd in ("verify", "all"):
+            rc |= 0 if verify(mm, args.device) else 1
+        if args.cmd in ("analog", "all"):
+            rc |= 0 if analog(mm, args.device) else 1
+    return rc
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/test_play.py

@@ -15,8 +15,9 @@ import unittest
 from contextlib import redirect_stdout
 
 REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-if REPO_ROOT not in sys.path:
-    sys.path.insert(0, REPO_ROOT)
+for _p in (REPO_ROOT, os.path.join(REPO_ROOT, "tools")):  # play.py lives in tools/
+    if _p not in sys.path:
+        sys.path.insert(0, _p)
 
 import play  # noqa: E402
 

todo.md

@@ -9,13 +9,3 @@ Unfinished work.
 - The standalone float normalize stages, superseded by the composed pipelines' own normalizers, are removed from the circuit inventory.
 - Every gate in the 32-bit multiply circuit resolves its .inputs to a defined signal.
 - A machine-checked correctness proof relates the shipped weights to the ISA.
-- The processor's full state transition is expressed as a recurrent ternary threshold network and executes as analog matrix-vector products rather than a wired gate graph.
-  - The verified gate wiring is compiled into a fixed sequence of ternary weight matrices W1..Wk with a Heaviside step between them, acting on a state vector that holds the program counter, registers, flags, and every memory bit.
-  - One instruction is that fixed stack of threshold layers, and the machine is the stack iterated until the halt bit sets, so the whole processor is a single recurrent linear-threshold network.
-  - The matrix form is proven equal to the gate-graph processor, so the ISA semantics carry over bit for bit.
-  - Each weight matrix maps to a resistive or photonic crossbar with conductances drawn from {-1, 0, +1}, and one clock cycle is one analog matrix-vector product followed by thresholding.
-  - The analog realization is shown to reproduce the digital circuit within the device's conductance-quantization and noise margins.
-- A program running on the processor emits the exact tensor file that defines that processor, and builds any other machine in the family from a description of it.
-  - The program's output stream is the byte-for-byte safetensors file of the running machine, and that equality is machine-checked rather than observed on a single run.
-  - The same program takes an encoded description of any machine in the family and constructs that machine's weight file, so the constructor is universal and the description selects what is built.
-  - Self-reproduction is the case where the description handed to the constructor is its own.

build_all.py → tools/build_all.py

@@ -26,7 +26,7 @@ from pathlib import Path
 import torch
 from safetensors import safe_open
 
-ROOT = Path(__file__).resolve().parent
+ROOT = Path(__file__).resolve().parent.parent  # repo root (this file lives in tools/)
 SEED = ROOT / "neural_computer.safetensors"
 OUT_DIR = ROOT / "variants"
 OUT_DIR.mkdir(exist_ok=True)

play.py → tools/play.py

@@ -25,7 +25,8 @@ import sys
 import torch
 from safetensors import safe_open
 
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))  # this file lives in tools/
+sys.path.insert(0, REPO)
 
 # Reuse the variant-aware CPU runtime from eval_all.py
 from eval_all import GenericThresholdCPU, builtin_program
@@ -47,8 +48,7 @@ def main() -> int:
     parser = argparse.ArgumentParser(description="Threshold computer playground")
     parser.add_argument(
         "--model", type=str,
-        default=os.path.join(os.path.dirname(__file__),
-                             "variants", "neural_computer8_small.safetensors"),
+        default=os.path.join(REPO, "variants", "neural_computer8_small.safetensors"),
         help="Path to a .safetensors variant"
     )
     parser.add_argument("--skip-cpu", action="store_true",

prune_weights.py → tools/prune_weights.py

@@ -7,10 +7,13 @@ Phase 2: Apply all successes at once, binary search if conflicts
 
 import argparse
 import os
+import sys
 import time
 
 import torch
 from safetensors.torch import save_file
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))  # repo root
 from eval import BatchedFitnessEvaluator, create_population, load_model
 
 torch.manual_seed(0)

test_cpu.py → tools/test_cpu.py

@@ -20,7 +20,9 @@ from pathlib import Path
 import torch
 from safetensors import safe_open
 
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))  # this file lives in tools/
+sys.path.insert(0, REPO)                    # eval_all lives at the repo root
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))  # cpu_programs is a sibling
 from eval_all import GenericThresholdCPU, get_manifest
 from cpu_programs import SUITE
 
@@ -61,8 +63,7 @@ def main() -> int:
     parser = argparse.ArgumentParser(description="Run the CPU program suite")
     parser.add_argument(
         "--model", type=str,
-        default=os.path.join(os.path.dirname(__file__),
-                             "variants", "neural_computer8_small.safetensors"),
+        default=os.path.join(REPO, "variants", "neural_computer8_small.safetensors"),
         help="Path to .safetensors variant",
     )
     parser.add_argument(

variants/neural_matrix8.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:837e5984345ad36af3d4297413046690665751db3567f9c7c33f698e33cf5d3b
+size 9523232

variants/neural_subleq8io.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7744f8ba85916ab705f8e608cc49ca9150e3eac2dc5dbbe6c7682acdb16df93a
+size 95306